candlestix 3.0.1

Library to get candlesticks info

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:

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:

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

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

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

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:

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:

./build.sh

The build script deletes:

• build/
• dist/
• candlestix.egg-info/

Then builds the wheel using:

python3 -m build --wheel

Build And Install

./build.sh -i

or

./build.sh --install

Verify:

pip list | grep candlestix

Uninstall

pip uninstall candlestix
pip list | grep candlestix

Upload

Upload to PyPI:

twine upload dist/*

Install twine if needed:

pip install twine