### Install Requests Library

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Install the required 'requests' library for the Python script environment.

```bash
pip install requests
```

--------------------------------

### Interactive CLI Example: Directory and File Operations

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Demonstrates common interactive commands like changing directory, creating a folder, uploading a file, and downloading it.

```text
/> cd demo
无效命令，使用 '..' 返回上级，'/' 返回根目录，或输入文件夹编号
/> cd 1     
当前目录为空  
/demo1> ls  
当前目录为空  
/demo1> mkdir test  
目录 'test' 创建成功  

/demo1> 1  
当前目录为空  
/demo1/test> upload 123pan.py  
上传进度: 100.0%
上传完成，正在验证...  
文件上传成功  
------------------------------------------------------------  
编号    类型      大小          名称  
------------------------------------------------------------  
1     文件      38.66 KB    123pan.py  
============================================================  

/demo1/test> 1  
开始下载: 123pan.py  
进度: 100.0% | 38.66 KB/38.66 KB | 10.29 MB/s        
下载完成: 123pan.py  
/demo1/test>
```

--------------------------------

### 123Pan Configuration File Example

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Example JSON structure for the configuration file, storing login and device preferences. Be cautious about storing sensitive information like passwords or tokens locally.

```json
{
  "userName": "your_username",
  "passWord": "your_password",
  "authorization": "Bearer xxxxx",
  "deviceType": "M2007J20CI",
  "osVersion": "Android_10",
  "protocol": "android"
}
```

--------------------------------

### Run 123Pan CLI Script

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Execute the main CLI script. It will prompt for credentials or use a configuration file.

```bash
python pan123_cli.py
```

--------------------------------

### Initialize and Login with 123pan Core

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Initializes the Pan123Core object for Android protocol and logs in. Raises an exception if login fails. Requires user credentials and protocol type.

```python
import json

from pan123_core import Pan123Core, Pan123Tool, Pan123EventType, format_size

# Initialize core object (Android protocol)
core = Pan123Core(
    user_name="13800138000",
    password="your_password",
    protocol=Pan123Core.PROTOCOL_ANDROID
)

# Login
result = core.login()
if result["code"] != 0:
    raise Exception("Login failed")

# Create tool class instance
tool = Pan123Tool(core)
```

--------------------------------

### Download a File with Progress Callback

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Downloads a single file using the tool instance. It specifies the file index, save directory, and a progress callback function. The callback prints download progress percentage.

```python
# Download a file
result = tool.download_file(
    index=0,
    save_dir="downloads",
    on_progress=lambda e: print(f"下载进度: {e['percent']:.2f}%")
)
```

--------------------------------

### Configuration Management

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Methods for loading and saving configuration settings.

```APIDOC
## Configuration Management

### Description
Provides methods to manage the application's configuration by loading from and saving to files.

### Methods

#### `load_config_from_file()`

*   **Description**: Loads configuration settings from a file.
*   **Parameters**: None
*   **Return Type**: Result

#### `save_config_to_file()`

*   **Description**: Saves the current configuration settings to a file.
*   **Parameters**: None
*   **Return Type**: Result
```

--------------------------------

### Configuration Management

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Methods for managing the client's configuration, including loading settings and setting the protocol.

```APIDOC
## load_config(cfg)

### Description
Loads configuration from a dictionary and updates the instance state.

### Method
load_config(cfg)

### Parameters
- **cfg** (dict) - Required - A dictionary containing account information.

### Response
- **Result**: Type indicating the outcome of loading the configuration.
```

```APIDOC
## get_current_config()

### Description
Retrieves the current configuration, including account details, token, and protocol.

### Method
get_current_config()

### Parameters
None

### Response
- **dict**: A dictionary containing the current configuration.
```

```APIDOC
## set_protocol(protocol)

### Description
Switches the request protocol between 'android' and 'web'.

### Method
set_protocol(protocol)

### Parameters
- **protocol** (str) - Required - The desired protocol ('android' or 'web').

### Response
- **Result**: Type indicating the outcome of setting the protocol.
```

--------------------------------

### Create a Shared Link for Files

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Creates a shareable link for specified file IDs. It allows setting a password and an expiration date for the link. Requires a list of file IDs.

```python
# Create a share link
result = core.share(
    file_ids=[12345],
    share_pwd="123456",
    expiration="2026-12-31T23:59:59+08:00"
)
```

--------------------------------

### File Download

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Methods for downloading single files or entire directories.

```APIDOC
## File Download

### Description
Enables downloading of individual files or entire directory structures from the service.

### Methods

#### `download_file(index, save_dir="download", on_progress=None, overwrite=False, skip_existing=False)`

*   **Description**: Downloads a single file specified by its index.
*   **Parameters**:
    *   `index` (int) - Required - The index of the file to download.
    *   `save_dir` (str) - Optional - The directory to save the downloaded file. Defaults to "download".
    *   `on_progress` (callable) - Optional - A callback function to report download progress.
    *   `overwrite` (bool) - Optional - Whether to overwrite the file if it already exists. Defaults to False.
    *   `skip_existing` (bool) - Optional - Whether to skip downloading if the file already exists. Defaults to False.
*   **Return Type**: Result

#### `download_directory(directory, save_dir="download", on_progress=None, overwrite=False, skip_existing=False)`

*   **Description**: Recursively downloads a directory and its contents.
*   **Parameters**:
    *   `directory` (dict) - Required - Information about the directory to download.
    *   `save_dir` (str) - Optional - The directory to save the downloaded contents. Defaults to "download".
    *   `on_progress` (callable) - Optional - A callback function to report download progress.
    *   `overwrite` (bool) - Optional - Whether to overwrite files if they already exist. Defaults to False.
    *   `skip_existing` (bool) - Optional - Whether to skip downloading files if they already exist. Defaults to False.
*   **Return Type**: Result
```

--------------------------------

### Directory Operations

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Methods for navigating and managing directories on the 123pan service.

```APIDOC
## list_dir(parent_id=None, page=1, limit=100)

### Description
Retrieves a paginated list of files and directories within a specified parent directory.

### Method
list_dir(parent_id=None, page=1, limit=100)

### Parameters
- **parent_id** (int) - Optional - The ID of the parent directory. Defaults to the current directory.
- **page** (int) - Optional - The page number for the file list. Defaults to 1.
- **limit** (int) - Optional - The maximum number of items per page. Defaults to 100.

### Response
- **Result**: Type containing the file list for the specified page.
```

```APIDOC
## list_dir_all(parent_id=None, limit=100)

### Description
Retrieves all files and directories within a specified parent directory, handling pagination automatically.

### Method
list_dir_all(parent_id=None, limit=100)

### Parameters
- **parent_id** (int) - Optional - The ID of the parent directory. Defaults to the current directory.
- **limit** (int) - Optional - The maximum number of items per page for internal requests. Defaults to 100.

### Response
- **Result**: Type containing the complete file list.
```

```APIDOC
## mkdir(name)

### Description
Creates a new subdirectory within the current directory.

### Method
mkdir(name)

### Parameters
- **name** (str) - Required - The name of the new directory to create.

### Response
- **Result**: Type indicating the outcome of the directory creation.
```

```APIDOC
## cd(folder_index)

### Description
Enter a target folder within the current directory's file list.

### Method
cd(folder_index)

### Parameters
- **folder_index** (int) - Required - The index of the target folder in the `file_list`.

### Response
- **Result**: Type indicating the outcome of changing the directory.
```

```APIDOC
## cd_up()

### Description
Navigates to the parent directory.

### Method
cd_up()

### Parameters
None

### Response
- **Result**: Type indicating the outcome of moving to the parent directory.
```

```APIDOC
## cd_root()

### Description
Navigates to the root directory.

### Method
cd_root()

### Parameters
None

### Response
- **Result**: Type indicating the outcome of moving to the root directory.
```

```APIDOC
## trash(file_data, delete=True)

### Description
Deletes a file or restores it from the trash.

### Method
trash(file_data, delete=True)

### Parameters
- **file_data** (dict) - Required - A dictionary containing the file's information.
- **delete** (bool) - Optional - If True, deletes the file. If False, restores it from trash. Defaults to True.

### Response
- **Result**: Type indicating the outcome of the trash operation.
```

```APIDOC
## list_recycle()

### Description
Retrieves a list of files currently in the recycle bin.

### Method
list_recycle()

### Parameters
None

### Response
- **Result**: Type containing the list of files in the recycle bin.
```

--------------------------------

### Authentication Operations

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Methods for logging in, logging out, checking login status, and clearing account information.

```APIDOC
## login()

### Description
Logs into the 123pan service using the provided user name and password.

### Method
login()

### Parameters
None

### Response
- **Result**: Type indicating the outcome of the login operation.
```

```APIDOC
## logout()

### Description
Logs out of the 123pan service and clears the authentication token.

### Method
logout()

### Parameters
None

### Response
- **Result**: Type indicating the outcome of the logout operation.
```

```APIDOC
## check_login()

### Description
Checks if the current authentication token is valid.

### Method
check_login()

### Parameters
None

### Response
- **Result**: Type indicating the validity of the current login status.
```

```APIDOC
## clear_account()

### Description
Clears account information without saving configuration.

### Method
clear_account()

### Parameters
None

### Response
- **Result**: Type indicating the outcome of clearing account information.
```

--------------------------------

### Upload a File with Overwrite Option

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Uploads a local file using the core object. It allows specifying the file path, a duplicate flag to control overwriting behavior (1 means overwrite), and an optional progress callback.

```python
# Upload a file
result = core.upload_file(
    file_path="local_file.txt",
    duplicate=1,  # Overwrite existing file
    on_progress=None  # ...
)
```

--------------------------------

### User Information

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Methods for retrieving information about the currently logged-in user.

```APIDOC
## get_user_info()

### Description
Retrieves detailed information about the current user, including UID, nickname, and storage usage.

### Method
get_user_info()

### Parameters
None

### Response
- **Result**: Type containing the current user's information.
```

--------------------------------

### File Operations

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Methods for uploading, downloading, and sharing files on the 123pan service.

```APIDOC
## upload_file(file_path, duplicate=0, on_progress=None)

### Description
Uploads a local file to the 123pan service. If a directory path is provided, it will recursively upload its contents.

### Method
upload_file(file_path, duplicate=0, on_progress=None)

### Parameters
- **file_path** (str) - Required - The local path to the file or directory to upload.
- **duplicate** (int) - Optional - Strategy for handling duplicate files: 0=error, 1=overwrite, 2=keep. Defaults to 0.
- **on_progress** (callable) - Optional - A callback function to report upload progress.

### Response
- **Result**: Type indicating the outcome of the file upload.
```

```APIDOC
## upload_directory(dir_path, duplicate=0, on_progress=None)

### Description
Uploads a local directory to the 123pan service, preserving the directory structure.

### Method
upload_directory(dir_path, duplicate=0, on_progress=None)

### Parameters
- **dir_path** (str) - Required - The local path to the directory to upload.
- **duplicate** (int) - Optional - Strategy for handling duplicate files: 0=error, 1=overwrite, 2=keep. Defaults to 0.
- **on_progress** (callable) - Optional - A callback function to report upload progress.

### Response
- **Result**: Type indicating the outcome of the directory upload.
```

```APIDOC
## get_download_url(index)

### Description
Generates a direct download URL for a file listed in the current directory.

### Method
get_download_url(index)

### Parameters
- **index** (int) - Required - The index of the file in the `file_list` for which to get the download URL.

### Response
- **Result**: Type containing the direct download URL for the file.
```

```APIDOC
## share(file_ids, share_pwd="", expiration="2099-12-12T08:00:00+08:00")

### Description
Creates a share link for specified files with an optional password and expiration date.

### Method
share(file_ids, share_pwd="", expiration="2099-12-12T08:00:00+08:00")

### Parameters
- **file_ids** (list) - Required - A list of file IDs to share.
- **share_pwd** (str) - Optional - The password for the share link. Defaults to an empty string.
- **expiration** (str) - Optional - The expiration date and time for the share link in ISO format. Defaults to '2099-12-12T08:00:00+08:00'.

### Response
- **Result**: Type containing information about the created share link.
```

--------------------------------

### File Upload

Source: https://github.com/bao-qing/123pan/blob/master/README.md

Method for uploading files or folders.

```APIDOC
## File Upload

### Description
Uploads a file or a folder to the service. This method is consistent with the `Pan123Core.upload_file` method.

### Method

#### `upload_file(file_path, duplicate=0, on_progress=None)`

*   **Description**: Uploads a local file or folder to the service.
*   **Parameters**:
    *   `file_path` (str) - Required - The path to the local file or folder to upload.
    *   `duplicate` (int) - Optional - Specifies how to handle duplicates. `0` typically means do not upload if exists, `1` means overwrite. Defaults to `0`.
    *   `on_progress` (callable) - Optional - A callback function to report upload progress.
*   **Return Type**: Result
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.