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

## 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")
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/*
```
