Configuration

Complete guide to configuring numistalib.

Configuration Methods

numistalib can be configured through:

Environment variables (recommended)
.env file
Direct Settings object

§ 1 Environment Variables

Core Settings

NUMISTA_API_KEY

Required. Your Numista API key.

export NUMISTA_API_KEY="your_api_key_here"

Get your key at: https://en.numista.com/api/

NUMISTA_BASE_URL

Base URL for the Numista API.

Default: https://api.numista.com/v3
Type: string

export NUMISTA_BASE_URL="https://api.numista.com/v3"

Cache Settings

CACHE_DIR

Directory for persistent HTTP cache.

Default: .numista_cache
Type: string (path)

export CACHE_DIR="/path/to/cache"

CACHE_TTL_SECONDS

Time-to-live for cached responses.

Default: 604800 (7 days)
Type: integer (seconds)

export CACHE_TTL_SECONDS=86400  # 1 day

Rate Limiting

RATE_LIMIT

Maximum number of requests per time window.

Default: 45
Type: integer

export RATE_LIMIT=30

RATE_LIMIT_WINDOW

Time window for rate limiting.

Default: 60 (seconds)
Type: integer

export RATE_LIMIT_WINDOW=60

Retry Settings

MAX_RETRIES

Maximum number of retry attempts for failed requests.

Default: 3
Type: integer

export MAX_RETRIES=5

RETRY_BACKOFF_FACTOR

Multiplier for exponential backoff.

Default: 2.0
Type: float

export RETRY_BACKOFF_FACTOR=1.5

Logging

LOG_LEVEL

Logging verbosity level.

Default: INFO
Type: string
Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL

export LOG_LEVEL=DEBUG

§ 2 .env File Configuration

Create a .env file in your project root:

# Numista API
NUMISTA_API_KEY=your_api_key_here
NUMISTA_BASE_URL=https://api.numista.com/v3

# Cache
CACHE_DIR=.numista_cache
CACHE_TTL_SECONDS=604800

# Rate Limiting
RATE_LIMIT=45
RATE_LIMIT_WINDOW=60

# Retry
MAX_RETRIES=3
RETRY_BACKOFF_FACTOR=2.0

# Logging
LOG_LEVEL=INFO

The .env file is automatically loaded when using Settings().

§ 3 Programmatic Configuration

Using Settings Object

from numistalib.config import Settings

# Load from environment/.env
settings = Settings()

# Override specific values
settings = Settings(
    numista_api_key="your_key",
    cache_ttl_seconds=86400,  # 1 day
    rate_limit=30
)

# Use with client
from numistalib.client import NumistaApiClient

with NumistaApiClient(settings) as client:
    # Use client
    pass

Custom Cache Directory

from pathlib import Path
from numistalib.config import Settings

cache_path = Path.home() / ".cache" / "numista"
settings = Settings(cache_dir=str(cache_path))

Disable Caching

settings = Settings(cache_ttl_seconds=0)

Note: This will still create the cache directory but responses won’t be stored.

Aggressive Rate Limiting

For API quota conservation:

settings = Settings(
    rate_limit=20,        # 20 requests
    rate_limit_window=60  # per minute
)

Increase Retry Attempts

For unreliable networks:

settings = Settings(
    max_retries=10,
    retry_backoff_factor=3.0
)

§ 4 Configuration Validation

Settings are validated using Pydantic:

from numistalib.config import Settings

try:
    settings = Settings(
        rate_limit=-5  # Invalid!
    )
except ValueError as e:
    print(f"Configuration error: {e}")

§ 5 Viewing Current Configuration

Via CLI

numistalib config list

Shows all current settings including:

API key (masked)
Cache directory
TTL
Rate limits
Retry settings

Programmatically

from numistalib.config import Settings

settings = Settings()

print(f"API Key: {settings.numista_api_key[:8]}...")
print(f"Cache Dir: {settings.cache_dir}")
print(f"Cache TTL: {settings.cache_ttl_seconds}s")
print(f"Rate Limit: {settings.rate_limit}/{settings.rate_limit_window}s")

§ 6 Multi-Environment Setup

Development

.env.development:

NUMISTA_API_KEY=dev_key
CACHE_DIR=.cache_dev
CACHE_TTL_SECONDS=3600
LOG_LEVEL=DEBUG

Production

.env.production:

NUMISTA_API_KEY=prod_key
CACHE_DIR=/var/cache/numista
CACHE_TTL_SECONDS=604800
LOG_LEVEL=WARNING

Load specific environment:

from numistalib.config import Settings
from pathlib import Path

env_file = Path(".env.production")
settings = Settings(_env_file=env_file)

§ 7 Docker Configuration

docker-compose.yml:

version: '3.8'

services:
  numistalib:
    image: python:3.13
    environment:
      - NUMISTA_API_KEY=${NUMISTA_API_KEY}
      - CACHE_DIR=/cache
      - CACHE_TTL_SECONDS=604800
      - RATE_LIMIT=45
    volumes:
      - ./cache:/cache
      - ./app:/app
    working_dir: /app
    command: python your_script.py

§ 8 Best Practices

Security

Never commit .env files to version control
Add .env to .gitignore
Use environment-specific files (.env.local, .env.production)
Rotate API keys periodically

Performance

Use default cache TTL (7 days) for stable data
Reduce cache TTL for frequently changing data
Adjust rate limits based on your API tier
Use async methods for batch operations

Reliability

Keep retry settings moderate (3-5 attempts)
Use exponential backoff factor ≥ 2.0
Monitor rate limit usage
Handle errors gracefully

§ 9 Troubleshooting

“API key not found”

Ensure NUMISTA_API_KEY is set:

echo $NUMISTA_API_KEY

Or check .env file exists and contains the key.

“Permission denied” (cache directory)

Ensure the cache directory is writable:

mkdir -p .numista_cache
chmod 755 .numista_cache

Rate limit errors

Check your rate limit settings:

numistalib config get rate_limit
numistalib config get rate_limit_window

Reduce request frequency or increase limits if your API tier supports it.

Cache not working

Verify cache directory and TTL:

numistalib config get cache_dir
numistalib config get cache_ttl_seconds
ls -la .numista_cache/

§ 10 Configuration Reference

Setting	Type	Default	Description
`numista_api_key`	str	required	Numista API key
`numista_base_url`	str	`https://api.numista.com/v3`	API base URL
`cache_dir`	str	`.numista_cache`	Cache directory path
`cache_ttl_seconds`	int	`604800`	Cache TTL (7 days)
`rate_limit`	int	`45`	Requests per window
`rate_limit_window`	int	`60`	Rate limit window (seconds)
`max_retries`	int	`3`	Maximum retry attempts
`retry_backoff_factor`	float	`2.0`	Exponential backoff multiplier
`log_level`	str	`INFO`	Logging level

Next Steps

Advanced Usage - Complex configuration scenarios
Architecture - Understanding how configuration works
CLI Guide - Using configuration with CLI