Metadata-Version: 2.4
Name: jing
Version: 0.3.5
Summary: Download stock data and perform data analisys
Author-email: sai <sai@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: importlib-metadata; python_version < "3.10"

# jing

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

## Installation

```bash
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.

```python
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.

```python
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.

```python
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`).

```python
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):

```text
~/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:

```text
~/.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)

## Configuration

### Data directory

Priority (highest first):

1. **Function call** — programmatic override
   ```python
   from jing.data_paths import set_data_root
   set_data_root('/custom/data/path')
   ```

2. **Environment variable**
   ```bash
   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

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

### Clear cache

```python
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`:
   ```toml
   version = "0.3.1"
   ```

2. Build the distribution packages:
   ```bash
   python -m build
   ```

3. Upload to PyPI:
   ```bash
   python -m twine upload dist/*
   ```

   > You will need a PyPI account and [API token](https://pypi.org/manage/account/token/). Configure twine once with `python -m twine upload --repository testpypi dist/*` to test first if desired.
