fba-finance 0.1.2

Multi-source financial data library with anti-rate-limiting strategies

FBA Finance 📈

Libreria Python multi-source per acquisizione dati finanziari con strategie anti-rate-limiting

FBA Finance è una libreria completa che aggrega multiple fonti di dati finanziari gratuite con fallback automatico, caching intelligente e rate limiting distribuito, permettendoti di superare i limiti di utilizzo delle singole API.

🎯 Caratteristiche Principali

• ✅ Multi-Provider con Fallback Automatico: Se una fonte fallisce o è rate-limited, passa automaticamente alla successiva
• ✅ Dati Real-Time e Storici: Quote in tempo quasi reale e dati storici OHLCV
• ✅ Tutti i Mercati Mondiali: Azioni, ETF, Indici, Forex, Crypto, Futures
• ✅ Anti-Rate-Limiting: Rate limiter intelligente per ogni provider
• ✅ Caching Multi-Backend: Memory, Disk (DiskCache), Redis
• ✅ Web Scraping Resiliente: Rotating user agents, proxy support
• ✅ 100% Gratuito e Open Source: Nessun costo, tutte fonti free tier

🔌 Provider Supportati

Provider	Quote Real-Time	Dati Storici	Rate Limit (Free)	API Key Richiesta
yfinance	✅	✅	~60 req/min	❌ No
yahooquery	✅	✅	~60 req/min	❌ No
Yahoo Scraper	✅	⚠️ Limitato	~30 req/min	❌ No
Twelve Data	✅	✅	800 req/giorno	✅ Sì (gratis)
Alpha Vantage	✅	✅	500 req/giorno	✅ Sì (gratis)

Capacità teorica combinata: Migliaia di richieste al giorno senza pagare!

📦 Installazione

Installazione da PyPI (Consigliata)

# Installazione base (Yahoo Finance + fallback)
pip install fba-finance

# Installazione completa (tutti i provider)
pip install fba-finance[full]

Installazione da Sorgente (per sviluppatori)

# Clona il repository
git clone https://github.com/faux62/fba_finance.git
cd fba_finance

# Installazione base
pip install -e .

# Installazione completa
pip install -e ".[full]"

🚀 Quick Start

Esempio Base - Quote in Real-Time

from fba_finance import FinanceClient

# Inizializza il client
client = FinanceClient()

# Ottieni una quote
quote = client.get_quote("AAPL")
print(f"{quote.symbol}: ${quote.price}")
print(f"Change: {quote.change_percent:.2f}%")

# Ottieni multiple quote (batch)
quotes = client.get_quotes(["AAPL", "MSFT", "GOOGL", "TSLA"])
for symbol, quote in quotes.items():
    print(f"{symbol}: ${quote.price}")

Dati Storici

from fba_finance import FinanceClient
from datetime import datetime, timedelta

client = FinanceClient()

# Ottieni 1 anno di dati giornalieri
data = client.get_historical("AAPL", period="1y", interval="1d")
print(data.data.head())

# Ottieni dati per un periodo specifico
end = datetime.now()
start = end - timedelta(days=30)
data = client.get_historical("AAPL", start=start, end=end, interval="1h")

# Il DataFrame ha le colonne: date, open, high, low, close, volume
df = data.data
print(df[['date', 'close', 'volume']])

Ticker Internazionali

# Mercati globali
stocks = [
    "AAPL",           # USA - NASDAQ
    "TSLA",           # USA - NASDAQ  
    "0700.HK",        # Hong Kong - Tencent
    "BMW.DE",         # Germania - BMW
    "MC.PA",          # Francia - LVMH
    "FTSEMIB.MI",     # Italia - FTSE MIB Index
    "UCG.MI",         # Italia - UniCredit
    "ENI.MI",         # Italia - ENI
]

quotes = client.get_quotes(stocks)
for symbol, quote in quotes.items():
    print(f"{symbol}: {quote.currency} {quote.price}")

Forex e Crypto

# Forex pairs
forex = client.get_quote("EURUSD=X")
print(f"EUR/USD: {forex.price}")

# Cryptocurrencies
btc = client.get_quote("BTC-USD")
eth = client.get_quote("ETH-USD")
print(f"Bitcoin: ${btc.price}")
print(f"Ethereum: ${eth.price}")

🔧 Configurazione Avanzata

Setup API Keys (Opzionale ma Raccomandato)

Crea un file .env nella root del progetto:

# Copia il template
cp .env.example .env

Modifica .env con le tue API keys (tutte gratuite!):

# Alpha Vantage - https://www.alphavantage.co/support/#api-key
ALPHA_VANTAGE_API_KEY=your_key_here

# Twelve Data - https://twelvedata.com/
TWELVE_DATA_API_KEY=your_key_here

# Cache settings
CACHE_ENABLED=true
CACHE_BACKEND=disk  # Options: disk, redis, memory
CACHE_TTL_REALTIME=60
CACHE_TTL_HISTORICAL=3600

Personalizza Provider Priority

from fba_finance import FinanceClient

# Definisci l'ordine di fallback
custom_priority = [
    "twelvedata",      # Prova prima Twelve Data
    "yahooquery",      # Poi yahooquery
    "yfinance",        # Poi yfinance standard
    "yahoo_scraper",   # Infine scraper
]

client = FinanceClient(provider_priority=custom_priority)
quote = client.get_quote("AAPL")

Forza Provider Specifico

# Usa solo un provider specifico
quote = client.get_quote("AAPL", provider="twelvedata")
data = client.get_historical("AAPL", period="1mo", provider="yfinance")

Gestione Cache

# Disabilita cache
client = FinanceClient(use_cache=False)

# Cancella cache
client.clear_cache()

# Usa Redis invece di disk cache
# Nel file .env:
# CACHE_BACKEND=redis
# REDIS_HOST=localhost
# REDIS_PORT=6379

📊 Esempi Avanzati

Esempio 1: Portfolio Tracker

from fba_finance import FinanceClient

client = FinanceClient()

portfolio = {
    "AAPL": 10,   # 10 shares
    "MSFT": 5,
    "GOOGL": 3,
    "TSLA": 2,
}

quotes = client.get_quotes(list(portfolio.keys()))

total_value = 0
for symbol, shares in portfolio.items():
    if symbol in quotes:
        price = quotes[symbol].price
        value = price * shares
        total_value += value
        print(f"{symbol}: {shares} shares @ ${price} = ${value:.2f}")

print(f"\nTotal Portfolio Value: ${total_value:.2f}")

Esempio 2: Download Massivo Dati Storici

from fba_finance import FinanceClient
from datetime import datetime, timedelta
import pandas as pd

client = FinanceClient()

# Lista di 100+ ticker
tickers = ["AAPL", "MSFT", "GOOGL", "TSLA", "AMZN", ...]  # aggiungi più ticker

all_data = {}

for ticker in tickers:
    print(f"Downloading {ticker}...")
    data = client.get_historical(ticker, period="1y", interval="1d")
    
    if data:
        all_data[ticker] = data.data
        print(f"✓ {ticker}: {len(data.data)} rows")
    else:
        print(f"✗ {ticker}: failed")

# Combina tutti in un singolo DataFrame
combined = pd.concat(all_data, names=['ticker', 'idx'])
combined.to_csv("all_stocks_1y.csv")

Esempio 3: Real-Time Monitoring

import time
from fba_finance import FinanceClient

client = FinanceClient(use_cache=False)  # No cache for real-time

watchlist = ["AAPL", "TSLA", "BTC-USD"]

while True:
    quotes = client.get_quotes(watchlist)
    
    print("\n" + "="*50)
    print(f"Update: {datetime.now().strftime('%H:%M:%S')}")
    print("="*50)
    
    for symbol, quote in quotes.items():
        change_symbol = "🔴" if quote.change < 0 else "🟢"
        print(f"{change_symbol} {symbol}: ${quote.price:.2f} ({quote.change_percent:+.2f}%)")
    
    time.sleep(10)  # Aggiorna ogni 10 secondi

Esempio 4: Analisi Tecnica

import pandas as pd
from fba_finance import FinanceClient

client = FinanceClient()

# Ottieni dati storici
data = client.get_historical("AAPL", period="3mo", interval="1d")
df = data.data

# Calcola medie mobili
df['SMA_20'] = df['close'].rolling(window=20).mean()
df['SMA_50'] = df['close'].rolling(window=50).mean()

# RSI (Relative Strength Index)
delta = df['close'].diff()
gain = (delta.where(delta > 0, 0)).rolling(window=14).mean()
loss = (-delta.where(delta < 0, 0)).rolling(window=14).mean()
rs = gain / loss
df['RSI'] = 100 - (100 / (1 + rs))

# Volatilità
df['volatility'] = df['close'].pct_change().rolling(window=20).std()

print(df[['date', 'close', 'SMA_20', 'SMA_50', 'RSI', 'volatility']].tail())

🛠️ Strategie Anti-Rate-Limiting

La libreria implementa diverse strategie per massimizzare il throughput:

1. Fallback Multi-Provider

Se un provider è rate-limited, prova automaticamente il prossimo nella catena.

2. Rate Limiter Intelligente

Tiene traccia delle richieste per secondo/minuto/giorno per ogni provider.

# Configurabile in .env
MAX_REQUESTS_PER_SECOND=2
MAX_REQUESTS_PER_MINUTE=50

3. Caching Aggressivo

Cachea le risposte per ridurre richieste duplicate.

# TTL configurabile per tipo di dato
CACHE_TTL_REALTIME=60      # 1 minuto per quote
CACHE_TTL_HISTORICAL=3600  # 1 ora per dati storici

4. Batch Requests

Usa batch API quando disponibili (yahooquery, twelvedata).

5. Web Scraping di Fallback

Se le API falliscono, usa web scraping con:

• Rotating User Agents
• Request throttling
• Error handling robusto

📈 Performance Tips

Massimizza Throughput

# 1. Usa batch requests quando possibile
quotes = client.get_quotes(["AAPL", "MSFT", "GOOGL"])  # 1 request
# invece di
quote1 = client.get_quote("AAPL")  # 3 requests
quote2 = client.get_quote("MSFT")
quote3 = client.get_quote("GOOGL")

# 2. Abilita cache per dati ripetuti
client = FinanceClient(use_cache=True)

# 3. Usa provider con limiti più alti per batch
client = FinanceClient(provider_priority=["twelvedata", "yahooquery"])

# 4. Per download massivi, distribuisci su più provider
providers = ["yfinance", "twelvedata", "alphavantage"]
for i, ticker in enumerate(large_ticker_list):
    provider = providers[i % len(providers)]
    data = client.get_historical(ticker, period="1y", provider=provider)

🐛 Debugging

# Verifica provider disponibili
statuses = client.get_provider_status()
for status in statuses:
    symbol = "✓" if status.available else "✗"
    print(f"{symbol} {status.name}")
    if not status.available:
        print(f"  Error: {status.last_error}")

# Verifica quali provider hanno funzionato
client.get_available_providers()
# Output: ['yfinance', 'yahooquery', 'yahoo_scraper']

🤝 Contribuire

Contributi sono benvenuti! Per aggiungere nuovi provider:

1. Crea una nuova classe in fba_finance/providers/
2. Eredita da BaseProvider
3. Implementa get_quote(), get_historical(), get_multiple_quotes()
4. Aggiungi al ProviderAggregator

📝 Limiti Noti

• Dati Intraday: Alcuni provider free hanno limiti sui dati intraday (< 1d interval)
• Dati Storici: Twelvedata free tier limita a 8 anni di storia
• Mercati Esotici: Alcuni mercati minori potrebbero non essere disponibili su tutti i provider

⚖️ Disclaimer

Questa libreria è per scopi educativi e di ricerca. Rispetta sempre i termini di servizio dei provider:

• Yahoo Finance: Solo uso personale, non commerciale
• API Provider: Rispetta i rate limits dei tier gratuiti
• Web Scraping: Usa responsabilmente

NON usare per trading automatico ad alta frequenza.

📜 License

MIT License - Vedi LICENSE file

🙏 Crediti

Questa libreria si basa su:

• yfinance
• yahooquery
• Alpha Vantage
• Twelve Data

---

Made with ❤️ for the financial data community

Per domande o supporto, apri una issue su GitHub!