Metadata-Version: 2.4
Name: lixinger-python
Version: 0.1.2
Summary: Python SDK for Lixinger Financial Data API
Project-URL: Homepage, https://www.lixinger.com
Project-URL: Documentation, https://www.lixinger.com/open/api/doc
Author-email: JianGuo <aliezted@gmail.com>
License: MIT
License-File: LICENSE
Keywords: api,finance,financial-data,lixinger,sdk,stock
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: numpy>=2.4.1
Requires-Dist: pandas>=3.0.0
Requires-Dist: pandera>=0.28.1
Requires-Dist: python-dotenv>=1.2.1
Description-Content-Type: text/markdown

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

## Installation

### From PyPI (Recommended)

```bash
# Using pip
pip install lixinger-python

# Using uv (faster)
uv add lixinger-python
```

### From Source (Development)

```bash
# 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.

```bash
# 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

```python
from lixinger import LixingerClient

# The API key is ALWAYS loaded from .env file
# You cannot pass it as a parameter - this is intentional for security
client = LixingerClient()

try:
    # Fetch company information
    df = client.company.get_company(stock_codes=["600036"])
    print(df)

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

# Or use context manager (recommended)
with LixingerClient() as client:
    df = client.company.get_company(stock_codes=["000001"])
    print(df)

# You can override other settings (but NOT the API key)
with LixingerClient(timeout=60.0, proxy="socks5://localhost:1080") as client:
    df = client.company.get_company(stock_codes=["000001"])
    print(df)
```

For more examples, see the `examples/` directory.

## Project Structure

The project follows an endpoint-based file organization:

```
lixinger/
├── api/cn/
│   ├── company/     # /cn/company endpoints
│   └── index/       # /cn/index endpoints
└── models/cn/       # Models mirror API structure
    ├── company/
    └── index/
```

**Import Examples:**

```python
# Functional API (recommended for quick usage)
from lixinger import get_company, get_index

# Client API
from lixinger import LixingerClient

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

See `AGENTS.md` for detailed file organization rules.

## Documentation

- 📚 **完整文档**: 运行 `uv run mkdocs serve` 启动本地文档站点
- 📖 **API 参考**: 查看 `docs/api/` 目录或 [API_SUMMARY.md](API_SUMMARY.md)
- 🚀 **快速开始**: 查看 [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md)

### 文档特性

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

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

### 生成和预览文档

```bash
# 安装文档依赖
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](DOCS.md)。

## API Notes

Notes when using the API:

* Set Content-Type to application/json in the request headers.
* The accept-encoding in request headers must include gzip, other options can be deflate, br, *.
* The maximum number of requests per minute is 1000. If it exceeds 1000, the request will fail and return status code 429 (Too Many Requests).
* Crawlers generally need to have a retry mechanism to avoid the crawler crashing when network issues or other unknown problems occur.
