Metadata-Version: 2.4
Name: canslim-yanxiang
Version: 0.2.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.

The current SDK includes L1 market and financial queries, L2-Class1 stock
analysis, L2-Class2 industry analysis, L2-Class3 CANSLIM card indicators,
L2-Class4 rule-based stock screening, and the first L2-Class5 market-analysis
aggregate.

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

Start the Tkinter desktop screener from a repository checkout:

```powershell
$env:CANSLIM_API_BASE_URL = "http://127.0.0.1:5000/api/sdk/v1"
python -m canslim_yanxiang.gui
```

After an editable install, the equivalent command is
`canslim-screener-gui`. The desktop application reads the Chinese indicator
names from the server registry, stores rule plans locally without the API key,
and uses the same Class4, Class5, and L3 endpoints as the SDK.

## Configure

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

```powershell
$env:CANSLIM_API_BASE_URL = "https://canslim-lab.com/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")
fresh_breakout = cs.n_fresh_resistance_breakout(
    "600519",
    lookback=240,
)
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()

# Nine-index consensus used by later L3 market gates.
market = cs.market_state_aggregate()
```

L3 industry-rotation opportunities default to evaluating industries without a
market gate:

```python
opportunities = cs.industry_rotation_opportunities(
    rps_top_n=30,
    eps_top_m=30,
    output_top_n=5,
    stocks_per_industry=10,
    market_gate="off",
)
```

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
python -m canslim_yanxiang.screen_six_rules
```

Use `--rules` to select a subset. The default `intersection` mode requires every
selected rule, so this example only returns stocks that satisfy C, A, L and I:

```powershell
python -m canslim_yanxiang.screen_six_rules --rules C A L I
```

Comma-separated input is also accepted. To return stocks matching at least
three of those four selected rules:

```powershell
python -m canslim_yanxiang.screen_six_rules `
  --rules C,A,L,I `
  --combine at_least `
  --min-matched-rules 3
```

Dates and output location can be fixed explicitly:

```powershell
python -m canslim_yanxiang.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. Each result contains
`matched_rule_count` and `matched_rules`, so the selected rule names are visible
for every stock. 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/*
```
