candlecraft 0.1.2

A clean, reusable Python library for fetching OHLCV data from multiple providers

Data Puller All-in-One

A production-ready system for pulling OHLCV data from Cryptocurrency, Forex, and U.S. Equities markets.

Repository: https://github.com/alfredalpino/Data-Puller-AiO
License: MIT License - See LICENSE for details

Candlecraft Library

candlecraft is a Python library for fetching OHLCV data from multiple providers. Published on PyPI.

Installation

pip install candlecraft

Quick Start

from candlecraft import fetch_ohlcv, OHLCV, AssetClass

# Fetch OHLCV data (auto-detects asset class)
data = fetch_ohlcv(
    symbol="BTCUSDT",
    timeframe="1h",
    limit=100
)

# Access OHLCV data
for candle in data:
    print(f"{candle.timestamp}: {candle.close}")

# Explicit asset class
data = fetch_ohlcv(
    symbol="EUR/USD",
    timeframe="1h",
    asset_class=AssetClass.FOREX,
    limit=50
)

API Reference

• fetch_ohlcv() - Fetch OHLCV data from appropriate provider
• list_indicators() - List available technical indicators
• OHLCV - Data model for OHLCV candles
• AssetClass - Enum for asset class types (CRYPTO, FOREX, EQUITY)

Configuration

Set environment variables for API authentication:

# Binance API (Optional - for higher rate limits)
export BINANCE_API_KEY=your_key_here
export BINANCE_API_SECRET=your_secret_here

# Twelve Data API (Required for Forex and US Equities)
export TWELVEDATA_SECRET=your_key_here

API Keys:

• Binance: API Management (optional, works without keys for public data)
• Twelve Data: Sign up (required for Forex/Equities)

Rate Limits & Provider Behavior

Candlecraft does not enforce rate limits by default. Market data providers apply their own rate limits based on your subscription plan, and these limits vary significantly between free tiers and paid plans.

When rate limits are exceeded, providers may return HTTP status codes (such as 429) along with retry-after information indicating when you can make your next request. By default, Candlecraft will raise a RateLimitException when a rate limit is encountered, allowing you to implement your own retry logic, backoff strategies, or error handling as appropriate for your application.

Candlecraft provides an optional opt-in mechanism for automatic waiting. If you explicitly enable rate_limit_strategy="sleep", the library will wait for the provider-specified retry duration before retrying the request. This is useful for simple scripts or applications where automatic waiting is acceptable.

Example with default behavior (fail fast):

from candlecraft import fetch_ohlcv, RateLimitException

try:
    data = fetch_ohlcv(symbol="AAPL", timeframe="1h", limit=100)
except RateLimitException as e:
    print(f"Rate limit hit for {e.provider}")
    print(f"Retry after {e.retry_after} seconds")
    # Implement your own retry logic here

Example with opt-in automatic waiting:

from candlecraft import fetch_ohlcv

# Automatically wait and retry on rate limits
data = fetch_ohlcv(
    symbol="AAPL",
    timeframe="1h",
    limit=100,
    rate_limit_strategy="sleep"
)

Users are responsible for implementing rate limiting, retries, or backoff logic in their own applications based on their specific needs and subscription plans.

Supported Asset Classes

Asset Class	Provider	Example Symbols
Cryptocurrency	Binance	BTCUSDT, ETHUSDT, BNBUSDT
Forex	Twelve Data	EUR/USD, GBP/USD, USD/JPY
U.S. Equities	Twelve Data	AAPL, MSFT, TSLA, GOOGL

Supported Timeframes

1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w, 1M

---

CLI Interface (Optional)

pull_ohlcv.py is a command-line interface for the same functionality. Use this repository for CLI access or development.

Installation (CLI)

git clone https://github.com/alfredalpino/Data-Puller-AiO.git
cd Data-Puller-AiO
python -m venv dpa
source dpa/bin/activate  # On Windows: dpa\Scripts\activate
pip install -r requirements.txt

Quick Start (CLI)

# Cryptocurrency
python pull_ohlcv.py --symbol BTCUSDT --timeframe 1h --limit 100

# Forex
python pull_ohlcv.py --symbol EUR/USD --timeframe 1h --limit 100

# U.S. Equities
python pull_ohlcv.py --symbol AAPL --timeframe 1h --limit 100

# Real-time streaming
python pull_ohlcv.py --symbol BTCUSDT --timeframe 1h --stream

# Polling mode (Forex/Equities)
python pull_ohlcv.py --symbol EUR/USD --timeframe 1m --limit 1 --poll

Historical Data

# Fetch last N candles
python pull_ohlcv.py --symbol BTCUSDT --timeframe 1h --limit 100

# Fetch by date range
python pull_ohlcv.py --symbol AAPL --timeframe 1d --start 2024-01-01 --end 2024-01-31

# Output formats
python pull_ohlcv.py --symbol BTCUSDT --timeframe 1h --limit 10 --format csv
python pull_ohlcv.py --symbol BTCUSDT --timeframe 1h --limit 10 --format json

Real-time Streaming

# Stream only
python pull_ohlcv.py --symbol BTCUSDT --timeframe 1h --stream

# Fetch historical, then stream
python pull_ohlcv.py --symbol BTCUSDT --timeframe 1h --limit 100 --stream

Polling Mode (Forex/Equities)

# Poll for latest candle every 60 seconds
python pull_ohlcv.py --symbol EUR/USD --timeframe 1m --limit 1 --poll

Command Reference

Required Arguments:

• --symbol: Trading pair or stock symbol
• --timeframe: Time interval (required for historical data)

Optional Arguments:

• --limit N: Fetch last N candles
• --start YYYY-MM-DD: Start date (requires --end)
• --end YYYY-MM-DD: End date (requires --start)
• --format {table,csv,json}: Output format (default: table)
• --stream: Enable WebSocket streaming
• --poll: Enable polling mode (60s intervals, Forex/Equities only)
• --timezone TZ: Timezone (e.g., UTC, America/New_York)
• --indicator NAME: Calculate technical indicator (e.g., macd)

Output Formats

• Table (default): Formatted table output
• CSV: Comma-separated values
• JSON: JSON array of OHLCV objects

Rate Limiting (CLI)

The CLI interface (pull_ohlcv.py) includes built-in rate limiting for convenience. This behavior is separate from the library's default behavior.

• Binance: Public access unlimited; with API keys: 1200 requests/minute
• Twelve Data (Free Tier): 1 REST API request per minute (automatically handled in CLI)
• Polling Mode: Automatically respects rate limits with 60-second intervals

Troubleshooting

1. "TWELVEDATA_SECRET environment variable not set"

export TWELVEDATA_SECRET=your_key_here
# Or add to .env file

2. "ModuleNotFoundError"

source dpa/bin/activate
pip install -r requirements.txt

3. "Subscription failed" (WebSocket)

• Free tier may not support WebSocket for all symbols
• Use polling mode instead: --poll
• Check your Twelve Data plan tier

Legacy Scripts

The following scripts are legacy/development-only and should not be used in production:

• pull_fx.py - Use pull_ohlcv.py instead
• pull_us-eq.py - Use pull_ohlcv.py instead
• my_ohlcv.py - Use pull_ohlcv.py instead

All functionality is available in pull_ohlcv.py.

License

MIT License - See LICENSE for details.