Configuration

class pybdl.config.BDLConfig(api_key: str | None = <object object>, language: ~pybdl.config.Language = Language.EN, format: ~pybdl.config.Format = Format.JSON, use_cache: bool = True, cache_expire_after: int = 3600, proxy_url: str | None = None, proxy_username: str | None = None, proxy_password: str | None = None, custom_quotas: dict | None = None, quota_cache_enabled: bool = True, quota_cache_file: str | None = None, use_global_cache: bool = False, page_size: int = 100)

Bases: object

Configuration for the BDL API client.

This dataclass manages all configuration options for the BDL API client, supporting direct parameter passing, environment variable overrides, and sensible defaults.

api_key

API key for authentication (optional, None for anonymous access).

Type:

str | None

language

Language code for API responses (default: “en”).

Type:

pybdl.config.Language

format

Response format (default: “json”).

Type:

pybdl.config.Format

use_cache

Whether to use request caching (default: True).

Type:

bool

cache_expire_after

Cache expiration time in seconds (default: 3600).

Type:

int

proxy_url

Optional URL of the proxy server.

Type:

str | None

proxy_username

Optional username for proxy authentication.

Type:

str | None

proxy_password

Optional password for proxy authentication.

Type:

str | None

custom_quotas

Optional custom quota dictionary (period: int).

Type:

dict | None

quota_cache_enabled

Enable persistent quota cache (default: True).

Type:

bool

quota_cache_file

Path to quota cache file (default: project .cache/pybdl).

Type:

str | None

use_global_cache

Store quota cache in OS-specific location (default: False).

Type:

bool

page_size

Default page size for paginated requests (default: 100).

Type:

int

api_key: str | None = <object object>

cache_expire_after: int = 3600

custom_quotas: dict | None = None

format: Format = 'json'

language: Language = 'en'

page_size: int = 100

proxy_password: str | None = None

proxy_url: str | None = None

proxy_username: str | None = None

quota_cache_enabled: bool = True

quota_cache_file: str | None = None

use_cache: bool = True

use_global_cache: bool = False

class pybdl.config.Format(*values)

Bases: Enum

JSON = 'json'

JSONAPI = 'jsonapi'

XML = 'xml'

class pybdl.config.Language(*values)

Bases: Enum

EN = 'en'

PL = 'pl'

The pybdl.config.BDLConfig class manages all configuration for authentication, language, caching, proxy settings, and quota/rate limiting.

Common Configuration Scenarios

Basic Setup

from pybdl import BDL, BDLConfig

# Minimal configuration (reads API key from environment)
bdl = BDL()

# Or provide API key directly
config = BDLConfig(api_key="your-api-key")
bdl = BDL(config)

Anonymous Access

The API supports anonymous access without an API key. When api_key is explicitly set to None, the client operates in anonymous mode with lower rate limits:

from pybdl import BDL, BDLConfig

# Anonymous access (explicitly None - overrides environment variables)
config = BDLConfig(api_key=None)
bdl = BDL(config)

# Or simply pass None
bdl = BDL(config=None)  # Creates default config with api_key=None

# Or use dict
bdl = BDL(config={"api_key": None})

Important: Explicitly passing api_key=None is stronger than environment variables. If you want to use the environment variable BDL_API_KEY, simply don’t provide the api_key parameter (or use BDLConfig()).

Note: Anonymous users have lower rate limits than registered users. See Rate Limiting for details on quota differences.

Development Setup

# Enable caching for faster development
config = BDLConfig(
    api_key="your-api-key",
    use_cache=True,
    cache_expire_after=3600  # 1 hour
)
bdl = BDL(config)

Production Setup

# Production configuration with rate limiting
config = BDLConfig(
    api_key="your-api-key",
    use_cache=False,  # Disable cache for real-time data
    language="en",
    quota_cache_enabled=True  # Enable quota tracking
)
bdl = BDL(config)

Corporate Network Setup

# Behind corporate proxy
config = BDLConfig(
    api_key="your-api-key",
    proxy_url="http://proxy.company.com:8080",
    proxy_username="username",  # Or use environment variables
    proxy_password="password"
)
bdl = BDL(config)

Environment Variables

All configuration options can be set via environment variables:

export BDL_API_KEY="your-api-key"
export BDL_LANGUAGE="en"
export BDL_USE_CACHE="true"
export BDL_CACHE_EXPIRE_AFTER="3600"
export BDL_PROXY_URL="http://proxy.example.com:8080"
export BDL_PROXY_USERNAME="user"
export BDL_PROXY_PASSWORD="pass"
export BDL_QUOTAS='{"1": 20, "900": 500}'

Then use defaults in code:

# Reads from environment variables
bdl = BDL()

See also

• Main Client for main client usage

• Access Layer for access layer usage

• API Clients for API endpoint usage

• Rate Limiting for comprehensive rate limiting documentation

Caching

pyBDL supports transparent request caching to speed up repeated queries and reduce API usage. Caching can be enabled or disabled via the use_cache option in BDLConfig.

Basic Usage

# Enable caching with 10-minute expiry
config = BDLConfig(api_key="...", use_cache=True, cache_expire_after=600)
bdl = BDL(config)

# First call hits the API
data1 = bdl.data.get_data_by_variable("3643", years=[2021])

# Second call uses cache (if within expiry time)
data2 = bdl.data.get_data_by_variable("3643", years=[2021])

Configuration Options

• use_cache: Enable/disable caching (default: False)

• cache_expire_after: Cache expiry time in seconds (default: 3600 = 1 hour)

When to Use Caching

• Development and testing: Speed up repeated queries

• Data exploration: Avoid re-fetching the same data

• Batch processing: Cache metadata queries

When Not to Use Caching

• Real-time data: When you need the latest data

• One-off scripts: No benefit if queries aren’t repeated

• Memory-constrained environments: Cache uses disk space

For technical details about cache file management and locations, see Appendix: Technical Implementation Details.

Proxy Configuration

The library supports HTTP/HTTPS proxy configuration for environments behind corporate firewalls or proxies.

Basic Configuration

# Direct configuration
config = BDLConfig(
    api_key="your-api-key",
    proxy_url="http://proxy.example.com:8080",
    proxy_username="user",  # Optional
    proxy_password="pass"   # Optional
)
bdl = BDL(config)

Using Environment Variables

For security, prefer environment variables over hardcoded credentials:

export BDL_PROXY_URL="http://proxy.example.com:8080"
export BDL_PROXY_USERNAME="user"
export BDL_PROXY_PASSWORD="pass"

Then use in Python:

# Configuration is read from environment variables
config = BDLConfig(api_key="your-api-key")
bdl = BDL(config)

Configuration Precedence

Settings are applied in this order: 1. Direct parameter passing (highest priority) 2. Environment variables 3. Default values (None)

Common Use Cases

• Corporate networks requiring proxy access

• VPN connections

• Development environments behind firewalls

For technical details about proxy implementation, see Appendix: Technical Implementation Details.

Rate Limiting & Quotas

pyBDL enforces API rate limits using both synchronous and asynchronous rate limiters. These limits are based on the official BDL API provider’s policy, as described in the BDL API Manual (see the “Manual” tab).

Quick Overview

• Automatic enforcement: Rate limiting is built into all API calls

• Multiple quota periods: Enforces limits across different time windows simultaneously

• Persistent cache: Quota usage survives process restarts

• Sync & async support: Works seamlessly with both synchronous and asynchronous code

Default Quotas

The following user limits apply. Quotas are automatically selected based on whether api_key is provided:

Period	Anonymous user	Registered user
1s	5	10
15m	100	500
12h	1,000	5,000
7d	10,000	50,000

• Anonymous user: api_key=None or not provided (no X-ClientId header sent)

• Registered user: api_key is provided (X-ClientId header sent with API key)

The rate limiter automatically selects the appropriate quota limits based on registration status.

Custom Quotas

To override default rate limits, provide a custom_quotas dictionary with integer keys representing the period in seconds:

config = BDLConfig(api_key="...", custom_quotas={1: 10, 900: 200, 43200: 2000, 604800: 20000})

Or via environment variable:

export BDL_QUOTAS='{"1": 20, "900": 500}'

Comprehensive Documentation

For detailed information on rate limiting, including: - How to handle rate limit errors - Configuring wait vs. raise behavior - Using context managers and decorators - Checking remaining quota - Technical implementation details

See Rate Limiting for the complete guide.