pyzdata 1.0.0__tar.gz

pyzdata-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Vikas Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyzdata-1.0.0/PKG-INFO

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: pyzdata
+Version: 1.0.0
+Summary: Historical OHLCV market data downloader for Zerodha (Kite API)
+Author-email: Vikas Sharma <Jnv2252@Gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/vikassharma545/Historical-Market-data-From-Zerodha
+Project-URL: Repository, https://github.com/vikassharma545/Historical-Market-data-From-Zerodha
+Project-URL: Issues, https://github.com/vikassharma545/Historical-Market-data-From-Zerodha/issues
+Keywords: zerodha,kite,market-data,ohlcv,trading,finance,india
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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 :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: urllib3>=1.26.0
+Provides-Extra: web
+Requires-Dist: streamlit>=1.20.0; extra == "web"
+Requires-Dist: openpyxl>=3.0.0; extra == "web"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10; extra == "dev"
+Dynamic: license-file
+
+# PyZData – Zerodha Historical Market Data Downloader
+
+![Python](https://img.shields.io/badge/python-3.8%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![GitHub repo size](https://img.shields.io/github/repo-size/vikassharma545/Historical-Market-data-From-Zerodha)
+![GitHub last commit](https://img.shields.io/github/last-commit/vikassharma545/Historical-Market-data-From-Zerodha)
+![GitHub stars](https://img.shields.io/github/stars/vikassharma545/Historical-Market-data-From-Zerodha?style=social)
+
+Download historical OHLCV and Open Interest candle data for any stock, index, or F&O instrument from **Zerodha** — as a Python library, a CLI command, or a browser-based web app.
+
+---
+
+## What you can do with PyZData
+
+- Download price history for **any stock or index** listed on Zerodha (NSE, BSE, NFO, MCX)
+- Choose intervals from **1-minute to daily**
+- Export clean **pandas DataFrames** ready for backtesting, charting, or ML
+- Use the **web app** — no coding needed
+- Use the **CLI** — one-liner downloads from the terminal
+- Use the **Python library** — import and integrate into your own scripts
+
+---
+
+## Web Interface (no coding required)
+
+The easiest way to use PyZData is the built-in Streamlit web app.
+
+**Run it:**
+
+```bash
+pip install "git+https://github.com/vikassharma545/Historical-Market-data-From-Zerodha.git#egg=pyzdata[web]"
+pyzdata-web
+```
+
+Then open `http://localhost:8501` in your browser.
+
+**Features:**
+- Click popular stocks (NIFTY 50, RELIANCE, TCS, HDFC Bank …) — no typing needed
+- Quick date presets: Last Week, Last Month, Last Year, Last 3 Years …
+- Plain-English frequency selector with descriptions
+- Download result as **CSV** or **Excel (.xlsx)**
+- Built-in Help tab with step-by-step guides
+
+---
+
+## Installation
+
+```bash
+# Library only (Python API + CLI)
+pip install git+https://github.com/vikassharma545/Historical-Market-data-From-Zerodha.git
+
+# Library + web interface (adds streamlit and openpyxl)
+pip install "git+https://github.com/vikassharma545/Historical-Market-data-From-Zerodha.git#egg=pyzdata[web]"
+```
+
+**Requirements:** Python 3.8+, pandas ≥ 1.3, requests ≥ 2.25
+
+For development:
+
+```bash
+git clone https://github.com/vikassharma545/Historical-Market-data-From-Zerodha.git
+cd Historical-Market-data-From-Zerodha
+pip install -e ".[web,dev]"
+```
+
+---
+
+## Python Library
+
+```python
+from pyzdata import PyZData, Interval
+
+# Login with enctoken (paste from browser cookies after logging into kite.zerodha.com)
+client = PyZData(enctoken="your_enctoken_here")
+
+# OR login with credentials
+client = PyZData(user_id="AB1234", password="your_password", totp="123456")
+
+# Find the instrument token for a symbol
+token = client.get_instrument_token("NIFTY 50", "NSE")
+
+# Not sure of the exact symbol name? Search for it
+results = client.search_instruments("NIFTY", exchange="NSE")
+print(results[["tradingsymbol", "instrument_token", "exchange"]])
+
+# Download daily candles for a full year
+df = client.get_data(token, "2024-01-01", "2024-12-31", Interval.DAY)
+print(df.head())
+
+# Download 1-minute candles with Open Interest (F&O instruments)
+fut_token = client.get_instrument_token("NIFTY24JANFUT", "NFO")
+df = client.get_data(fut_token, "2024-01-02", "2024-01-25", Interval.MINUTE_1, oi=True)
+```
+
+**Output columns:** `tradingsymbol, datetime, open, high, low, close, volume` (+ `open_interest` when `oi=True`)
+
+---
+
+## CLI
+
+```bash
+# Daily data for NIFTY 50 — print to terminal
+pyzdata download --enctoken TOKEN --symbol "NIFTY 50" --exchange NSE \
+        --start 2024-01-01 --end 2024-12-31
+
+# 1-minute data — save to CSV
+pyzdata download --enctoken TOKEN --symbol RELIANCE --exchange NSE \
+        --start 2024-01-01 --end 2024-06-30 \
+        --interval minute --output reliance.csv
+
+# Login with credentials
+pyzdata download --user-id AB1234 --password pw --totp 123456 \
+        --symbol RELIANCE --exchange NSE \
+        --start 2024-01-01 --end 2024-01-31
+
+# Search for a symbol
+pyzdata search --enctoken TOKEN --query HDFC --exchange NSE
+
+# All options
+pyzdata download --help
+pyzdata search --help
+```
+
+---
+
+## Available Intervals
+
+| Enum | Interval | Best for |
+|------|----------|----------|
+| `Interval.MINUTE_1` | 1 minute | Intraday scalping analysis |
+| `Interval.MINUTE_5` | 5 minutes | Intraday charts |
+| `Interval.MINUTE_15` | 15 minutes | Intraday / short-term |
+| `Interval.MINUTE_30` | 30 minutes | Swing trading |
+| `Interval.HOUR_1` | 1 hour | Swing / positional |
+| `Interval.DAY` | Daily | Long-term investing & backtesting |
+
+---
+
+## Configuration
+
+Copy `.env.example` to `.env` and set any values you want to override:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PYZDATA_MAX_WORKERS` | `4` | Parallel download threads |
+| `PYZDATA_MAX_RETRIES` | `5` | Retry attempts on failures |
+| `PYZDATA_TIMEOUT` | `30` | HTTP timeout in seconds |
+| `PYZDATA_CACHE_TTL_HOURS` | `24` | How long to cache the instruments list |
+| `PYZDATA_LOG_LEVEL` | `WARNING` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
+
+Or pass a `Config` object in code:
+
+```python
+from pyzdata import Config, PyZData
+
+cfg = Config(max_workers=8, log_level="DEBUG")
+client = PyZData(enctoken="...", config=cfg)
+```
+
+---
+
+## Error Handling
+
+```python
+from pyzdata.exceptions import (
+    AuthenticationError,    # wrong credentials or expired enctoken
+    InstrumentNotFoundError, # symbol not found
+    DataFetchError,          # API or network failure
+    PyZDataError,            # catch-all base class
+)
+
+try:
+    client = PyZData(enctoken="...")
+    token  = client.get_instrument_token("RELIANCE", "NSE")
+    df     = client.get_data(token, "2024-01-01", "2024-12-31", Interval.DAY)
+except AuthenticationError as e:
+    print(f"Login failed: {e}")
+except InstrumentNotFoundError as e:
+    print(f"Symbol not found: {e}")
+except DataFetchError as e:
+    print(f"Download failed: {e}")
+```
+
+---
+
+## Project Structure
+
+```
+pyzdata/
+├── client.py        PyZData — main entry point
+├── auth.py          Two-step Zerodha login
+├── instruments.py   Symbol lookup with 24-hour disk cache
+├── downloader.py    Parallel monthly data fetching
+├── models.py        Interval enum
+├── config.py        Settings + environment variable loading
+├── exceptions.py    Typed exception hierarchy
+├── cli.py           pyzdata command-line tool
+├── _app.py          Streamlit web interface
+└── py.typed         PEP 561 type-checking marker
+
+app.py               Local dev launcher for Streamlit
+tests/               Unit tests (no credentials needed)
+CONTRIBUTING.md      How to contribute
+CHANGELOG.md         Release history
+SECURITY.md          Security policy
+```
+
+---
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+No Zerodha account or internet connection needed — all HTTP calls are mocked.
+
+---
+
+## How to get your enctoken
+
+1. Log in to [kite.zerodha.com](https://kite.zerodha.com)
+2. Press **F12** → **Application** tab → **Cookies** → `kite.zerodha.com`
+3. Copy the value of the `enctoken` cookie
+4. Paste it into the app or pass it as `PyZData(enctoken="...")`
+
+The enctoken refreshes each time you log in to Kite.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.
+
+## Security
+
+To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
+## Author
+
+Built by [Vikas Sharma](https://github.com/vikassharma545)

pyzdata-1.0.0/README.md

@@ -0,0 +1,250 @@
+# PyZData – Zerodha Historical Market Data Downloader
+
+![Python](https://img.shields.io/badge/python-3.8%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![GitHub repo size](https://img.shields.io/github/repo-size/vikassharma545/Historical-Market-data-From-Zerodha)
+![GitHub last commit](https://img.shields.io/github/last-commit/vikassharma545/Historical-Market-data-From-Zerodha)
+![GitHub stars](https://img.shields.io/github/stars/vikassharma545/Historical-Market-data-From-Zerodha?style=social)
+
+Download historical OHLCV and Open Interest candle data for any stock, index, or F&O instrument from **Zerodha** — as a Python library, a CLI command, or a browser-based web app.
+
+---
+
+## What you can do with PyZData
+
+- Download price history for **any stock or index** listed on Zerodha (NSE, BSE, NFO, MCX)
+- Choose intervals from **1-minute to daily**
+- Export clean **pandas DataFrames** ready for backtesting, charting, or ML
+- Use the **web app** — no coding needed
+- Use the **CLI** — one-liner downloads from the terminal
+- Use the **Python library** — import and integrate into your own scripts
+
+---
+
+## Web Interface (no coding required)
+
+The easiest way to use PyZData is the built-in Streamlit web app.
+
+**Run it:**
+
+```bash
+pip install "git+https://github.com/vikassharma545/Historical-Market-data-From-Zerodha.git#egg=pyzdata[web]"
+pyzdata-web
+```
+
+Then open `http://localhost:8501` in your browser.
+
+**Features:**
+- Click popular stocks (NIFTY 50, RELIANCE, TCS, HDFC Bank …) — no typing needed
+- Quick date presets: Last Week, Last Month, Last Year, Last 3 Years …
+- Plain-English frequency selector with descriptions
+- Download result as **CSV** or **Excel (.xlsx)**
+- Built-in Help tab with step-by-step guides
+
+---
+
+## Installation
+
+```bash
+# Library only (Python API + CLI)
+pip install git+https://github.com/vikassharma545/Historical-Market-data-From-Zerodha.git
+
+# Library + web interface (adds streamlit and openpyxl)
+pip install "git+https://github.com/vikassharma545/Historical-Market-data-From-Zerodha.git#egg=pyzdata[web]"
+```
+
+**Requirements:** Python 3.8+, pandas ≥ 1.3, requests ≥ 2.25
+
+For development:
+
+```bash
+git clone https://github.com/vikassharma545/Historical-Market-data-From-Zerodha.git
+cd Historical-Market-data-From-Zerodha
+pip install -e ".[web,dev]"
+```
+
+---
+
+## Python Library
+
+```python
+from pyzdata import PyZData, Interval
+
+# Login with enctoken (paste from browser cookies after logging into kite.zerodha.com)
+client = PyZData(enctoken="your_enctoken_here")
+
+# OR login with credentials
+client = PyZData(user_id="AB1234", password="your_password", totp="123456")
+
+# Find the instrument token for a symbol
+token = client.get_instrument_token("NIFTY 50", "NSE")
+
+# Not sure of the exact symbol name? Search for it
+results = client.search_instruments("NIFTY", exchange="NSE")
+print(results[["tradingsymbol", "instrument_token", "exchange"]])
+
+# Download daily candles for a full year
+df = client.get_data(token, "2024-01-01", "2024-12-31", Interval.DAY)
+print(df.head())
+
+# Download 1-minute candles with Open Interest (F&O instruments)
+fut_token = client.get_instrument_token("NIFTY24JANFUT", "NFO")
+df = client.get_data(fut_token, "2024-01-02", "2024-01-25", Interval.MINUTE_1, oi=True)
+```
+
+**Output columns:** `tradingsymbol, datetime, open, high, low, close, volume` (+ `open_interest` when `oi=True`)
+
+---
+
+## CLI
+
+```bash
+# Daily data for NIFTY 50 — print to terminal
+pyzdata download --enctoken TOKEN --symbol "NIFTY 50" --exchange NSE \
+        --start 2024-01-01 --end 2024-12-31
+
+# 1-minute data — save to CSV
+pyzdata download --enctoken TOKEN --symbol RELIANCE --exchange NSE \
+        --start 2024-01-01 --end 2024-06-30 \
+        --interval minute --output reliance.csv
+
+# Login with credentials
+pyzdata download --user-id AB1234 --password pw --totp 123456 \
+        --symbol RELIANCE --exchange NSE \
+        --start 2024-01-01 --end 2024-01-31
+
+# Search for a symbol
+pyzdata search --enctoken TOKEN --query HDFC --exchange NSE
+
+# All options
+pyzdata download --help
+pyzdata search --help
+```
+
+---
+
+## Available Intervals
+
+| Enum | Interval | Best for |
+|------|----------|----------|
+| `Interval.MINUTE_1` | 1 minute | Intraday scalping analysis |
+| `Interval.MINUTE_5` | 5 minutes | Intraday charts |
+| `Interval.MINUTE_15` | 15 minutes | Intraday / short-term |
+| `Interval.MINUTE_30` | 30 minutes | Swing trading |
+| `Interval.HOUR_1` | 1 hour | Swing / positional |
+| `Interval.DAY` | Daily | Long-term investing & backtesting |
+
+---
+
+## Configuration
+
+Copy `.env.example` to `.env` and set any values you want to override:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PYZDATA_MAX_WORKERS` | `4` | Parallel download threads |
+| `PYZDATA_MAX_RETRIES` | `5` | Retry attempts on failures |
+| `PYZDATA_TIMEOUT` | `30` | HTTP timeout in seconds |
+| `PYZDATA_CACHE_TTL_HOURS` | `24` | How long to cache the instruments list |
+| `PYZDATA_LOG_LEVEL` | `WARNING` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
+
+Or pass a `Config` object in code:
+
+```python
+from pyzdata import Config, PyZData
+
+cfg = Config(max_workers=8, log_level="DEBUG")
+client = PyZData(enctoken="...", config=cfg)
+```
+
+---
+
+## Error Handling
+
+```python
+from pyzdata.exceptions import (
+    AuthenticationError,    # wrong credentials or expired enctoken
+    InstrumentNotFoundError, # symbol not found
+    DataFetchError,          # API or network failure
+    PyZDataError,            # catch-all base class
+)
+
+try:
+    client = PyZData(enctoken="...")
+    token  = client.get_instrument_token("RELIANCE", "NSE")
+    df     = client.get_data(token, "2024-01-01", "2024-12-31", Interval.DAY)
+except AuthenticationError as e:
+    print(f"Login failed: {e}")
+except InstrumentNotFoundError as e:
+    print(f"Symbol not found: {e}")
+except DataFetchError as e:
+    print(f"Download failed: {e}")
+```
+
+---
+
+## Project Structure
+
+```
+pyzdata/
+├── client.py        PyZData — main entry point
+├── auth.py          Two-step Zerodha login
+├── instruments.py   Symbol lookup with 24-hour disk cache
+├── downloader.py    Parallel monthly data fetching
+├── models.py        Interval enum
+├── config.py        Settings + environment variable loading
+├── exceptions.py    Typed exception hierarchy
+├── cli.py           pyzdata command-line tool
+├── _app.py          Streamlit web interface
+└── py.typed         PEP 561 type-checking marker
+
+app.py               Local dev launcher for Streamlit
+tests/               Unit tests (no credentials needed)
+CONTRIBUTING.md      How to contribute
+CHANGELOG.md         Release history
+SECURITY.md          Security policy
+```
+
+---
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+No Zerodha account or internet connection needed — all HTTP calls are mocked.
+
+---
+
+## How to get your enctoken
+
+1. Log in to [kite.zerodha.com](https://kite.zerodha.com)
+2. Press **F12** → **Application** tab → **Cookies** → `kite.zerodha.com`
+3. Copy the value of the `enctoken` cookie
+4. Paste it into the app or pass it as `PyZData(enctoken="...")`
+
+The enctoken refreshes each time you log in to Kite.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.
+
+## Security
+
+To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
+## Author
+
+Built by [Vikas Sharma](https://github.com/vikassharma545)

pyzdata-1.0.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyzdata"
+version = "1.0.0"
+description = "Historical OHLCV market data downloader for Zerodha (Kite API)"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Vikas Sharma", email = "Jnv2252@Gmail.com" }
+]
+requires-python = ">=3.8"
+keywords = ["zerodha", "kite", "market-data", "ohlcv", "trading", "finance", "india"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "pandas>=1.3.0",
+    "requests>=2.25.0",
+    "urllib3>=1.26.0",
+]
+
+[project.optional-dependencies]
+# Web interface: pip install "pyzdata[web]"
+web = [
+    "streamlit>=1.20.0",
+    "openpyxl>=3.0.0",
+]
+# Development / testing: pip install "pyzdata[dev]"
+dev = [
+    "pytest>=7.0",
+    "pytest-mock>=3.10",
+]
+
+[project.urls]
+Homepage   = "https://github.com/vikassharma545/Historical-Market-data-From-Zerodha"
+Repository = "https://github.com/vikassharma545/Historical-Market-data-From-Zerodha"
+Issues     = "https://github.com/vikassharma545/Historical-Market-data-From-Zerodha/issues"
+
+[project.scripts]
+pyzdata     = "pyzdata.cli:main"
+pyzdata-web = "pyzdata.run_web:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pyzdata*"]
+
+# ---------------------------------------------------------------------------
+# pytest
+# ---------------------------------------------------------------------------
+[tool.pytest.ini_options]
+testpaths   = ["tests"]
+addopts     = "-v --tb=short"
+
+# ---------------------------------------------------------------------------
+# ruff (optional linting — install with: pip install ruff)
+# ---------------------------------------------------------------------------
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]

pyzdata-1.0.0/pyzdata/__init__.py

@@ -0,0 +1,42 @@
+"""PyZData – Zerodha historical market data downloader.
+
+Quick start::
+
+    from pyzdata import PyZData, Interval
+
+    client = PyZData(enctoken="your_enctoken")
+
+    token = client.get_instrument_token("NIFTY 50", "NSE")
+    df    = client.get_data(token, "2024-01-01", "2024-12-31", Interval.DAY)
+    print(df.head())
+"""
+
+from .client import PyZData
+from .config import Config
+from .exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    DataFetchError,
+    InstrumentNotFoundError,
+    PyZDataError,
+)
+from .models import Interval
+
+__all__ = [
+    "PyZData",
+    "Interval",
+    "Config",
+    # Exceptions — exported so callers can write `except pyzdata.DataFetchError`
+    "PyZDataError",
+    "AuthenticationError",
+    "InstrumentNotFoundError",
+    "DataFetchError",
+    "ConfigurationError",
+]
+
+try:
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("pyzdata")
+except Exception:  # package not installed (editable / dev checkout)
+    __version__ = "0.0.0-dev"