Metadata-Version: 2.4
Name: atabet-data
Version: 1.0.0
Summary: Atabet-Data: A data retrieval library for financial data from multiple sources
Author: Joseph Chen
Author-email: Joseph Chen <josephchenhk@gmail.com>
Maintainer: Joseph Chen
Maintainer-email: Joseph Chen <josephchenhk@gmail.com>
License: Proprietary
Keywords: finance,data,bloomberg,tushare,xtdata,yahoo
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: tqdm
Provides-Extra: auth
Requires-Dist: atabet-token; extra == "auth"
Provides-Extra: blpapi
Requires-Dist: blpapi; extra == "blpapi"
Requires-Dist: xbbg; extra == "blpapi"
Provides-Extra: bql
Requires-Dist: bql; extra == "bql"
Provides-Extra: tushare
Requires-Dist: tushare; extra == "tushare"
Provides-Extra: xtdata
Requires-Dist: xtquant; extra == "xtdata"
Provides-Extra: yahoo
Requires-Dist: yfinance; extra == "yahoo"
Provides-Extra: all
Requires-Dist: atabet-token; extra == "all"
Requires-Dist: blpapi; extra == "all"
Requires-Dist: xbbg; extra == "all"
Requires-Dist: bql; extra == "all"
Requires-Dist: tushare; extra == "all"
Requires-Dist: xtquant; extra == "all"
Requires-Dist: yfinance; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: author
Dynamic: maintainer

# Atabet-Data

A data retrieval library for financial data from multiple sources with token-based authentication.

## Authentication

Atabet-Data uses token-based authentication. **Token authentication is mandatory** for all API calls.

### Using the AtabetData Class

All API access is through the `AtabetData` class, which validates authentication tokens:

```python
from atabet_data import AtabetData

# Create client with a valid authentication token
client = AtabetData(token=your_token)

# Use the client to access data APIs
data = client.get_data(
    tickers=['AAPL US Equity'],
    flds=['PX_LAST'],
    source='bql'
)

# All methods are available
historical = client.get_historical_data(
    tickers=['AAPL US Equity'],
    flds=['PX_LAST'],
    start='2025-01-01',
    end='2025-01-31',
    source='bql'
)
```

**Note:** 
- Token authentication is **mandatory** and validated when creating the `AtabetData` instance
- If an invalid token is provided, `InvalidTokenError` is raised during initialization
- Once initialized, all methods can be called without additional authentication
- Contact the administrator to obtain a valid authentication token

### Yahoo Finance (`source='yahoo'`)

Install the optional extra (`pip install atabet-data[yahoo]` or `pip install yfinance`), then pass `source='yahoo'`. Tickers must be Yahoo symbols (for example `AAPL`, `700.HK`, `^GSPC`), not Bloomberg-style identifiers. Supported fields are `PX_OPEN`, `PX_HIGH`, `PX_LOW`, `PX_LAST`, and `PX_VOLUME` for snapshot and daily history. `get_datasets`, `get_mem_weights`, and `run_query` are not implemented for this channel.

### Available Methods

The `AtabetData` class provides the following methods:
- `get_data()` - Get current snapshot data
- `get_historical_data()` - Get historical data
- `get_datasets()` - Get datasets data
- `get_mem_weights()` - Get index members weights
- `run_query()` - Run raw queries

## Technical Analysis (`ta` accessor)

Atabet-Data ships with a built-in technical analysis module. Any OHLCV DataFrame
can compute indicators directly via the `.ta` accessor (no external dependency
required):

```python
from atabet_data import AtabetData

client = AtabetData(token=your_token)
df = client.get_historical_data(
    tickers=["AAPL US Equity"],
    flds=["PX_OPEN", "PX_HIGH", "PX_LOW", "PX_LAST", "PX_VOLUME"],
    start="2024-01-01", end="2024-12-31", source="yahoo",
)
ohlcv = df.ext.to_ohlcv("AAPL US Equity")

# Individual indicators
ohlcv.ta.sma(length=20)        # Simple Moving Average
ohlcv.ta.rsi(length=14)        # Relative Strength Index
ohlcv.ta.macd()                # MACD (returns DataFrame with line/signal/histogram)
ohlcv.ta.bbands(length=20)     # Bollinger Bands
ohlcv.ta.atr(length=14)        # Average True Range
ohlcv.ta.obv()                 # On-Balance Volume

# Append results to the DataFrame
ohlcv.ta.sma(length=50, append=True)
ohlcv.ta.rsi(length=14, append=True)

# Batch: run a preset strategy (Common or All)
ohlcv.ta.strategy("Common")

# Or define a custom strategy
from atabet_data.ta.strategy import Strategy
my_strat = Strategy(name="Quick", ta=[
    {"kind": "ema", "length": 9},
    {"kind": "rsi", "length": 7},
    {"kind": "bbands", "length": 20, "std": 2.5},
])
ohlcv.ta.strategy(my_strat)
```

### Indicator categories

| Category | Indicators |
|-------------|------------|
| **Overlap** | `sma`, `ema`, `wma`, `rma`, `dema`, `tema`, `hma`, `vwap`, `hlc3` |
| **Momentum** | `rsi`, `macd`, `stoch`, `roc`, `cci`, `willr`, `mfi` |
| **Trend** | `adx`, `aroon`, `psar` |
| **Volatility** | `true_range`, `atr`, `bbands`, `kc`, `donchian` |
| **Volume** | `obv`, `ad`, `adosc`, `cmf` |
| **Statistics** | `stdev`, `variance`, `mad`, `zscore` |
| **Performance** | `log_return`, `percent_return`, `drawdown` |

### Functional API

All indicators are also available as standalone functions:

```python
from atabet_data.ta import sma, rsi, macd
sma(ohlcv["close"], length=20)
rsi(ohlcv["close"], length=14)
```

### Custom indicators

Register your own indicators at runtime:

```python
from atabet_data.ta.custom import bind, create_dir, import_dir

# Scaffold a directory tree, write custom modules, then import them
create_dir("~/my_indicators")
import_dir("~/my_indicators")
```

See `samples/ta_example.py` for a complete walkthrough.

## Environment preparations


```bash
conda create -n py39_atabet_data python=3.9
conda activate py39_atabet_data
(py39_atabet_data_test) conda install conda-forge::cython
(py39_atabet_data_test) conda install anaconda::pandas
(py39_atabet_data_test) conda install anaconda::setuptools # Windows
```


### Packaging

```bash
# Basic usage - will cythonize all .py files including __init__.py
python atabet-data/run_packaging.py

# Remove source files from the wheel
python atabet-data/run_packaging.py --remove-source

# Specify a different module name, version, or distribution directory
python run_packaging.py --module="my-module" --version="2.0.0" --dist-dir="dist"

# Combine options
python run_packaging.py --remove-source --module="my-module" --version="2.0.0"
```

### Test

```bash
conda create -n py39_atabet_data_test python=3.9
conda activate py39_atabet_data_test
(py39_atabet_data_test) conda install anaconda::pandas
(py39_atabet_data_test) pip install jquant/atabet_data-1.0.0-cp39-cp39-macosx_10_15_x86_64.whl # (Mac OS/Linux)
(py39_atabet_data_test) pip install .\jquant\atabet_data-1.0.0-cp39-cp39-win_amd64.whl # (Windows)
(py39_atabet_data_test) pip install tushare --upgrade
(py39_atabet_data_test) python atabet-data/test.py
```

## GitHub Actions: wheels and PyPI

Workflow: [`.github/workflows/build-wheels.yml`](.github/workflows/build-wheels.yml). Wheels are built with [cibuildwheel](https://cibuildwheel.readthedocs.io/); options live in [`pyproject.toml`](pyproject.toml) under `[tool.cibuildwheel]`.

**When jobs run (push):** the Linux / Windows / macOS matrix runs only if the **head commit message** includes one of:

| Tag | Effect |
|-----|--------|
| `[build ci]` (or `[Build CI]`, `[BUILD CI]`) | Build wheels and upload per-OS artifacts; no publish. |
| `[pub pypi]` (or `[Pub PyPI]`, `[PUB PYPI]`) | Build wheels, then publish merged wheels to [PyPI](https://pypi.org/) (production). |
| `[pub test.pypi]` (or `[Pub test.pypi]`, `[PUB TEST.PYPI]`) | Build wheels, then publish to [TestPyPI](https://test.pypi.org/). |

Plain pushes (no tag above) skip the matrix so CI does not run on every commit.

**Manual runs:** **Actions → Build wheels → Run workflow** runs the build matrix only; publishing is by **push** with `[pub pypi]` or `[pub test.pypi]` in the commit message.

**Authentication (publish):** the workflow uses **Trusted Publishing (OIDC)** by default — no API token in GitHub secrets. Register the GitHub repo and workflow file on each index (project **Manage → Publishing**). See the comment block at the top of `build-wheels.yml` for OIDC vs API-token options.

Private repositories are supported for OIDC the same as public ones.
