### Complete Example with Error Handling

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Provides a comprehensive example demonstrating best practices for handling errors during API interactions.

```python
import pywencai
import logging

logging.basicConfig(level=logging.ERROR)

# Complete example with error handling
try:
    data = pywencai.get(query='INVALID_QUERY')
    if data.empty:
        print("No data returned.")
    else:
        print(data)
except pywencai.exceptions.PyWencaiError as e:
    logging.error(f"PyWencai API error: {e}")
except Exception as e:
    logging.error(f"An unexpected error occurred: {e}")

```

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

### Basic Stock Query

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Demonstrates a basic query for stock data using the get API.

```python
import pywencai

# Basic query for stocks
stocks = pywencai.get(query='AAPL', report_type='stock')
print(stocks)
```

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

### Fetch Additional Component Data

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Example showing how to fetch additional component data, possibly related to API responses.

```python
import pywencai

# Fetch additional component data
# component_data = pywencai.get_component_data(component_id='XYZ')
# print(component_data)
```

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

### Configuring Proxy for Network Requests

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/configuration.md

This example shows how to configure proxy settings for requests. It defines proxy addresses and includes them in the request parameters along with a timeout.

```python
proxies = {
    'http': 'http://proxy.company.com:8080',
    'https': 'http://proxy.company.com:8080'
}

result = pywencai.get(
    query='融资余额',
    cookie='xxx',
    request_params={'proxies': proxies, 'timeout': 30}
)
```

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

### Use Paid API Features

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Example of utilizing paid API features, which may require specific parameters or authentication.

```python
import pywencai

# Use paid API features
paid_data = pywencai.get(
    query='AAPL',
    report_type='stock',
    paid_feature=True,  # Example parameter for a paid feature
    api_key='YOUR_PAID_API_KEY'
)
print(paid_data)
```

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

### Verify Node.js Version

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/configuration.md

Check if the installed Node.js version meets the minimum requirement of v16. This command is essential for ensuring the `hexin-v.bundle.js` can be executed correctly.

```bash
node --version
# Should output: v16.x.x or higher
```

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

### API Response Example (Empty Results)

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/errors.md

This JSON structure shows a successful API response (200 OK) but with an empty 'datas' array, indicating no matching securities were found for the query.

```json
{
    "answer": {
        "components": [
            {
                "data": {
                    "datas": []
                }
            }
        ]
    }
}
```

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

### get_url

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Fetches component data from an additional endpoint by constructing a full URL and making a GET request.

```APIDOC
## get_url

### Description
Fetches component data from an additional endpoint by constructing a full URL and making a GET request. It then parses and returns the JSON response.

### Method
```python
def get_url(url: str) -> dict | Any
```

### Behavior
1. Constructs full URL: `http://www.iwencai.com{url}` (prepends domain)
2. Sends GET request with headers (no authentication cookie)
3. Parses JSON response
4. Returns `data` field from response

### Used by
`wiki1_handler`, `nestedblocks_handler` for fetching related components

### Code Example
```python
from pywencai.convert import get_url

data = get_url('/some/endpoint/path')
```
```

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

### Fetch Data from URL

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Fetches component data from an additional endpoint by constructing a full URL and sending a GET request. It parses the JSON response and returns the 'data' field.

```python
from pywencai.convert import get_url

data = get_url('/some/endpoint/path')
```

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

### PyWencai Public API - get()

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/GENERATION_SUMMARY.txt

The primary public function for interacting with the PyWencai API. It allows users to fetch data with various configuration options.

```APIDOC
## get()

### Description
This is the main public function of the PyWencai library, designed for fetching data. It supports numerous configuration parameters for customizing requests and handling responses.

### Method
N/A (Python function)

### Endpoint
N/A (Python function, but accesses internal HTTP endpoints)

### Parameters
This function accepts 15 documented parameters, including logger configuration, environment setup, dependency specifications, and cookie acquisition details. Specific parameter names, types, defaults, and descriptions are available in the detailed `api-reference/get.md` documentation.

### Request Example
```python
# Example usage (details in source)
import pywencai

# Assuming necessary configuration is set up
result = pywencai.get(query='some query', params={'key': 'value'})
```

### Response
- **Success Response**: The function returns data based on the query and configuration. Specific return types and structures are documented in `api-reference/get.md`.

#### Response Example
```json
{
  "data": [
    // ... returned data ...
  ],
  "status": "success"
}
```

### Error Handling
Covers network request failures, invalid authentication, rate limiting, malformed responses, timeouts, and more, as detailed in the `errors.md` document.
```

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

### FileNotFoundError: Node.js Not Found

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/errors.md

This error occurs when the 'node' command is not found in the system's PATH or Node.js is not installed. Ensure Node.js v16+ is installed and accessible.

```text
FileNotFoundError: [Errno 2] No such file or directory: 'node'
```

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

### Pywencai get function

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/README.md

The primary function `pywencai.get` allows users to query Wencai data using natural language. It supports various parameters for customization, including sorting, pagination, and error handling.

```APIDOC
## pywencai.get

### Description
This function retrieves data from Wencai based on a natural language query. It offers extensive customization options for fetching, sorting, and processing results.

### Method
```python
def get(
    query: str,                          # Required: natural language question
    cookie: str,                         # Required: authentication
    sort_key: str = None,                # Optional: column to sort by
    sort_order: str = None,              # Optional: 'asc' or 'desc'
    page: int = 1,                       # Optional: starting page
    perpage: int = 100,                  # Optional: records per page (max 100)
    loop: bool | int = False,            # Optional: pagination (True=all, n=n pages)
    query_type: str = 'stock',           # Optional: asset type
    retry: int = 10,                     # Optional: retry attempts
    sleep: float = 0,                    # Optional: delay between requests
    log: bool = False,                   # Optional: enable logging
    pro: bool = False,                   # Optional: use paid API
    no_detail: bool = False,             # Optional: ensure DataFrame return
    find: list = None,                   # Optional: prioritize security codes
    user_agent: str = None,              # Optional: custom User-Agent
    request_params: dict = None          # Optional: additional requests params
) -> pandas.DataFrame | dict | None
```

### Parameters
#### Required Parameters
- **query** (str) - Required - A natural language question to query Wencai.
- **cookie** (str) - Required - Authentication token for Wencai.

#### Optional Parameters
- **sort_key** (str) - Optional - The column name to sort the results by.
- **sort_order** (str) - Optional - The order of sorting, either 'asc' or 'desc'.
- **page** (int) - Optional - The starting page number for the query. Defaults to 1.
- **perpage** (int) - Optional - The number of records to retrieve per page. Maximum is 100.
- **loop** (bool | int) - Optional - Controls pagination. If `True`, fetches all pages. If an integer `n`, fetches `n` pages. Defaults to `False`.
- **query_type** (str) - Optional - The type of asset to query. Defaults to 'stock'. Supported types include: 'stock', 'fund', 'zhishu', 'hkstock', 'usstock', 'threeboard', 'conbond', 'insurance', 'futures', 'lccp', 'foreign_exchange'.
- **retry** (int) - Optional - The number of retry attempts in case of failure. Defaults to 10.
- **sleep** (float) - Optional - The delay in seconds between requests, useful for rate limiting. Defaults to 0.
- **log** (bool) - Optional - Enables logging of progress and debug information. Defaults to `False`.
- **pro** (bool) - Optional - Use the paid API version. Defaults to `False`.
- **no_detail** (bool) - Optional - Ensures the return type is a pandas DataFrame. Defaults to `False`.
- **find** (list) - Optional - A list of security codes to prioritize in the search.
- **user_agent** (str) - Optional - A custom User-Agent string for the requests.
- **request_params** (dict) - Optional - Additional parameters to pass to the underlying requests library.

### Return Value
- Returns a pandas.DataFrame, dict, or None. Returns `None` if the query fails due to network, authentication, or if no results are found.

### Error Handling
- **Returns `None`**: Indicates a network issue, authentication failure, or no matching results. Refer to `errors.md` for details.
- **`FileNotFoundError: node`**: Occurs if Node.js is not installed. Install Node.js v16 or later.
- **Invalid session (401/403)**: Caused by an invalid or expired cookie. Refresh the cookie from Wencai.
- **Rate limited (403)**: Indicates too many requests. Use the `sleep` parameter to introduce delays between requests.
```

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

### Get Page Data

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Utilizes the internal get_page function to retrieve data from a specific page.

```python
import pywencai

# Example for get_page()
page_data = pywencai.get_page(url_params={'query': 'example'})
print(page_data)
```

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

### API Response Example (401 Unauthorized)

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/errors.md

This JSON structure represents an API response indicating an invalid session or unauthorized access, often resulting in a 'None' return from pywencai functions.

```json
{
    "error_code": "1001",
    "error_msg": "Invalid session",
    "data": null
}
```

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

### Internal HTTP Endpoints

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/GENERATION_SUMMARY.txt

The PyWencai library interacts with 4 internal HTTP endpoints. These are accessed by the public `get()` function and are fully documented in the API reference.

```APIDOC
## Internal HTTP Endpoints

### Description
The PyWencai library utilizes several internal HTTP endpoints to perform its operations. These endpoints are not directly exposed to the user but are integral to the functionality of the public `get()` method.

### Method
Details on HTTP methods (GET, POST, etc.) for each specific endpoint are documented in the `api-reference/` directory.

### Endpoint
There are 4 distinct HTTP endpoints accessed by the library. The exact paths are specified in the detailed API reference.

### Parameters
Parameters for these endpoints include path parameters, query parameters, and request bodies, all of which are documented with their types, requirements, and descriptions in the source code analysis.

### Request Example
(Specific examples for each endpoint are available in the detailed API reference documentation.)

### Response
Responses from these endpoints are handled by 13 different response handler types, ensuring accurate parsing and data extraction. Success and error responses, along with their structures, are documented.
```

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

### Query with Proxy and Custom Headers

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Demonstrates how to configure proxy settings and custom headers for API requests.

```python
import pywencai

# Query with proxy and custom headers
custom_headers = {
    'User-Agent': 'MyCustomUserAgent/1.0',
    'X-Custom-Header': 'Value'
}
proxies = {
    'http': 'http://user:password@host:port',
    'https': 'https://user:password@host:port',
}

proxied_data = pywencai.get(
    query='AAPL',
    report_type='stock',
    proxies=proxies,
    headers=custom_headers
)
print(proxied_data)
```

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

### Basic pywencai Usage with Cookie

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/configuration.md

Demonstrates how to use the `pywencai.get` function with a provided Wencai session cookie. It's recommended to manage cookies securely, not by hardcoding them directly in source code.

```python
import pywencai
cookie = 'sessionid=abc123...; path=/; Domain=.iwencai.com'
result = pywencai.get(query='...', cookie=cookie)
```

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

### Get Robot Data

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Calls the internal get_robot_data function, likely for specific robot-related information.

```python
import pywencai

# Example for get_robot_data()
robot_data = pywencai.get_robot_data(param1='value1')
print(robot_data)
```

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

### Stock Query with Sorting and Pagination

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Shows how to query stock data with specified sorting and pagination parameters.

```python
import pywencai

# Query with sorting and pagination
sorted_stocks = pywencai.get(
    query='AAPL',
    report_type='stock',
    start_date='2023-01-01',
    end_date='2023-12-31',
    order='desc',  # or 'asc'
    page_size=100,
    page=1
)
print(sorted_stocks)
```

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

### Basic Query with pywencai

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/README.md

Fetches financial data for a given query. Requires a valid Wencai cookie for authentication.

```python
import pywencai

result = pywencai.get(
    query='融资余额',
    cookie='your_wencai_cookie'
)
print(result)  # pandas.DataFrame
```

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

### Missing Bundle File Error

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/errors.md

Occurs when the 'hexin-v.bundle.js' file is missing, leading to authentication failures. Reinstalling pywencai typically resolves this.

```text
data_list is empty!
```

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

### Use show_type_handler()

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Demonstrates the usage of show_type_handler for specific type handling during data conversion.

```python
import pywencai

# Use show_type_handler()
# Assuming 'raw_value' and 'type_info' are defined
# handled_value = pywencai.show_type_handler(raw_value, type_info)
# print(handled_value)
```

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

### Pywencai Header Generation

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Documentation for functions related to constructing HTTP headers for Wencai API requests, including authentication token generation.

```APIDOC
## HTTP Header Generation

### `headers(token: str)`

#### Description
Constructs the necessary request headers, including the authentication token.

#### Parameters
- **token** (str) - Required - The authentication token.

#### Returns
- dict - A dictionary containing the request headers.

### `get_token()`

#### Description
Generates the authentication token, potentially via a Node.js process.

#### Returns
- str - The generated authentication token.
```

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

### Aggressive Configuration for Fast Data Collection

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/configuration.md

This configuration is suitable for rapid data collection when rate limits are not a concern. It enables fetching all pages without delay and increases the number of retries.

```python
result = pywencai.get(
    query='沪深A股',
    cookie='xxx',
    loop=True,        # Fetch all pages
    sleep=0,          # No delay
    retry=20,         # Many retries
    perpage=100
)
```

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

### Fetch All Results with Pagination

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/README.md

Retrieves all available pages of results for a query. Includes options for throttling requests and logging progress.

```python
result = pywencai.get(
    query='沪深A股',
    loop=True,      # Fetch all pages
    sleep=0.5,      # Throttle: 500ms between pages
    log=True,       # Show progress
    cookie='xxx'
)
```

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

### Query with Sorting

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/README.md

Fetches data and sorts the results by a specified key in a given order. Requires a valid Wencai cookie.

```python
result = pywencai.get(
    query='可转债',
    sort_key='收益率',
    sort_order='desc',
    cookie='xxx'
)
```

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

### Error Handling and Result Checking

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/README.md

Demonstrates how to handle potential query failures and check the number of records returned. Includes retry logic for resilience.

```python
result = pywencai.get(
    query='...', 
    retry=15,  # More resilient
    log=True,  # Debug info
    cookie='xxx'
)

if result is None:
    print("Query failed")
elif len(result) == 0:
    print("No matching results")
else:
    print(f"Got {len(result)} records")
```

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

### multi_show_type_handler

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Processes multiple components and returns a merged dictionary. It iterates through components, extracts a key for each, processes it using `show_type_handler`, and adds non-empty results to a merged dictionary.

```APIDOC
## multi_show_type_handler

### Description
Processes multiple components and returns a merged dictionary. It iterates over all components, extracts a key for each using `get_key()`, processes the component via `show_type_handler()`, and adds it to the result dictionary if both the key and value are non-empty. Finally, it returns the merged dictionary.

### Function Signature
```python
def multi_show_type_handler(components: list) -> dict
```

### Parameters
* **components** (list) - A list of component dictionaries to process.

### Returns
* dict - A merged dictionary where keys are component titles and values are their processed data.

### Code Example
```python
from pywencai.convert import multi_show_type_handler

result = multi_show_type_handler(components_list)
# Returns: {'component_title_1': <data>, 'component_title_2': <data>, ...}
```
```

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

### Replace Key in Data

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Demonstrates the use of the internal replace_key function, likely for data transformation.

```python
import pywencai

# Example for replace_key()
original_data = {'old_key': 'value'}
replaced_data = pywencai.replace_key(data=original_data, old_key='old_key', new_key='new_key')
print(replaced_data)
```

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

### Fetch First Page of Data

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/internal-functions.md

Retrieves the first page of results from a paginated endpoint using `get_page`. Ensure you have obtained the necessary `url_params` and `data` from `get_robot_data` and provide your authentication cookie.

```python
from pywencai.wencai import get_robot_data, get_page

params = get_robot_data(query='融资余额', cookie='xxx')
url_params = params['url_params']
data = params['data']

# Fetch first page
df = get_page(url_params, **data, page=1, perpage=100, cookie='xxx')
print(df)
```

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

### get_key

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Extracts a descriptive key for a component, used as a dictionary key. It attempts to extract the key in a specific order from the component dictionary.

```APIDOC
## get_key

### Description
Extracts a descriptive key for a component, which can be used as a dictionary key. The function attempts to retrieve the key by checking `comp['title_config']['data']['h1']`, then `comp['config']['title']`, and finally `comp['show_type']`, returning the first non-None value found.

### Function Signature
```python
def get_key(comp: dict) -> str | None
```

### Parameters
* **comp** (dict) - The component dictionary from which to extract the key.

### Returns
* str | None - The extracted key string, or None if no key could be determined.

### Source
`pywencai/convert.py:140-143`
```

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

### Fetch All Pages of Results

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Retrieves all available pages of results for a given query.

```python
import pywencai

# Fetch all pages of results
all_stocks = pywencai.get(
    query='AAPL',
    report_type='stock',
    start_date='2023-01-01',
    end_date='2023-12-31',
    page=0  # page=0 fetches all pages
)
print(all_stocks)
```

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

### Conservative Configuration for Rate-Limited Environments

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/configuration.md

Use this configuration in environments with strict rate limits. It sets fewer retries and a small delay between requests to avoid being blocked.

```python
result = pywencai.get(
    query='退市股票',
    cookie='xxx',
    retry=5,          # Fewer retries
    sleep=1.0,        # 1 second between requests
    log=True
)
```

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

### Request Parameters Dictionary

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/types.md

Dictionary for configuring requests.request() parameters like proxies, timeout, and SSL verification. Used by get_robot_data() and get_page().

```python
{
    'proxies': dict,          # Proxy configuration
    'timeout': int | tuple,   # Connection/read timeout
    'verify': bool,           # SSL certificate verification
    # ... any requests parameter
}
```

```python
request_params = {
    'proxies': {
        'http': 'http://proxy.example.com:8080',
        'https': 'http://proxy.example.com:8080'
    },
    'timeout': 30,
    'verify': False
}
```

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

### Find Securities with Priority Ordering

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Searches for specific securities and applies priority ordering.

```python
import pywencai

# Find specific securities with priority ordering
priority_securities = pywencai.get(
    query='MSFT',
    report_type='security',
    priority_order=['ticker', 'name']
)
print(priority_securities)
```

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

### Pywencai Internal Functions

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Documentation for internal utility functions that can be called directly for lower-level control or advanced functionality. These include functions for data fetching, pagination, and parameter manipulation.

```APIDOC
## Internal Functions

### `get_robot_data(params: dict)`

#### Description
Initial query endpoint for fetching robot data. It constructs and sends the initial request to the Wencai API.

#### Parameters
- **params** (dict) - Required - Parameters for the initial query.

### `get_page(endpoint: str, params: dict)`

#### Description
Fetches a single page of data from a specified endpoint with given parameters.

#### Parameters
- **endpoint** (str) - Required - The API endpoint to fetch data from.
- **params** (dict) - Required - Parameters for the request.

### `loop_page(initial_params: dict, page_fetcher: callable)`

#### Description
Handles multi-page pagination by repeatedly calling a page fetching function until all data is retrieved.

#### Parameters
- **initial_params** (dict) - Required - The initial parameters for the first request.
- **page_fetcher** (callable) - Required - A function that fetches a single page of data.

### `while_do(condition: callable, action: callable, max_retries: int = 5)`

#### Description
A retry wrapper that executes an action repeatedly as long as a condition is met, with a maximum number of retries.

#### Parameters
- **condition** (callable) - Required - A function that returns True if the action should continue.
- **action** (callable) - Required - The function to execute.
- **max_retries** (int) - Optional - The maximum number of retries allowed.

### `replace_key(data: dict, mapping: dict)`

#### Description
Replaces keys in a dictionary based on a provided mapping.

#### Parameters
- **data** (dict) - Required - The dictionary to modify.
- **mapping** (dict) - Required - A dictionary defining the key replacements.

### `can_loop(response: dict)`

#### Description
Determines if pagination can continue based on the API response.

#### Parameters
- **response** (dict) - Required - The API response dictionary.

#### Returns
- bool - True if pagination can continue, False otherwise.
```

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

### Handle Retries and Logging

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Sets up automatic retries for failed requests and enables logging for debugging.

```python
import pywencai
import logging

# Handle retries and logging
logging.basicConfig(level=logging.INFO)

retried_data = pywencai.get(
    query='AAPL',
    report_type='stock',
    max_retries=3,
    retry_delay=5  # seconds
)
print(retried_data)
```

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

### Generate Headers with Explicit Parameters

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Creates API headers by explicitly providing parameters like cookie and user agent.

```python
import pywencai

# Generate headers with explicit parameters
headers = pywencai.headers(
    cookie='YOUR_COOKIE_STRING',
    user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64)'
)
print(headers)
```

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

### Fetch Data with Specific Codes using 'find'

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/internal-functions.md

Fetches data by prioritizing specific stock codes using the 'find' parameter in `get_page`. This changes the request endpoint and requires 'find' to be a list of strings (codes).

```python
from pywencai.wencai import get_robot_data, get_page

params = get_robot_data(query='融资余额', cookie='xxx')
url_params = params['url_params']
data = params['data']

# Fetch with find
df_find = get_page(
    url_params,
    find=['600519', '000001'],  # Prioritize these codes
    query_type='stock',
    cookie='xxx'
)
```

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

### Enabling Paid Features with Pro Cookie

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/configuration.md

Use this snippet to access premium metrics and features by enabling the paid API. Ensure you have a valid 'pro_cookie'.

```python
result = pywencai.get(
    query='近3个月每日市盈率',  # Premium metric
    cookie='pro_cookie',
    pro=True,         # Enable paid API
    log=True
)
```

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

### wiki1_handler

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Handles wiki-style content. Although currently disabled, if re-enabled, it would extract a URL, fetch the component from that URL, and process it.

```APIDOC
## wiki1_handler

### Description
Handles wiki-style content. This handler is currently disabled but is designed to fetch and process content from a given URL.

### Function Signature
```python
def wiki1_handler(comp: dict, comps: list) -> Any | None
```

### Note
This handler is commented out in the code. If re-enabled, it would:
1. Extract URL from `data.url`.
2. Fetch component from that URL.
3. Process the fetched component.

### Source
`pywencai/convert.py:91-99`
```

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

### Query Specific Pages

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Fetches data for specific page numbers.

```python
import pywencai

# Query specific pages only
specific_pages = pywencai.get(
    query='AAPL',
    report_type='stock',
    start_date='2023-01-01',
    end_date='2023-12-31',
    pages=[1, 3, 5]  # Fetch pages 1, 3, and 5
)
print(specific_pages)
```

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

### Handle Component by Show Type

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Use `show_type_handler` to dispatch component processing to the correct handler based on its `show_type`. It checks the handler registry and falls back to a common handler if the type is unknown.

```python
from pywencai.convert import show_type_handler

result = show_type_handler(component_dict, all_components)
```

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

### get_page

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/internal-functions.md

Fetches a single page of results from the paginated Wencai API endpoint. It supports different retrieval modes based on the 'find' parameter and handles retries and logging.

```APIDOC
## get_page

Fetches a single page of results from the paginated endpoint.

### Method Signature
```python
def get_page(url_params, **kwargs) -> pandas.DataFrame | None
```

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body

- **url_params** (dict) - Required - URL parameters extracted from `get_robot_data()` response
- **retry** (int) - Optional - Retry attempts. Default: 10
- **sleep** (float) - Optional - Sleep between retries. Default: 0
- **log** (bool) - Optional - Enable logging. Default: False
- **cookie** (str) - Required - Authentication cookie
- **user_agent** (str) - Optional - Custom User-Agent. Default: None
- **find** (str | list[str]) - Optional - Security codes to find. List is joined with commas. Changes endpoint. Default: None
- **query_type** (str) - Optional - Asset type for find requests. Default: 'stock'
- **request_params** (dict) - Optional - Additional requests parameters. Default: {}
- **pro** (bool) - Optional - Use paid API (appends `?iwcpro=1` to URL). Default: False
- **page** (int) - Optional - Page number to fetch. Default: 1
- **perpage** (int) - Optional - Records per page. Default: 100
- **Additional** - All kwargs passed to request data

### Return Type

**pandas.DataFrame** containing the page results with columns from Wencai API, or `None` on failure.

### Behavior

When `find` is `None`:
- **Endpoint:** `POST http://www.iwencai.com/gateway/urp/v7/landing/getDataList`
- **Response path:** `answer.components.0.data.datas`

When `find` is provided (find/pick endpoint):
- **Endpoint:** `POST http://www.iwencai.com/unifiedwap/unified-wap/v2/stock-pick/find`
- **Response path:** `data.data.datas`
- Request includes `question` field set to the find value

All requests use `POST` with `application/x-www-form-urlencoded` data format.

### Timeout

Fixed timeout of `(5, 10)` seconds (connection, read).

### Request Example
```python
from pywencai.wencai import get_robot_data, get_page

params = get_robot_data(query='融资余额', cookie='xxx')
url_params = params['url_params']
data = params['data']

# Fetch first page
df = get_page(url_params, **data, page=1, perpage=100, cookie='xxx')
print(df)

# Fetch with find
df_find = get_page(
    url_params,
    find=['600519', '000001'],  # Prioritize these codes
    query_type='stock',
    cookie='xxx'
)
```
```

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

### wiki1 Handler (Disabled)

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Handles wiki-style content but is currently commented out. If re-enabled, it would fetch and process component data from a URL.

```python
def wiki1_handler(comp: dict, comps: list) -> Any | None
```

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

### Fetching Specific Securities by Ticker

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/configuration.md

Use the `find` parameter to retrieve data for specific securities identified by their tickers. This ensures the top results correspond to the provided list.

```python
result = pywencai.get(
    query='沪深A股',
    find=['600519', '000001'],  # Get these at top
    cookie='xxx'
)
```

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

### txt Handler

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Handles text content components. Returns the text string from the 'data.content' field.

```python
def txt_handler(comp: dict, comps: list) -> str
```

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

### Generate Headers with Random User-Agent

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Generates API headers using a randomly selected User-Agent string.

```python
import pywencai

# Generate headers with random User-Agent
headers_random_ua = pywencai.headers(cookie='YOUR_COOKIE_STRING', random_ua=True)
print(headers_random_ua)
```

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

### xuangu_tableV1_handler

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Handles stock screening result table components. It takes a component dictionary and a list of components as input and returns a dictionary containing the URL-encoded condition for pagination, component ID, and a unique component ID.

```APIDOC
## xuangu_tableV1_handler

### Description
Handles stock screening result table components. It processes a given component and returns relevant metadata for pagination and identification.

### Function Signature
```python
def xuangu_tableV1_handler(comp: dict, comps: list) -> dict
```

### Returns
- `condition` (str): URL-encoded condition for pagination.
- `comp_id` (str): Component identifier.
- `uuid` (str): Unique component ID.

### Source
`pywencai/convert.py:17-23`
```

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

### Pywencai Response Parsing

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Details on the `convert()` function and various handlers used for parsing API responses and processing different component types.

```APIDOC
## Response Parsing and Component Handling

### `convert(response: dict)`

#### Description
Parses the raw API response and processes various component types.

#### Parameters
- **response** (dict) - Required - The raw API response dictionary.

#### Handlers Documented
- **xuangu_tableV1**: Handles stock tables.
- **container**: Handles nested containers.
- **tab1, tab4**: Handles tabbed interfaces.
- **txt**: Handles text content.
- **dragon_tiger_stock**: Handles market sentiment data.
- Plus 7 other component type handlers.

### Utility Functions

#### `show_type_handler(data: dict)`

#### Description
Determines and applies the appropriate handler based on the data type.

#### Parameters
- **data** (dict) - Required - The data to be handled.

#### `multi_show_type_handler(data: list)`

#### Description
Applies handlers to multiple items in a list.

#### Parameters
- **data** (list) - Required - A list of data items.

#### `get_key(data: dict, key: str)`

#### Description
Safely retrieves a value from a dictionary using a specified key.

#### Parameters
- **data** (dict) - Required - The dictionary to query.
- **key** (str) - Required - The key to retrieve.

#### `parse_url_params(url: str)`

#### Description
Parses URL parameters from a given URL string.

#### Parameters
- **url** (str) - Required - The URL string to parse.

#### `get_url(params: dict)`

#### Description
Constructs a URL from a dictionary of parameters.

#### Parameters
- **params** (dict) - Required - The parameters to construct the URL with.
```

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

### xuangu_tableV1 Handler

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Handles stock screening result tables. Returns a dictionary with condition, comp_id, and uuid.

```python
def xuangu_tableV1_handler(comp: dict, comps: list) -> dict
```

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

### txt_handler

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Extracts and returns plain text content from text components. It specifically retrieves the text from the 'data.content' field.

```APIDOC
## txt_handler

### Description
Extracts and returns plain text content from text components.

### Function Signature
```python
def txt_handler(comp: dict, comps: list) -> str
```

### Returns
Text string from `data.content`.

### Source
`pywencai/convert.py:43-46`
```

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

### Ensuring Consistent DataFrame Output

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/configuration.md

Configure the `no_detail` parameter to ensure the output is always a DataFrame or None, even if the query might otherwise return detailed data in a different format.

```python
result = pywencai.get(
    query='平安银行',  # May return detail data
    no_detail=True,   # But return None instead of dict
    cookie='xxx'
)
# result is guaranteed to be DataFrame or None
```

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

### Python Version Requirement from pyproject.toml

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/configuration.md

Specifies the Python version range required by the pywencai project as defined in its `pyproject.toml` file. Ensures compatibility with Python 3.8 and above.

```toml
requires-python = ">=3.8,<4.0"
```

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

### Process Multiple Components and Merge

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Employ `multi_show_type_handler` to process a list of components, extract keys, and merge their results into a single dictionary. This function is useful for aggregating data from various components.

```python
from pywencai.convert import multi_show_type_handler

result = multi_show_type_handler(components_list)
# Returns: {'component_title_1': <data>, 'component_title_2': <data>, ...}
```

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

### HTTP Headers Dictionary

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/types.md

Dictionary for HTTP headers, including authentication tokens and user agents. Generated by the headers() function.

```python
{
    'hexin-v': str,          # Authentication token
    'User-Agent': str,       # Browser user agent
    'cookie': str | None     # Session cookie
}
```

```python
{
    'hexin-v': '7d3a5c9e2f...',
    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)',
    'cookie': 'sessionid=abc123; path=/; Domain=.iwencai.com'
}
```

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

### Pywencai HTTP Endpoints

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Summary of the HTTP endpoints accessed by the pywencai library. This includes details on request methods, paths, parameters, and response structures.

```APIDOC
## HTTP Endpoints

### 1. POST /customized/chart/get-robot-data

#### Description
This endpoint is used for the initial query to retrieve robot data.

#### Request Body Parameters
- **query_type** (str) - Required - Type of data to query.
- **fields** (list[str]) - Optional - Fields to include in the response.

### 2. POST /gateway/urp/v7/landing/getDataList

#### Description
Endpoint for retrieving paginated results from data lists.

#### Request Body Parameters
- **query_type** (str) - Required - Type of data to query.
- **sort_order** (str) - Optional - Sorting order for the results.
- **limit** (int) - Optional - Maximum number of results per page.
- **offset** (int) - Optional - Offset for pagination.

### 3. POST /unifiedwap/unified-wap/v2/stock-pick/find

#### Description
Endpoint for security picking, likely related to stock market analysis.

#### Request Body Parameters
- **query_type** (str) - Required - Type of data to query.
- **stock_codes** (list[str]) - Optional - List of stock codes to analyze.

### 4. GET /[endpoint]

#### Description
Generic endpoint for fetching component data. The specific endpoint path may vary.

#### Parameters
- **endpoint** (str) - Required - The specific component endpoint path.

#### Request Headers
- **Authorization** (str) - Required - Authentication token.
```

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

### Use parse_url_params()

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Utilizes parse_url_params to parse and structure URL parameters.

```python
import pywencai

# Use parse_url_params()
url = 'http://example.com?param1=value1&param2=value2'
parsed_params = pywencai.parse_url_params(url)
print(parsed_params)
```

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

### Generate Token

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Calls the get_token function, likely to obtain an authentication token.

```python
import pywencai

# Generate token
token = pywencai.get_token()
print(token)
```

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

### Distinguishing No Results from Errors in Python

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/errors.md

This Python code snippet demonstrates how to differentiate between a 'None' return due to no search results and a 'None' return caused by a network or authentication failure.

```python
result = pywencai.get(query='...', cookie='...')
if result is None:
    # Could be no results OR network/auth failure
    pass
else:
    print(f"Got {len(result)} records")
```

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

### Extract Component Key

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

The `get_key` function extracts a descriptive key from a component dictionary, prioritizing specific fields like 'h1' in 'title_config', 'title' in 'config', or 'show_type'. It returns the first non-None value found.

```python
def get_key(comp: dict) -> str | None:
    # Extraction order:
    # 1. comp['title_config']['data']['h1']
    # 2. comp['config']['title']
    # 3. comp['show_type']
    pass
```

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

### Process API Response with convert()

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/REFERENCE_INDEX.md

Uses the convert function to process a raw API response into a usable format.

```python
import pywencai

# Process API response with convert()
raw_response = {'data': 'some_data'}
processed_data = pywencai.convert(response=raw_response)
print(processed_data)
```

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

### Fetch Multiple Consecutive Pages

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/internal-functions.md

Use loop_page to fetch a specified number of consecutive pages and concatenate the results. It handles calculating the maximum pages and sequential fetching, skipping failed pages.

```python
from pywencai.wencai import get_robot_data, loop_page

params = get_robot_data(query='沪深A股', cookie='xxx')
data = params['data']
url_params = params['url_params']
row_count = params['row_count']

# Fetch first 5 pages
df = loop_page(
    loop=5,
    row_count=row_count,
    url_params=url_params,
    page=1,
    perpage=100,
    cookie='xxx',
    log=True
)
```

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

### textblocklinkone Handler

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Extracts data for text blocks with links from 'data.result.data'. Returns a pandas.DataFrame.

```python
def textblocklinkone_handler(comp: dict, comps: list) -> pandas.DataFrame
```

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

### show_type_handler

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Dispatches component processing to the appropriate handler based on 'show_type'. It checks the component's show_type against a registry and either calls a specific handler or falls back to a common handler.

```APIDOC
## show_type_handler

### Description
Dispatches component processing to the appropriate handler based on `show_type`. It checks `comp['show_type']` against the handler registry. If the type is known, it calls the specific handler; otherwise, it falls back to `common_handler()`.

### Function Signature
```python
def show_type_handler(comp: dict, comps: list) -> Any
```

### Parameters
* **comp** (dict) - The component dictionary to process.
* **comps** (list) - A list of components.

### Returns
* Any - The result of the component processing.

### Code Example
```python
from pywencai.convert import show_type_handler

result = show_type_handler(component_dict, all_components)
```
```

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

### Send Query to Wencai API

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/internal-functions.md

The `get_robot_data` function sends a query to the Wencai API and extracts the raw response. It accepts various parameters including the query string, authentication cookie, query type, retry settings, and options for paid API usage. The function returns a dictionary containing response data, URL, URL parameters, and row count, or `None` if retries are exhausted.

```python
def get_robot_data(**kwargs) -> dict | None:
    pass
```

```python
from pywencai.wencai import get_robot_data

params = get_robot_data(
    query='退市股票',
    cookie='xxx',
    log=True
)
print(params['data']['condition'])  # URL-encoded pagination condition
print(params['row_count'])          # Total available rows
```

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

### container_handler

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Processes hierarchical container components. It iterates through child components, processes them individually, and returns a dictionary keyed by the child's show type.

```APIDOC
## container_handler

### Description
Handles hierarchical container components with child components. It recursively processes children and organizes the results by their type.

### Function Signature
```python
def container_handler(comp: dict, comps: list) -> dict
```

### Behavior
1. Iterates over child UUIDs in `config.children`.
2. Finds each child component in the component list.
3. Processes child using `show_type_handler()`.
4. Returns dict keyed by child's `show_type`.

### Source
`pywencai/convert.py:33-41`
```

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

### loop_page

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/internal-functions.md

Fetches multiple consecutive pages and concatenates results. This function is used internally to efficiently retrieve data that spans across multiple pages.

```APIDOC
## loop_page

### Description
Fetches multiple consecutive pages and concatenates results.

### Method
Internal Function

### Signature
```python
def loop_page(loop, row_count, url_params, **kwargs) -> pandas.DataFrame | None
```

### Parameters
#### Path Parameters
- **loop** (int) - Required - Number of pages to fetch
- **row_count** (int) - Required - Total available rows (used to calculate max pages)
- **url_params** (dict) - Required - URL parameters from `get_robot_data()`

#### Query Parameters
- **perpage** (int) - Optional - Records per page (default: 100)
- **page** (int) - Optional - Starting page number (default: 1)

#### Request Body
- **Additional** (dict) - Optional - All other kwargs passed to `get_page()`

### Response
#### Success Response
- **pandas.DataFrame** - DataFrame with all fetched pages stacked vertically.

#### Error Response
- **None** - Returned if any page fails.

### Behavior
Calculates the maximum possible pages as `ceil(row_count / perpage)`. Fetches the minimum of:
- `loop` pages (if `loop` is an integer)
- All available pages (if `loop` is `True` in the caller)

Pages are fetched sequentially starting from the initial `page` parameter. Failed pages are skipped. Results are concatenated using `pd.concat(ignore_index=True)`.

### Code Example
```python
from pywencai.wencai import get_robot_data, loop_page

params = get_robot_data(query='沪深A股', cookie='xxx')
data = params['data']
url_params = params['url_params']
row_count = params['row_count']

# Fetch first 5 pages
df = loop_page(
    loop=5,
    row_count=row_count,
    url_params=url_params,
    page=1,
    perpage=100,
    cookie='xxx',
    log=True
)
```
```

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

### Execute Function with Retry Logic

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/internal-functions.md

Use `while_do` to execute a given function with automatic retry capabilities. It supports configurable retry attempts, sleep intervals between retries, and optional logging of failed attempts. The function returns the result of the executed function on success or `None` if all retries fail.

```python
def while_do(do, retry=10, sleep=0, log=False) -> Any | None:
    pass
```

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

### textblocklinkone_handler

Source: https://github.com/zsrl/pywencai/blob/main/_autodocs/api-reference/convert.md

Processes text blocks that contain link data. It extracts the relevant data from 'data.result.data' and returns it as a pandas DataFrame.

```APIDOC
## textblocklinkone_handler

### Description
Processes text blocks containing link data, extracting information into a pandas DataFrame.

### Function Signature
```python
def textblocklinkone_handler(comp: dict, comps: list) -> pandas.DataFrame
```

### Extracts data from
`data.result.data`

### Source
`pywencai/convert.py:101-103`
```