Skip to main content

This is the python SDK of lixinger API. Lixinger is a website of financial data.

✨ Features

  • ⚡ Fully Async/Await - Non-blocking I/O for better performance
  • 🤖 AI Agent Ready - Perfect for LangChain, LlamaIndex function calls
  • 📊 Pandas DataFrame - All responses return pandas DataFrame
  • 🔒 Type Safe - Full type hints and mypy support
  • 🔄 Auto Retry - Automatic retry with exponential backoff
  • 🚦 Rate Limiting - Built-in rate limiter (1000 req/min)
  • 🌐 Proxy Support - SOCKS proxy support
  • 📓 Jupyter Ready - Native top-level await support

Installation

# Using pip
pip install lixinger-python

# Using uv (faster)
uv add lixinger-python

From Source (Development)

# Clone the repository
git clone https://github.com/your-username/lixinger-python.git
cd lixinger-python

# Install dependencies
uv sync

Configuration

REQUIRED: The SDK requires the API key to be set in a .env file. The API key cannot be passed as a parameter.

# Copy the example file
cp .env.example .env

# Edit .env and add your API key
# LIXINGER_API_KEY=your_actual_api_key_here

Get your API key from: https://www.lixinger.com/open/api

Usage

Basic Usage (Async/Await)

import asyncio
from lixinger import AsyncLixingerClient

async def main():
    # The API key is ALWAYS loaded from .env file
    # You cannot pass it as a parameter - this is intentional for security
    async with AsyncLixingerClient() as client:
        # Fetch company information
        df = await client.company.company.get_company(stock_codes=["600036"])
        print(df)

        # Fetch company profile
        df_profile = await client.company.profile.get_profile(stock_codes=["600036"])
        print(df_profile)

if __name__ == "__main__":
    asyncio.run(main())

Advanced: Concurrent Requests

Query multiple stocks in parallel using asyncio.gather():

import asyncio
from lixinger import AsyncLixingerClient

async def main():
    async with AsyncLixingerClient() as client:
        # Fetch multiple stocks concurrently
        tasks = [
            client.company.company.get_company(stock_codes=["600036"]),
            client.company.company.get_company(stock_codes=["000001"]),
            client.company.company.get_company(stock_codes=["000002"]),
        ]
        results = await asyncio.gather(*tasks)

        for df in results:
            print(df)

asyncio.run(main())

Jupyter Notebook Usage

Jupyter notebooks support async/await natively at the top level:

# In a Jupyter cell, you can use await directly (no asyncio.run needed)
from lixinger import AsyncLixingerClient

client = AsyncLixingerClient()
df = await client.company.company.get_company(stock_codes=["600036"])
df

Configuration Override

# You can override settings (but NOT the API key)
async with AsyncLixingerClient(
    timeout=60.0,
    proxy="socks5://localhost:1080",
    max_requests_per_minute=500
) as client:
    df = await client.company.company.get_company(stock_codes=["000001"])

For more examples, see the examples/ directory.

Project Structure

The project follows an endpoint-based file organization:

lixinger/
├── api/cn/
│   ├── company/     # /cn/company endpoints (async)
│   ├── index/       # /cn/index endpoints (async)
│   └── fund/        # /cn/fund endpoints (async)
└── models/cn/       # Pydantic models (mirrors API structure)
    ├── company/
    ├── index/
    └── fund/

Available APIs

Company APIs (client.company.*):

  • get_company() - Company basic info
  • get_profile() - Company profile
  • get_fundamental() - Fundamental data
  • get_candlestick() - OHLC candlestick data
  • get_equity_change() - Equity change events
  • get_dividend() - Dividend information
  • get_announcement() - Company announcements
  • get_indices() - Index memberships

Index APIs (client.cn_index.*):

  • get_index() - Index basic info
  • get_constituents() - Index constituents
  • get_candlestick() - Index OHLC data
  • get_fundamental() - Index fundamentals
  • get_tracking_fund() - Tracking funds
  • And more...

Fund APIs (client.cn_fund.*):

  • get_fund() - Fund basic info
  • get_profile() - Fund profile
  • get_candlestick() - Fund NAV data
  • get_shareholdings() - Fund holdings
  • And more...

Import Examples:

# Client API (recommended)
from lixinger import AsyncLixingerClient

async with AsyncLixingerClient() as client:
    df = await client.company.company.get_company(stock_codes=["000001"])

# Functional API (also async)
from lixinger import get_company, get_index

df = await get_company(stock_codes=["000001"])

# Models (if needed for type hints)
from lixinger.models.cn.company import Company
from lixinger.models.cn.index import Index

See AGENTS.md for detailed file organization rules.

Documentation

文档特性

本项目使用 MkDocs + Material 主题 自动生成文档,特性包括:

  • ✨ 从 Python docstrings 自动生成 API 文档
  • 🎨 美观的 Material Design 界面
  • 🔍 全文搜索功能(支持中英文)
  • 🌓 深色/浅色主题切换
  • 📱 响应式设计,支持移动端

生成和预览文档

# 安装文档依赖
uv sync --dev

# 启动本地文档服务器(支持热重载)
uv run mkdocs serve
# 访问 http://127.0.0.1:8000

# 构建静态站点
uv run mkdocs build

# 部署到 GitHub Pages
uv run mkdocs gh-deploy

详细说明请查看 DOCS.md。

API Notes

Architecture:

  • 🔄 Fully Async - All API methods use async def and must be awaited
  • ⚡ Non-blocking - Perfect for concurrent requests and AI agents
  • 📦 httpx.AsyncClient - Modern async HTTP client

API Requirements:

  • Content-Type: application/json in request headers
  • Accept-Encoding: Must include gzip (can also include deflate, br, *)
  • Rate Limit: Maximum 1000 requests per minute
  • Status Code 429: Too Many Requests (rate limit exceeded)
  • Retry Mechanism: Built-in automatic retry for network issues
  • Authentication: API key sent via token in POST body (loaded from .env)

Response Format: All Lixinger API responses follow this format:

{
  "code": 1,           // 1 = success, other = error
  "message": "success",
  "data": [...]        // Actual data (unwrapped by SDK)
}

The SDK automatically validates the response and returns only the data field.

Why Async?

Perfect for:

  • 🤖 AI Agents - LangChain, LlamaIndex function calls
  • 🌐 Web Apps - FastAPI, Sanic, Quart backends
  • 📊 Data Pipelines - Concurrent batch processing
  • 📓 Jupyter - Interactive analysis with await

Benefits:

  • ⚡ Concurrent requests - Query multiple stocks in parallel
  • 🚫 Non-blocking - Doesn't block your event loop
  • 📈 Better performance - Especially for bulk operations
  • 🎯 Modern Python - Follows async/await best practices

Development

# Run linter
uv run ruff check . --fix

# Run formatter
uv run ruff format .

# Run type checker
uv run mypy lixinger/

# Run tests (unit tests only, fast)
uv run pytest -m "not integration"

# Run all tests including integration (requires API key)
uv run pytest

See CLAUDE.md for development guidelines.

Contributing

Contributions are welcome! Please see AGENTS.md for detailed implementation guidelines, especially:

  • How to add new APIs (all must be async)
  • File organization rules
  • Testing requirements
  • Documentation standards

License

[Your License Here]

Metadata

Release files for lixinger-python 0.3.16

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lixinger-python 0.3.16
File Size Uploaded Provenance Actions
lixinger_python-0.3.16.tar.gz 433.0 kB Without provenance Details for lixinger_python-0.3.16.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lixinger-python 0.3.16
File Interpreter ABI Platform Actions
lixinger_python-0.3.16-py3-none-any.whl Python 3 none any Details for lixinger_python-0.3.16-py3-none-any.whl

Total release size: 564.1 kB

Release files / lixinger_python-0.3.16.tar.gz

Download URL lixinger_python-0.3.16.tar.gz
Size 433.0 kB
Tags Source
SHA-256 checksum
How to use checksums
0573c9d4c9868ba4c4074f5a4b29206720b0d229dbc0bb670e5ebb357a4ce2e7
BLAKE2b-256 checksum
How to use checksums
81e7f2d7f607809856d83f0c0c65132f37fb5f78aef33b8dbaaad3e3cd8fea1f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.12

Release files / lixinger_python-0.3.16-py3-none-any.whl

Download URL lixinger_python-0.3.16-py3-none-any.whl
Size 131.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1ffa3a0040a575191c5173e8263c4b62e67fef9ff4d7696c409a6ab12d7246be
BLAKE2b-256 checksum
How to use checksums
066484eeb000cb36fbd45c7f37009af2a1aac1fb8f37ddbe74073fbce4587709
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.12

Security for lixinger-python 0.3.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.16 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page