Metadata-Version: 2.4
Name: young-stock-cli
Version: 0.1.4
Summary: A-share (China stock market) after-hours CLI — no login, no scraping tricks, just data.
Project-URL: Homepage, https://github.com/AdvancingTitans/young-stock-cli
Project-URL: Repository, https://github.com/AdvancingTitans/young-stock-cli
Project-URL: Issues, https://github.com/AdvancingTitans/young-stock-cli/issues
Project-URL: Changelog, https://github.com/AdvancingTitans/young-stock-cli/blob/main/CHANGELOG.md
Author: AdvancingTitans
License: MIT
License-File: LICENSE
Keywords: a-share,china,cli,eastmoney,finance,stock
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# young-stock-cli

[![PyPI](https://img.shields.io/pypi/v/young-stock-cli.svg)](https://pypi.org/project/young-stock-cli/)
[![Python](https://img.shields.io/pypi/pyversions/young-stock-cli.svg)](https://pypi.org/project/young-stock-cli/)
[![License](https://img.shields.io/pypi/l/young-stock-cli.svg)](https://github.com/AdvancingTitans/young-stock-cli/blob/main/LICENSE)
[![CI](https://github.com/AdvancingTitans/young-stock-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/AdvancingTitans/young-stock-cli/actions/workflows/ci.yml)
[![Downloads](https://static.pepy.tech/badge/young-stock-cli/month)](https://pepy.tech/project/young-stock-cli)

> An A-share (China stock market) after-hours CLI that **just works** — no login, no API keys, no scraping tricks.
> Also covers HK & US indices and a global snapshot.

A single command (`young a`) prints a complete after-hours dashboard: major indices, limit-up (涨停) and limit-down pools, verified A-share fund flow when the trading date matches, and top sector boards. Everything pulls from public no-login endpoints, with a 7-day local cache so repeated calls during the same session don't hammer the server.

Born out of a real workflow: every trading day after close I wanted the same five numbers in one place without opening a browser or paying for a data terminal. So I packaged it.

---

## Install

```bash
pip install young-stock-cli
```

Requires Python 3.10+.

## Usage

```bash
young a                 # A-share after-hours dashboard (the main thing)
young hk                # Hong Kong indices snapshot
young us                # US indices snapshot
young global            # A + HK + US in one view
young stock 600519      # one stock snapshot (A-share / HK / US)
young indices           # A-share indices only
young zt-pool           # limit-up (涨停) / limit-down / 炸板 pool
young flow              # latest verified A-share fund flow
young a -d 20260530     # historical date (YYYYMMDD)
young a --refresh       # bypass cache, force re-fetch
young update            # upgrade young-stock-cli in the current Python env
young --help
```

### Example output (`young indices`)

```
A股主要指数 — 2026-05-30 收盘
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ 指数                        ┃     收盘  ┃ 涨跌幅 ┃ 成交额  ┃ 振幅     ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ 上证指数                    │  3,347.49 │ +0.62% │ 4,821亿 │ 1.18%   │
│ 深证成指                    │ 10,402.91 │ +0.95% │ 6,015亿 │ 1.42%   │
│ 创业板指                    │  2,135.66 │ +1.21% │ 2,310亿 │ 1.68%   │
│ 科创50                      │  1,028.74 │ +0.81% │ 412亿   │ 1.05%   │
└─────────────────────────────┴───────────┴────────┴─────────┴──────────┘
```

---

## Why this exists

Most A-share data libraries either (a) require paid accounts, (b) break the moment a portal redesigns its DOM, or (c) ship hundreds of MB of dependencies for a one-off after-hours glance. This is a 1-file core, three runtime deps (`requests`, `click`, `rich`), opinionated output, and a single command that prints what a trader actually wants at 15:01.

It is also a foundation for analysis pipelines: every subcommand maps to a Python function in `young_stock._core`, so you can `from young_stock._core import get_zt_pool, get_fund_flow` and feed the dicts into your own notebook or LLM prompt.

## What's in the box

- **Multiple public quote sources** — Tencent Finance, Sina Finance, and Eastmoney are tried in sequence so temporary source failures can be filled by another no-login endpoint.
- **Single-stock lookup** — `young stock 600519`, `young stock 0700.HK`, or `young stock AAPL` prints a compact quote snapshot with source, trade date, price, change, volume, turnover when available, and optional news.
- **Smart caching** — `~/.young_stock/cache/`, 7-day TTL, auto-pruned. Pass `--refresh` to skip.
- **Trade-day awareness** — nearest-trade-day resolution including weekends and (best-effort) holidays.
- **Rich terminal tables** — readable on dark and light terminals.
- **Verified A-share fund flow** — `young flow` shows the latest Eastmoney A-share / Shanghai Composite fund-flow date explicitly; full reports only include it when the trading date matches.
- **Sector boards via browser fallback** — when Eastmoney's board API rate-limits, falls back to rendering the public web page (optional, requires a local browser engine).
- **Local updater** — `young update` runs `python -m pip install --upgrade young-stock-cli` with the same interpreter that launched the CLI.

## Library usage

```python
from young_stock._core import get_index, get_zt_pool, nearest_trade_date

date = nearest_trade_date()
print(get_index(date))
print(get_zt_pool(date))
```

## Development

```bash
git clone https://github.com/AdvancingTitans/young-stock-cli.git
cd young-stock-cli
pip install -e ".[dev]"
pytest
ruff check .
```

## Roadmap

- [ ] Optional JSON output (`--json`) for piping into downstream tools.
- [ ] Built-in trading-calendar (公开节假日) for accurate non-trade-day skipping.
- [ ] Plugin hooks for additional data sources (THS, Sina).
- [ ] `young watch` — live ticker mode during trading hours.

PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT — see [LICENSE](LICENSE).

---

## 中文说明

A 股盘后行情命令行工具。免登录、免 API key、免反爬技巧 — 一行命令把当日涨跌、涨停板、可核验的 A 股资金流向、板块榜全部打到终端。同时支持港股、美股指数和全球快照视图。

```bash
pip install young-stock-cli
young a            # A 股盘后总览（主命令）
young stock 600519 # 单只股票速览（A股 / 港股 / 美股）
young zt-pool      # 涨停 / 跌停 / 炸板分析
young flow         # 最新可核验 A 股资金流向
young global       # 全球指数一屏
young a -d 20260530 --refresh    # 指定日期 + 强制刷新
young update       # 在当前 Python 环境中更新 CLI
```

数据来源：腾讯财经、新浪财经、东方财富公开行情接口（`qt.gtimg.cn` / `hq.sinajs.cn` / `push2.eastmoney.com` / `push2ex.eastmoney.com`），多源自动切换。本地缓存 7 天，目录 `~/.young_stock/cache/`，可用 `young cache-clear` 清理。

适用人群：每天盘后想用一条命令看完五张图的开发者 / 量化研究者 / 自动化爱好者。欢迎 issue / PR。
