Metadata-Version: 2.4
Name: candlestix
Version: 3.0.1
Summary: Library to get candlesticks info
Home-page: https://github.com/sharmaak/candlestix
Author: Amit Kumar Sharma
Author-email: amit.official@gmail.com
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: upstox-python-sdk>=2.21.0
Requires-Dist: pandas
Requires-Dist: requests
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# candlestix

Python package for fetching and working with candlestick data, focused on Indian markets.

`candlestix 3.0.0` uses Upstox History V3 for market candles and keeps the main
loader contract stable:

```python
CandleDataLoader().candles(symbol, exchange, candle_length, duration_in_days=-1)
```

## What Changed In 3.0.0

- Upstox candle loading now uses `HistoryV3Api`
- Historical requests are split into API-safe batches and stitched together
- Native candle sizes are requested from Upstox instead of resampling old V2 data
- Current-day candles are fetched separately and merged with historical candles

The public candle-loading entry point remains `CandleDataLoader`.

## Core Concepts

### 1. Instrument bootstrap

Before using the Upstox-backed loader, initialize the package:

```python
import candlestix

candlestix.init()
```

This:
- creates a cache directory under the system temp directory
- downloads the Upstox instrument master
- builds in-memory lookup tables for NSE and BSE symbols

Without `candlestix.init()`, symbol-based Upstox candle fetches will not resolve instrument keys.

### 2. Upstox-backed candle loader

Main file: `candlestix/candle_loader.py`

Responsibilities:
- map public `CandleLength` values to Upstox V3 `unit` and `interval`
- enforce historical API fetch limits
- fetch current-day intraday candles separately
- combine and sort candle data
- cache historical results on disk

### 3. Chitragupt HTTP loader

Main file: `candlestix/candle_loader_ctg.py`

This is a separate lightweight loader for a plain HTTP API. It does not depend on:
- Upstox SDK
- instrument bootstrap
- local file caching

## Supported Candle Lengths

Public candle lengths are defined in `candlestix/candleconf.py`.

The core loader currently supports:
- `ONE_MIN`
- `FIVE_MIN`
- `TEN_MIN`
- `FIFTEEN_MIN`
- `THIRTY_MIN`
- `ONE_HOUR`
- `DAY`

`WEEK` and `MONTH` remain in the enum for compatibility, but are not directly fetched by `CandleDataLoader`.

## Upstox V3 Fetch Strategy

Upstox imposes limits on how much historical data can be fetched in one request.
`CandleDataLoader` handles this internally by splitting the requested date range
into multiple batches and concatenating the results.

Current batching strategy:
- `ONE_MIN`, `FIVE_MIN`, `TEN_MIN`, `FIFTEEN_MIN`: 1-month chunks
- `THIRTY_MIN`, `ONE_HOUR`: 3-month chunks
- `DAY`: 10-year chunks

Current-day candles are fetched separately from the intraday endpoint and merged
with historical candles after de-duplication.

## Quick Start

### Upstox loader example

```python
import candlestix
from candlestix import Exchange
from candlestix.candle_loader import CandleDataLoader
from candlestix.candleconf import CandleLength

candlestix.init()

loader = CandleDataLoader()
df = loader.candles("INDHOTEL", Exchange.NSE, CandleLength.ONE_MIN)

print(df.tail())
```

### Index example

```python
import candlestix
from candlestix import Exchange
from candlestix.candle_loader import CandleDataLoader
from candlestix.candleconf import CandleLength

candlestix.init()

loader = CandleDataLoader()
df = loader.candles("NIFTY_50", Exchange.NSE_INDEX, CandleLength.THIRTY_MIN)

print(df.tail())
```

### CTG loader example

```python
from candlestix.candle_loader_ctg import CtgCandleLoader

loader = CtgCandleLoader()
df = loader.df_lookback("OIL", lookback_days=180)

print(df.tail())
```

## Output Contract

### `CandleDataLoader.candles(...)`

Returns a pandas DataFrame:
- index: `date` as `DatetimeIndex`
- columns: `open`, `high`, `low`, `close`, `volume`
- sorted in chronological order

### `CtgCandleLoader.df(...)`

Returns a pandas DataFrame:
- index: `date` as `DatetimeIndex`
- columns: `open`, `high`, `low`, `close`, `volume`, `oi`
- sorted in chronological order

## Dependencies

Core dependencies:
- `upstox-python-sdk>=2.21.0`
- `pandas`

`candle_loader_ctg.py` also uses `requests`.

## Development Notes

Focused tests added for the V3 rewrite:
- Upstox batching and interval mapping: `test/test_candle_loader_v3.py`
- CTG loader behavior: `test/test_candle_loader_ctg.py`

Run them with the project virtualenv:

```bash
venv/bin/python -m unittest discover -s test -p 'test_candle_loader_v3.py' -v
venv/bin/python -m unittest discover -s test -p 'test_candle_loader_ctg.py' -v
```

## Build

Before building, update the project version in `setup.py`.

Build from project root:

```bash
./build.sh
```

The build script deletes:
- `build/`
- `dist/`
- `candlestix.egg-info/`

Then builds the wheel using:

```bash
python3 -m build --wheel
```

## Build And Install

```bash
./build.sh -i
```

or

```bash
./build.sh --install
```

Verify:

```bash
pip list | grep candlestix
```

## Uninstall

```bash
pip uninstall candlestix
pip list | grep candlestix
```

## Upload

Upload to PyPI:

```bash
twine upload dist/*
```

Install `twine` if needed:

```bash
pip install twine
```
