royy/chinese-equity-quant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: manage env with uv (pyproject + lockfile)

Browse Source 
Migrate dependency management from requirements.txt to uv. Runtime deps
move to pyproject.toml with pytest in the dev group; uv.lock pins the
resolved set. Docs updated to use `uv sync` / `uv run`.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Yuxuan Yan
2026-06-09 16:20:08 +08:00
parent 0c524c6987
commit 7faeb77c50
5 changed files with 1777 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+15 -11
View File
@@ -6,19 +6,23 @@ A modular Chinese A-share quant research framework. Daily frequency only (Phase
## Commands
The env is managed with **uv**. `uv sync` creates `.venv` from `pyproject.toml` + `uv.lock`; `uv run <cmd>` runs inside it (no manual activation needed).
```bash
pip install -r requirements.txt # install deps
python3 -m pytest tests/ -v # all tests
python3 -m pytest tests/test_alpha.py -v # single file (test_alpha is network-free)
python3 -m pytest tests/test_alpha.py::test_evaluate_alpha_keys -v # single test
uv sync # create/refresh .venv from the lockfile (incl. dev group)
uv run python -m pytest tests/ -v # all tests
uv run python -m pytest tests/test_alpha.py -v # single file (test_alpha is network-free)
uv run python -m pytest tests/test_alpha.py::test_evaluate_alpha_keys -v # single test
# Pipeline — each phase is independent: reads parquet, writes parquet.
python3 cli.py data download --universe csi500 --start-date 2017-01-01 # → data/daily_bars/csi500/ (month-partitioned)
python3 cli.py alpha reversal --data-path data/daily_bars/<universe> # --data-path is the dataset DIR
python3 cli.py alpha eval --alpha-path alphas/<file>.pq --data-path data/daily_bars/<universe>
python3 cli.py combo combine --alpha-paths a.pq,b.pq --combo-name eq --method equal_weight
uv run python cli.py data download --universe csi500 --start-date 2017-01-01 # → data/daily_bars/csi500/ (month-partitioned)
uv run python cli.py alpha reversal --data-path data/daily_bars/<universe> # --data-path is the dataset DIR
uv run python cli.py alpha eval --alpha-path alphas/<file>.pq --data-path data/daily_bars/<universe>
uv run python cli.py combo combine --alpha-paths a.pq,b.pq --combo-name eq --method equal_weight
```
Add a runtime dep with `uv add <pkg>`, a dev/test dep with `uv add --dev <pkg>` (both update `pyproject.toml` + `uv.lock`).
Note: `tests/test_downloader.py` hits the network (live baostock/akshare); `tests/test_alpha.py` is pure and fast.
## Architecture: one decoupled pipeline
@@ -57,9 +61,9 @@ Each alpha is a class subclassing `BaseAlpha` (`pipeline/alpha/base.py`), living
- **External alphas** (authored outside this repo) are the point of the design: write a `@register_alpha class MyAlpha(BaseAlpha)` in any `.py` file, then register it at runtime with `--alpha-module path/to/file.py` (or a dotted module path). See `examples/alphas/mean_reversion.py` for a working example, and `tests/test_alpha.py::test_load_external_alpha_module`.
```bash
python3 cli.py alpha list # registered alpha types
python3 cli.py alpha list --alpha-module my_alpha.py # incl. an external one
python3 cli.py alpha compute --alpha-module my_alpha.py \
uv run python cli.py alpha list # registered alpha types
uv run python cli.py alpha list --alpha-module my_alpha.py # incl. an external one
uv run python cli.py alpha compute --alpha-module my_alpha.py \
--alpha-type my_alpha --alpha-name run1 --param decay=0.9 --data-path <data>.pq
```
README.md
+20 -18
View File
@@ -39,36 +39,38 @@ Data comes from **baostock (primary)** with **akshare (fallback)**.
## Install
The env is managed with [uv](https://docs.astral.sh/uv/). `uv sync` builds `.venv` from `pyproject.toml` + `uv.lock`; prefix commands with `uv run` (no manual activation needed).
```bash
pip install -r requirements.txt
uv sync
```
## Quick start
```bash
# 1. Download daily bars for a few symbols (writes a month-partitioned dataset).
python3 cli.py data download \
uv run python cli.py data download \
--universe sh600000,sz000001,sh600519 \
--start-date 2024-01-01 --end-date 2024-03-31 \
--output-dir data/daily_bars
# 2. Compute an alpha (position weights) from that data.
# --data-path is the dataset DIRECTORY ({output-dir}/{universe}).
python3 cli.py alpha reversal \
uv run python cli.py alpha reversal \
--data-path "data/daily_bars/sh600000,sz000001,sh600519"
# 3. Evaluate it (return / Sharpe / turnover / drawdown).
python3 cli.py alpha eval \
uv run python cli.py alpha eval \
--alpha-path alphas/reversal_5d.pq \
--data-path "data/daily_bars/sh600000,sz000001,sh600519"
# Tests
python3 -m pytest tests/ -v # tests/test_alpha.py is network-free; test_downloader.py hits the network
uv run python -m pytest tests/ -v # tests/test_alpha.py is network-free; test_downloader.py hits the network
```
## CLI reference
All commands are subcommands of `python3 cli.py`. Add `--help` to any of them.
All commands are subcommands of `uv run python cli.py`. Add `--help` to any of them.
### `data download` — fetch daily bars → partitioned parquet dataset
@@ -93,8 +95,8 @@ set. Symbols use the internal `sh600000` / `sz000001` form (exchange prefix + co
### `alpha list` — show registered alpha types
```bash
python3 cli.py alpha list
python3 cli.py alpha list --alpha-module path/to/my_alpha.py # include an external alpha
uv run python cli.py alpha list
uv run python cli.py alpha list --alpha-module path/to/my_alpha.py # include an external alpha
```
### `alpha compute` — alpha class → weights parquet
@@ -114,7 +116,7 @@ Only the params an alpha's `__init__` accepts are forwarded, so passing extras
(e.g. `--vol-window` to a reversal alpha) is harmless.
```bash
python3 cli.py alpha compute \
uv run python cli.py alpha compute \
--data-path <data>.pq \
--alpha-type reversal_vol --alpha-name rv_5_20 \
--lookback 5 --vol-window 20
@@ -123,14 +125,14 @@ python3 cli.py alpha compute \
Shortcuts for the two most common built-ins:
```bash
python3 cli.py alpha reversal --data-path <data>.pq --lookback 5
python3 cli.py alpha reversal-vol --data-path <data>.pq --lookback 5 --vol-window 20
uv run python cli.py alpha reversal --data-path <data>.pq --lookback 5
uv run python cli.py alpha reversal-vol --data-path <data>.pq --lookback 5 --vol-window 20
```
### `alpha eval` — score an alpha as a portfolio
```bash
python3 cli.py alpha eval --alpha-path alphas/<name>.pq --data-path <data>.pq
uv run python cli.py alpha eval --alpha-path alphas/<name>.pq --data-path <data>.pq
```
Interprets the weights as a portfolio and reports cumulative return, annual
@@ -148,7 +150,7 @@ position weights, not return predictors.
| `--output-dir` | `combos` | Output directory |
```bash
python3 cli.py combo combine \
uv run python cli.py combo combine \
--alpha-paths alphas/reversal_5d.pq,alphas/reversal_vol_5d_20d.pq \
--combo-name eq --method equal_weight
```
@@ -166,9 +168,9 @@ directory) to stdout, without writing a throwaway script.
| `--info` | off | Show shape + dtypes instead of the rows |
```bash
python3 cli.py pqcat alphas/reversal_5d.pq # dump all rows
python3 cli.py pqcat data/daily_bars/csi500 --info # shape + dtypes
python3 cli.py pqcat data/daily_bars/csi500 -n 10 -c symbol_id,date,close,vwap
uv run python cli.py pqcat alphas/reversal_5d.pq # dump all rows
uv run python cli.py pqcat data/daily_bars/csi500 --info # shape + dtypes
uv run python cli.py pqcat data/daily_bars/csi500 -n 10 -c symbol_id,date,close,vwap
```
**Standalone command.** `tools/pqcat.py` has no repo dependencies, so it can be
@@ -195,7 +197,7 @@ volume over a time range.
| `-c, --columns` | `close,volume` | Comma-separated bar columns to show |
```bash
python3 cli.py alphaview \
uv run python cli.py alphaview \
--data-path data/daily_bars/csi500 \
--alpha-path alphas/reversal_5d.pq,alphas/momentum_5d.pq \
--symbol sh600000 --start-date 2024-01-01 --end-date 2024-03-31 \
@@ -260,7 +262,7 @@ with `--alpha-module` (a `.py` path or an importable dotted module). See the
worked example in `examples/alphas/mean_reversion.py`:
```bash
python3 cli.py alpha compute \
uv run python cli.py alpha compute \
--alpha-module examples/alphas/mean_reversion.py \
--alpha-type mean_reversion --alpha-name mr20 \
--param window=20 \
pyproject.toml
+22
View File
@@ -0,0 +1,22 @@
[project]
name = "chinese-equity-quant"
version = "0.1.0"
description = "A modular Chinese A-share quant research framework (daily frequency)."
requires-python = ">=3.10"
dependencies = [
"backtrader>=1.9.76.123",
"akshare>=1.14.0",
"baostock>=0.8.8",
"pandas>=2.0.0",
"matplotlib>=3.7.0",
"click>=8.0.0",
"pyarrow>=14.0.0",
]
[dependency-groups]
dev = [
"pytest>=7.0.0",
]
[tool.uv]
package = false
requirements.txt
-8
View File
@@ -1,8 +0,0 @@
backtrader>=1.9.76.123
akshare>=1.14.0
baostock>=0.8.8
pandas>=2.0.0
matplotlib>=3.7.0
pytest>=7.0.0
click>=8.0.0
pyarrow>=14.0.0
uv.lock
Generated
+1720
View File
File diff suppressed because it is too large Load Diff