Metadata-Version: 2.4
Name: tv-scraper-py
Version: 0.1.0
Summary: TradingView data scraper with multiple output formats
Home-page: https://github.com/anuragjha0001/tv_scraper
Author: tv-scraper-py
Author-email: anuragjha507@gmail.com
License: MIT
Project-URL: Homepage, https://github.com/anuragjha0001/tv_scraper
Project-URL: Repository, https://github.com/anuragjha0001/tv_scraper.git
Project-URL: Issues, https://github.com/anuragjha0001/tv_scraper/issues
Keywords: tradingview,scraper,crypto,stocks,data
Classifier: Development Status :: 3 - Alpha
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websocket-client>=1.4.0
Provides-Extra: pandas
Requires-Dist: pandas>=1.3.0; extra == "pandas"
Provides-Extra: numpy
Requires-Dist: numpy>=1.20.0; extra == "numpy"
Provides-Extra: ui
Requires-Dist: ipywidgets>=7.7.0; extra == "ui"
Provides-Extra: all
Requires-Dist: tv-view-scraper[numpy,pandas,ui]; extra == "all"
Provides-Extra: dev
Requires-Dist: tv-view-scraper[all]; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Dynamic: author-email
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python


# 📺 TV Scraper

> Fetch historical price data from TradingView in any format you need.

[![PyPI version](https://img.shields.io/badge/pypi-v0.1.0-blue)](https://pypi.org/project/tv_scraper/)
[![Python](https://img.shields.io/badge/python-3.8+-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![GitHub stars](https://img.shields.io/badge/dynamic/json?label=stars&query=%24.stargazers_count&url=https://api.github.com/repos/anuragjha0001/tv_scraper)](https://github.com/anuragjha0001/tv_scraper)

## 📖 Overview

**TV Scraper** is a lightweight yet powerful Python library that fetches historical OHLCV (Open, High, Low, Close, Volume) data from TradingView. Whether you need DataFrames for analysis, NumPy arrays for machine learning, or JSON for APIs — TV Scraper has you covered.

### Why TV Scraper?

- 🚀 **One line to get data** — `df = tv.get("BTCUSDT")`
- 🎨 **7 output formats** — pandas, numpy, arrays, dict, json, csv, raw tuples
- 🧹 **Zero bloat** — Only requires `websocket-client`
- 📊 **ML-ready** — Direct to TensorFlow, PyTorch, or scikit-learn
- 🔄 **Batch fetching** — Get multiple symbols in one call
- 🛡️ **Smart defaults** — Works out of the box, fully customizable
- 🌍 **All TradingView markets** — Crypto, stocks, forex, indices, commodities

---

## 📦 Installation

### Basic Install (DataFrame support)
```bash
pip install tv_scraper[pandas]
```

### ML Install (NumPy arrays)
```bash
pip install tv_scraper[numpy]
```

### Full Install (everything)
```bash
pip install tv_scraper[all]
```

### From GitHub (latest)
```bash
pip install git+https://github.com/anuragjha0001/tv_scraper.git
```

---

## 🚀 Quick Start

```python
from tv_scraper import TvDatafeed

# Create instance
tv = TvDatafeed()

# Get Bitcoin daily data (returns DataFrame)
df = tv.get("BTCUSDT")
print(df.head())
```

**Output:**
```
                       open    high     low   close    volume
timestamp                                                   
2026-04-05 00:00:00  83500.0  84200.0  83400.0  84000.0   125.34
2026-04-06 00:00:00  84000.0  84800.0  83900.0  84600.0   200.50
...
```

---

## 📚 Usage Guide

### 1. Basic Fetching

```python
from tv_scraper import TvDatafeed
from datetime import datetime, timedelta

tv = TvDatafeed()

# Simple - last 30 days daily data
df = tv.get("BTCUSDT")

# With custom parameters
df = tv.get(
    symbol="ETHUSDT",
    exchange="BINANCE",      # Default: BINANCE
    interval="1H",           # 1m, 5m, 15m, 1H, 4H, 1D, 1W, 1M
    start="2024-01-01",      # Start date
    end="2024-01-31",        # End date
)

# Using datetime objects
start = datetime(2024, 1, 1)
end = datetime.now()
df = tv.get("SOLUSDT", start=start, end=end, interval="4H")
```

### 2. All Output Formats

```python
tv = TvDatafeed()

# DataFrame (default)
df = tv.get("BTCUSDT", output_format="pandas")

# NumPy structured array
arr = tv.get("BTCUSDT", output_format="numpy")
print(arr.dtype)  # [('timestamp', '<i8'), ('open', '<f8'), ...]

# Separate arrays (ML-ready)
ts, o, h, l, c, v = tv.get("BTCUSDT", output_format="arrays")

# List of dictionaries (API-ready)
data = tv.get("BTCUSDT", output_format="dict")
# [{"timestamp": 1704067200, "open": 42500.5, ...}, ...]

# JSON string
json_str = tv.get("BTCUSDT", output_format="json", indent=2)

# CSV string
csv_str = tv.get("BTCUSDT", output_format="csv")

# Raw tuples (fastest)
bars = tv.get("BTCUSDT", output_format="raw")
# [(1704067200, 42500.5, 43200.0, 42400.0, 43100.0, 125.34), ...]
```

### 3. Batch Fetching (Multiple Symbols)

```python
tv = TvDatafeed()

results = tv.get_multi([
    {"symbol": "BTCUSDT", "interval": "1H", "output_format": "pandas"},
    {"symbol": "ETHUSDT", "interval": "1H", "output_format": "dict"},
    {"symbol": "SOLUSDT", "interval": "4H", "output_format": "json"},
])

# Access results
btc_df = results["BINANCE:BTCUSDT"]
eth_data = results["BINANCE:ETHUSDT"]
sol_json = results["BINANCE:SOLUSDT"]
```

### 4. ML Pipeline (PyTorch/TensorFlow Ready)

```python
from tv_scraper import TvDatafeed
import numpy as np
import torch

tv = TvDatafeed()

# Get data as separate arrays
ts, opens, highs, lows, closes, volumes = tv.get(
    "BTCUSDT", 
    interval="1H",
    output_format="arrays"
)

# Feature engineering
X = np.column_stack([opens, highs, lows, volumes])
y = np.roll(closes, -1)[:-1]  # Next period's close
X = X[:-1]

# Convert to PyTorch tensors
X_tensor = torch.from_numpy(X).float()
y_tensor = torch.from_numpy(y).float()

print(f"Features: {X_tensor.shape}, Target: {y_tensor.shape}")
```

### 5. API Backend (FastAPI)

```python
from fastapi import FastAPI
from tv_scraper import TvDatafeed

app = FastAPI()
tv = TvDatafeed()

@app.get("/api/crypto/{symbol}")
def get_crypto_data(symbol: str, interval: str = "1D"):
    return tv.get(
        symbol.upper(),
        interval=interval,
        output_format="json"
    )

# GET http://localhost:8000/api/crypto/BTCUSDT?interval=1H
```

### 6. Context Manager

```python
# Connection auto-closes after use
with TvDatafeed() as tv:
    df = tv.get("BTCUSDT")
    # Connection automatically closed
```

### 7. Stock & Forex Markets

```python
tv = TvDatafeed()

# Indian Stocks (NSE)
df = tv.get("RELIANCE", exchange="NSE", interval="1D")

# US Stocks (NASDAQ)
df = tv.get("AAPL", exchange="NASDAQ", interval="1H")

# Forex
df = tv.get("EURUSD", exchange="FX_IDC", interval="1D")

# Indices
df = tv.get("SPX", exchange="SP", interval="1D")

# Commodities
df = tv.get("XAUUSD", exchange="OANDA", interval="1D")
```

---

## 🕐 Supported Timeframes

| Code | Timeframe | Bars/Day |
|------|-----------|----------|
| `1m` | 1 Minute | 1440 |
| `3m` | 3 Minutes | 480 |
| `5m` | 5 Minutes | 288 |
| `15m` | 15 Minutes | 96 |
| `30m` | 30 Minutes | 48 |
| `1H` | 1 Hour | 24 |
| `2H` | 2 Hours | 12 |
| `3H` | 3 Hours | 8 |
| `4H` | 4 Hours | 6 |
| `1D` | Daily | 1 |
| `1W` | Weekly | ~0.14 |
| `1M` | Monthly | ~0.03 |

---

## 🎯 Output Formats

| Format | Returns | Required | Best For |
|--------|---------|----------|----------|
| `pandas` | DataFrame | `pandas` | Data analysis, plotting |
| `numpy` | Structured ndarray | `numpy` | Scientific computing |
| `arrays` | Tuple of 6 arrays | `numpy` | ML/AI pipelines |
| `dict` | List of dicts | None | APIs, databases |
| `json` | JSON string | None | HTTP responses |
| `csv` | CSV string | None | Excel, spreadsheets |
| `raw` | List of tuples | None | Custom processing |

---

## 📊 Performance Benchmarks

| Format | 1,000 bars | 10,000 bars | 100,000 bars |
|--------|-----------|-------------|-------------|
| raw (tuple) | 0.05s | 0.20s | 1.50s |
| numpy | 0.08s | 0.30s | 2.00s |
| arrays | 0.09s | 0.35s | 2.20s |
| dict | 0.15s | 0.50s | 3.00s |
| pandas | 0.25s | 0.80s | 5.00s |
| json | 0.30s | 1.00s | 6.00s |

*Benchmarks on Python 3.12, i7-13700K*

---

## 🛠️ API Reference

### `TvDatafeed` Class

```python
TvDatafeed(
    auth_token="unauthorized_user_token",  # TradingView auth token
    max_retries=3,                         # Connection retry attempts
    timeout=10                             # WebSocket timeout (seconds)
)
```

### `get()` Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `symbol` | str | Required | Trading pair symbol |
| `exchange` | str | `"BINANCE"` | Exchange identifier |
| `interval` | str | `"1D"` | Timeframe interval |
| `start` | str/datetime | 30 days ago | Start of date range |
| `end` | str/datetime | now | End of date range |
| `output_format` | str | `"pandas"` | Output format |
| `**format_kwargs` | dict | `{}` | Extra formatter options |

### Date Format Examples

```python
# All these work:
tv.get("BTCUSDT", start="2024-01-01")           # YYYY-MM-DD
tv.get("BTCUSDT", start="01-01-2024")           # DD-MM-YYYY
tv.get("BTCUSDT", start="2024-01-01 12:30:00")  # With time
tv.get("BTCUSDT", start=datetime(2024, 1, 1))   # datetime object
tv.get("BTCUSDT", start=1704067200)             # Unix timestamp
```

---

## ❗ Error Handling

```python
from tv_scraper import TvDatafeed
from tv_scraper.exceptions import *

tv = TvDatafeed()

try:
    df = tv.get("INVALID_SYMBOL")
except NoDataError:
    print("No data returned for this symbol")
except ConnectionError:
    print("Could not connect to TradingView")
except FormatError:
    print("Invalid output format specified")
except InvalidSymbolError:
    print("Symbol format is invalid")
```

### Exception Hierarchy

```
TvScraperError (base)
├── ConnectionError    — WebSocket connection failures
├── NoDataError        — No data for symbol/range
├── InvalidSymbolError — Bad symbol format
├── FormatError        — Invalid output format
└── ParseError         — Response parsing failures
```

---

## 🧪 Running Tests

```bash
pip install tv_scraper[dev]
pytest tests/ -v
pytest tests/ --cov=tv_scraper --cov-report=html
```

---

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create feature branch: `git checkout -b feature/amazing-feature`
3. Commit changes: `git commit -m "Add amazing feature"`
4. Push branch: `git push origin feature/amazing-feature`
5. Open a Pull Request

---

## 📝 Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

---

## ⚠️ Disclaimer

This library is for **educational and research purposes only**. 

- Respect TradingView's [Terms of Service](https://www.tradingview.com/policies/)
- Implement appropriate rate limiting in production
- Consider using official APIs for critical applications

---

## 📄 License

MIT License — See [LICENSE](LICENSE) for details.

---

## 🌟 Star History

If you find this useful, please ⭐ star the repository!

---

## 📬 Contact

- **Author:** Anurag Jha
- **Email:** anuragjha507@gmail.com
- **GitHub:** [@anuragjha0001](https://github.com/anuragjha0001)
- **Issues:** [Report Bug](https://github.com/anuragjha0001/tv_scraper/issues)

---

**Made with ❤️ by Anurag Jha**
