jing 0.3.10

Download stock data and perform data analisys

jing

jing is a Python library for downloading stock price data to local CSV files and running simple technical analysis or batch stock selection.

Installation

pip install jing

All required dependencies (requests, pandas, baostock, yfinance, akshare, pyarrow) will be installed automatically.

Quickstart

import jing

# 1. Download AAPL data to local CSV
jing.D('us').download('AAPL')

# 2. Analyze it
y = jing.Y('AAPL', _market='us')
print(y.ref.ma20(0))    # 20-day MA
print(y.ref.macd(0))    # MACD

Main APIs

The core workflow uses three public classes:

Class	Purpose	Network?	Typical Use
D	Download market data	Yes (API calls)	Fetch one stock or a batch list to local CSV
Y	Analyze single stock	No	Technical indicators (MA, MACD, etc.)
X	Select stocks by rules	No	Batch screening / backtesting

D — Downloader

Download stock data from Yahoo Finance, BaoStock, or AkShare into local CSV files.

import jing

# US stock via Yahoo Finance
d = jing.D('us')
d.download('AAPL')

# CN stock via BaoStock (default source for CN)
d = jing.D('cn')
d.download('sz.000807')

# HK stock via AkShare
d = jing.D('hk')
d.download('00700')

# Batch download all stocks in the default CN BaoStock list
d = jing.D('cn')
d.download()  # downloads all stocks in ~/data/jing/list/cn_baostock.txt

# Batch download CN via AkShare instead
d = jing.D('cn', _source='akshare')
d.download()  # downloads all stocks in ~/data/jing/list/cn_ak.txt

Y — Single Stock Analyzer

Analyze a single stock with technical indicators.

y = jing.Y('AAPL', _date='2024-09-27', _market='us')

# Technical indicators
print(y.ref.ma20(0))    # 20-day moving average
print(y.ref.ma50(0))    # 50-day moving average
print(y.ref.ma200(0))   # 200-day moving average
print(y.ref.macd(0))    # MACD value
print(y.ref.diff(0))    # DIFF line
print(y.ref.dea(0))     # DEA line
print(y.ref.vma50(0))   # 50-day volume MA

X — Stock Selector

Batch select stocks by applying rules.

x = jing.X('us', '2024-09-27')
x.add_rule(jing.RuleSimple)
x.add_rule(jing.RuleMa50Ma200)
x.run()
print(x.get_result())

Data Storage

The project uses a source-first layout under ~/data/jing/ (override with JING_DATA env var):

~/data/jing/
  raw/
    yahoo/us/
    baostock/cn/
    akshare/cn/
    akshare/hk/
  list/
    us.txt
    cn_ak.txt
    cn_baostock.txt
    hk.txt

Raw CSV examples:

• US Yahoo CSV: ~/data/jing/raw/yahoo/us/AAPL.csv
• CN BaoStock CSV: ~/data/jing/raw/baostock/cn/sh.601088.csv
• HK AkShare CSV: ~/data/jing/raw/akshare/hk/00700.csv

List files

List files are used only for batch downloads, for example jing.D('us').download() or jing.D('cn').download(). Single-stock downloads use the code you pass directly.

On first use, jing creates ~/data/jing/list/ and copies the bundled default lists there. Edit the files under ~/data/jing/list/; do not edit the package files under jing/lists/ unless you are changing the project defaults.

Market/source	Downloader call	List file	Code format
US Yahoo	jing.D('us')	us.txt	Yahoo ticker, e.g. AAPL
CN BaoStock (default CN)	jing.D('cn')	cn_baostock.txt	BaoStock code with exchange prefix, e.g. sh.601088 or sz.000807
CN AkShare	jing.D('cn', _source='akshare')	cn_ak.txt	6-digit A-share code, e.g. 601088
HK AkShare	jing.D('hk')	hk.txt	5-digit HK code, e.g. 00700

For CN, use cn_baostock.txt unless you explicitly pass _source='akshare'. The default jing.D('cn') downloader is BaoStock, and BaoStock requires exchange-prefixed codes.

Minimal examples:

~/data/jing/list/cn_baostock.txt

sh.601088
sz.000807
sh.600519

~/data/jing/list/cn_ak.txt

601088
000807
600519

~/data/jing/list/us.txt

AAPL
MSFT
NVDA

~/data/jing/list/hk.txt

00700
09988
03690

Batch download calls:

import jing

jing.D('cn').download()                       # reads cn_baostock.txt
jing.D('cn', _source='akshare').download()    # reads cn_ak.txt
jing.D('us').download()                       # reads us.txt
jing.D('hk').download()                       # reads hk.txt

Download cache

Downloaded data is cached as Parquet files to avoid repeated API calls on the same day:

~/.cache/jing/data/
  cn_baostock_sz_000807_2025-05-25.parquet
  us_yahoo_AAPL_2025-05-25.parquet

Cache pattern: <market>_<source>_<code>_<date>.parquet

• If cache exists for today → read from Parquet (fast, ~0.01s)
• If no cache → download from API, save CSV, and write Parquet cache
• New day → automatic fresh download (old cache ignored)
• Override the cache root with JING_CACHE

Data flow

Single stock

flowchart LR
    A["d.download('AAPL')"] --> B{Cache exists?}
    B -->|Yes| C[Read Parquet]
    B -->|No| D[Download from API]
    D --> E[Save CSV]
    E --> F[Write Parquet cache]
    C --> G[Return DataFrame]
    F --> G

Batch download

flowchart LR
    A["d.download()"] --> B[Read stock list]
    B --> C[Queue stocks]
    C --> D[Download each]
    D --> E[Print summary]

Configuration

Data directory

Priority (highest first):

1. Function call — programmatic override

   from jing.data_paths import set_data_root
   set_data_root('/custom/data/path')
   

2. Environment variable

   export JING_DATA=/custom/data/path
   

3. Default — ~/data/jing

Release to PyPI

1. Bump the version in pyproject.toml:

   version = "0.3.9"
   

2. Build the distribution packages:

   python -m build
   

3. Upload to PyPI:

   python -m twine upload dist/*
   

   You will need a PyPI account and API token. Configure twine once with python -m twine upload --repository testpypi dist/* to test first if desired.