Metadata-Version: 2.4
Name: jing
Version: 0.4.2
Summary: Download stock data and perform data analisys
Author-email: sai <dawangfei@gmail.com>
License: MIT
Keywords: jing,sai,stock
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: pandas
Requires-Dist: baostock
Requires-Dist: yfinance
Requires-Dist: akshare
Requires-Dist: pyarrow
Requires-Dist: cos-python-sdk-v5
Requires-Dist: importlib-metadata; python_version < "3.10"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"

# jing

`jing` downloads and organizes stock market data. The examples below use China A-share stocks with BaoStock.

## Install

```bash
pip install jing
```

## Download CN data

BaoStock is the default data source for CN. Stock codes must include an exchange prefix, such as `sh.` or `sz.`.

```python
import jing

d = jing.D("cn")
d.download("sz.000807")  # Download one stock
d.download()             # Download the stocks in the default list
```

Batch downloads use `~/data/jing/list/cn_baostock.txt` by default. On first use, `jing` copies the bundled list there; edit this copy to maintain your stock list.

## File locations

The default data directory is `~/data/jing`:

```text
~/data/jing/
├── list/cn_baostock.txt
└── raw/baostock/cn/sz.000807.csv
```

Set `JING_DATA` to use another directory:

```bash
export JING_DATA=/data/stocks
```

Or set the data directory from Python:

```python
from jing.data_paths import set_data_root

set_data_root("/data/stocks")
```

The stock list and CSV files will then be stored under `/data/stocks/list/` and `/data/stocks/raw/baostock/cn/`.

## Run daily on a server

`deploy/` holds the cron entry point. It is a deployment script, not part of the
`jing` package: `jing` only downloads and uploads, `deploy/daily.py` schedules
that.

```bash
sudo mkdir -p /opt/jing /data/jing /var/log/jing
sudo git clone <this repo> /opt/jing
cd /opt/jing && python3 -m venv .venv && .venv/bin/pip install -e .

sudo install -m 600 deploy/env.example /etc/jing/env
sudo $EDITOR /etc/jing/env          # fill in JING_COS_SECRET_ID / _KEY

.venv/bin/python deploy/daily.py us   # smoke test on one market
crontab deploy/jing.cron              # weekdays 20:00 Asia/Shanghai
```

`run_daily.sh` loads `/etc/jing/env` (cron has no login shell), takes a `flock`
so a slow run cannot overlap the next one, and writes `/var/log/jing/<date>.log`
(kept 14 days).

Notes:

- **Interrupted runs resume.** Each stock's CSV is the ledger, so the next run
  only downloads what is missing. Running out of the time budget is a normal
  outcome, not a failure.
- **Concurrency**: `JING_MAX_WORKERS` overrides the built-in worker count (3
  for BaoStock, 10 otherwise). The server sets it to 1 — one request at a
  time from one IP is the cheapest insurance against being rate limited.
  `D.download(max_workers=N)` overrides it per call.
- **akshare timeouts**: akshare's requests carry no timeout, so `jing` patches
  `requests.sessions.Session.request` to inject one (`JING_HTTP_TIMEOUT`,
  default 30s, 0 disables). `socket.setdefaulttimeout()` cannot do this —
  urllib3 passes its own `None` down to `sock.settimeout()`, overriding it.
- **cn uses BaoStock only.** `cn_ak` (AKShare) covers the same A-shares;
  running both every day doubles the request load for no new data.
