sc-entsoe 0.1.0

Modern, high-performance Python library for ENTSOE Transparency Platform data

sc-entsoe

Modern, high-performance Python library for the ENTSOE Transparency Platform.

✨ Features

• 🚀 High Performance: Based on Polars for fast data processing
• 🔒 Secure: Multi-source credential management with automatic redaction
• 🔄 Reliable: Built-in retry logic, rate limiting, and circuit breaker
• ⚡ Modern: Async-first with sync wrapper, full type hints
• 📊 Complete: All ENTSOE data types (prices, generation, load, transmission, balancing)

📦 Installation

pip install sc-entsoe

# Recommended: Install with keyring support for security
pip install sc-entsoe[keyring]

⚙️ Configuration

1. API Key

You need a security token from transparency.entsoe.eu.

Best Practice: Set it as an environment variable (or in a .env file):

export ENTSOE_API_KEY="your-security-token-here"

The library automatically loads this key. You can also pass it explicitly (EntsoeClient(api_key="...")) or use the OS keyring.

2. Custom Settings

Configure retries, timeouts, and rate limits globally:

from sc_entsoe import EntsoeConfig, EntsoeClient

config = EntsoeConfig(
    api_timeout=30,
    retry_attempts=3,
    rate_limit_requests=10,
    safe_logging=True
)

client = EntsoeClient(config=config)

Configuration Reference

Parameter	Environment Variable	Default	Description
api_key	ENTSOE_API_KEY	None	ENTSOE API security token
api_base_url	ENTSOE_API_BASE_URL	https://web-api.tp.entsoe.eu/api	API endpoint URL
api_timeout	ENTSOE_API_TIMEOUT	30	Request timeout (seconds)
rate_limit_requests	ENTSOE_RATE_LIMIT_REQUESTS	10	Max requests per second
rate_limit_burst	ENTSOE_RATE_LIMIT_BURST	20	Burst capacity
retry_attempts	ENTSOE_RETRY_ATTEMPTS	3	Number of retry attempts
retry_max_wait	ENTSOE_RETRY_MAX_WAIT	10	Max wait between retries (seconds)
circuit_breaker_threshold	ENTSOE_CIRCUIT_BREAKER_THRESHOLD	5	Failures before circuit opens
circuit_breaker_timeout	ENTSOE_CIRCUIT_BREAKER_TIMEOUT	60	Circuit cool-down (seconds)
cache_enabled	ENTSOE_CACHE_ENABLED	false	Enable response caching
cache_ttl	ENTSOE_CACHE_TTL	3600	Cache TTL (seconds)
cache_max_size	ENTSOE_CACHE_MAX_SIZE	1000	Max cache entries
debug_logging	ENTSOE_DEBUG_LOGGING	false	Enable debug logs
safe_logging	ENTSOE_SAFE_LOGGING	true	Redact API keys in logs
fill_missing	ENTSOE_FILL_MISSING	true	Fill missing intervals
strict_schema	ENTSOE_STRICT_SCHEMA	false	Strict schema validation

🚀 Quick Start

Synchronous

from sc_entsoe import EntsoeClient

with EntsoeClient() as client:
    # Get day-ahead prices for Germany
    result = client.get_day_ahead_prices("DE", "2024-01-01", "2024-01-02")
    
    print(result.df)  # Polars DataFrame

Async

import asyncio
from sc_entsoe import AsyncEntsoeClient

async def main():
    async with AsyncEntsoeClient() as client:
        # Get solar generation for France
        result = await client.get_generation_actual(
            area="FR", start="2024-01-01", end="2024-01-02", psr_type="B16"
        )
        print(result.df)

asyncio.run(main())

📚 Core Methods

The library achieves 100% parity with the ENTSOE API. Major categories:

• Prices: get_day_ahead_prices, get_imbalance_prices
• Generation: get_generation_actual, get_generation_forecast, get_wind_solar_forecast, get_installed_capacity
• Load: get_load_actual, get_load_forecast
• Transmission: get_crossborder_flows, get_scheduled_exchanges, get_transmission_capacity
• Balancing: get_procured_balancing_capacity, get_imbalance_volumes, get_activated_balancing_energy

🛠 Development

git clone https://github.com/skyeenergy/sc-entsoe.git
cd sc-entsoe
uv sync --dev      # Install dependencies
uv run pytest      # Run tests

📄 License

MIT License. Built at Skye - The energy autopilot for industries.