jing 0.3.8

Download stock data and perform data analisys

jing

This is a python library, used for download stock data and perform data analysis.

Installation

pip install jing

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

Usage

4 main classes are exported:

Class	Purpose	Network?	Typical Use
D	Download stock data from internet	Yes (API calls)	One-time download to local CSV
DataCenter	Read local CSV files	No	Load data for analysis
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 internet to 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 market list
d = jing.D('cn')
d.download()  # downloads all stocks in ~/data/jing/list/cn_baostock.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())

DataCenter — Low-level Data Access

Direct access to local CSV data (used internally by Y and X).

from jing.data_center import DataCenter

dc = DataCenter('cn', 'baostock')
df = dc.one('sz.000807')      # read single stock CSV as DataFrame
stocks = dc.list('cn')         # list all available CSV files

Data layout

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/
    binance/bn/
  list/
    us.txt
    cn.txt
    cn_baostock.txt
    hk.txt
    bn.txt

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: ~/data/jing/list/us.txt

Daily 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)

Data flow

flowchart TD
    A["User calls d.download('AAPL')"] --> B{"Check daily parquet cache<br/>~/.cache/jing/data/<br/>us_yahoo_AAPL_2025-05-25.parquet"}
    B -->|Cache exists| C["Read from Parquet<br/>~0.01s"]
    B -->|No cache| D["Download from API<br/>Yahoo Finance / BaoStock / AkShare / Binance"]
    D --> E["Save as CSV<br/>~/data/jing/raw/yahoo/us/AAPL.csv"]
    E --> F["Write Parquet cache<br/>~/.cache/jing/data/<br/>us_yahoo_AAPL_2025-05-25.parquet"]
    C --> G["Return DataFrame"]
    F --> G

    H["User calls d.download()<br/>batch mode"] --> I["Read stock list<br/>~/data/jing/list/us.txt"]
    I --> J["Producer/Consumer<br/>multiprocessing queue"]
    J --> K["Download each stock<br/>with same cache logic"]
    K --> L["Save status<br/>~/.cache/jing/status/<br/>us_ok.txt / us_failed.txt"]

    subgraph "Data Storage"
        E
        I
    end

    subgraph "Daily Cache"
        B
        F
    end

    subgraph "External APIs"
        D
    end

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

Cache

jing caches fetched stock data as Parquet files to speed up repeated analysis.

• Cache dir: ~/.cache/jing/data (override with JING_CACHE env var)
• Cache key: market_source_code_date.parquet

The date in the cache key is the analysis date you pass (e.g. _date='2024-01-01'). If no date is passed, today's date is used. This ensures cached data is scoped to the specific date filter you requested.

Why Parquet?

• Fast reads — columnar format, much faster than CSV for large DataFrames
• Small size — binary + compression (~45% smaller than CSV in our tests)
• Preserves schema — dates, floats, and dtypes survive round-trip without re-parsing
• Pandas-native — pd.read_parquet() / df.to_parquet() with no extra code

Trade-off: requires pyarrow dependency. For repeated stock data reads the speedup is worth it.

Skip cache

y = jing.Y('sh.600519', _date='2024-01-01', _market='cn', skip_cache=True)

Clear cache

from jing.data_center import DataCenter

dc = DataCenter('cn', 'baostock')
dc.clear_cache()                               # clear all
dc.clear_cache(code='sh.600519')               # clear specific stock
dc.clear_cache(code='sh.600519', date='2024-01-01')  # clear specific entry

Release to PyPI

1. Bump the version in pyproject.toml:

   version = "0.3.1"
   

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.