Metadata-Version: 2.4
Name: canslim-yanxiang
Version: 0.1.0
Summary: Python SDK for the CANSLIM Yanxiang cloud API
Author: CANSLIM Yanxiang
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://github.com/johnhowl/canslim_lib
Project-URL: Issues, https://github.com/johnhowl/canslim_lib/issues
Keywords: canslim,stock-screening,quantitative-finance,china-stocks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.25
Requires-Dist: pandas<4,>=2.2

# canslim-yanxiang

`canslim-yanxiang` is the lightweight Python SDK for the CANSLIM cloud service.
It uses an API key and HTTPS to call `/api/sdk/v1`. Database credentials,
membership checks, indicator calculations, and stock screening stay on the
server; an SDK user never connects to the production database directly.

Version 0.1.0 includes L1 market and financial queries, L2-Class1 stock
analysis, L2-Class2 industry analysis, L2-Class3 CANSLIM card indicators, and
L2-Class4 rule-based stock screening.

## Install

Install the production package from PyPI:

```powershell
python -m pip install --upgrade canslim-yanxiang
```

Verify the installation:

```powershell
python -c "import canslim_yanxiang as cs; print(cs.__version__)"
```

On macOS (Intel or Apple Silicon), use Python 3.10 or newer:

```bash
python3 -m pip install --upgrade canslim-yanxiang
python3 -c "import canslim_yanxiang as cs; print(cs.__version__)"
```

The SDK is platform-independent and does not include B-XTrender.

For repository development:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
```

## Configure

Set the cloud endpoint and API key in the current PowerShell session:

```powershell
$env:CANSLIM_API_BASE_URL = "https://your-domain.example/api/sdk/v1"
$env:CANSLIM_API_KEY = "csk_live_xxx"
```

Configuration can also be supplied in Python:

```python
import canslim_yanxiang as cs

cs.configure(
    base_url="https://your-domain.example/api/sdk/v1",
    api_key="csk_live_xxx",
)
```

The API key is never written into the package. The server validates membership
level and account expiry for every call.

## L1 Queries

```python
import canslim_yanxiang as cs

stocks = cs.stock_search("600519")
info = cs.stock_basic_info("600519")
latest = cs.stock_price_latest("600519")
prices = cs.stock_price_history("600519", start="2025-01-01")
financials = cs.stock_financials("600519", period="quarterly", limit=20)
```

List endpoints return pandas `DataFrame` objects by default and single-object
endpoints return dictionaries. Pass `raw=True` to receive the complete response
envelope.

## L2 Analysis

L2-Class1 stock analysis:

```python
current = cs.eps_current_quarter_score("600519")
eps = cs.eps_growth_history("600519", mode="quarter")
stock_score = cs.stock_rps_score("600519")       # defaults to rps_240
industry_score = cs.industry_rps_score("600519") # defaults to rps_120
industry = cs.stock_industry("600519")
```

L2-Class2 industry analysis:

```python
industries = cs.industry_list()
basic = cs.industry_basic_info("340500")
members = cs.industry_constituents("340500")
fundamental = cs.industry_fundamental_analysis(top_n=20)
strength = cs.industry_strength_history("340500")
member_rps = cs.industry_constituent_rps_ranking("340500")
```

L2-Class3 CANSLIM card analysis:

```python
c = cs.c_card("600519", report_date="2026-03-31")
a = cs.a_card("600519", report_date="2026-03-31")
n = cs.n_card("600519")
s = cs.s_card("600519", report_date="2026-03-31")
l = cs.l_card("600519")
i = cs.i_card("600519", report_date="2026-03-31")
m = cs.m_card()
```

Atomic indicators are also callable individually and can be registered in
L2-Class4 screening rules. See the contracts under [`docs/`](docs/) for stable
parameters and response fields.

## Six-Rule Screen

Run the frozen C/A/N/S/L/I rule set after installation:

```powershell
canslim-screen-six-rules
```

The default `intersection` mode requires all six groups. To return stocks that
match at least five groups:

```powershell
canslim-screen-six-rules --combine at_least --min-matched-rules 5
```

Dates and output location can be fixed explicitly:

```powershell
canslim-screen-six-rules `
  --report-date 2026-03-31 `
  --as-of-date 2026-07-17 `
  --output .\results\six_rules.csv
```

The command writes a CSV and a matching `.meta.json` file. Because the current
screening API is synchronous, the percentage shown while waiting is an elapsed
time estimate. Final counts and results always come from the cloud response.

## Repository Boundaries

- This repository contains the installable SDK and archived backtest CSV data.
- The production backend owns API keys, permissions, quotas, logs, database
  access, and job execution.
- The offline project owns heavy recomputation, historical backfills, and
  publishable data generation.
- `backtest_csv/` is not included in the SDK wheel. It is deployed separately
  as read-only cloud data when required by the backtest service.

See [SDK framework and cloud deployment](docs/canslim_python_library_framework_design.md)
for the complete architecture.

## Development Verification

```powershell
python -m unittest discover -s tests -v
python -m build
python -m twine check dist/*
```
