Application Configuration

To manage environment-specific behavior in etchblok-test-api, you use configuration classes that inherit from BaseConfig to define settings like DEBUG mode, PAGE_SIZE, and cache parameters.

Initializing the Application with a Configuration

The etchblok-test-api uses an application factory pattern in app/__init__.py. You pass a configuration class to create_app() to initialize the Flask instance with the desired settings.

from app import create_app
from app.config import ProductionConfig

# Initialize the app for production
app = create_app(config_class=ProductionConfig)

By default, create_app uses DevelopmentConfig if no class is provided, as seen in run.py:

from app import create_app

app = create_app()

if __name__ == "__main__":
    app.run(debug=True, port=5000)

Configuration Environments

The app/config.py module defines four primary classes to handle different deployment scenarios.

Development Configuration

DevelopmentConfig is optimized for local iteration. It enables DEBUG mode, reduces the default PAGE_SIZE to 10, and sets a short-lived cache.

@dataclass
class DevelopmentConfig(BaseConfig):
    """Configuration for local development."""

    DEBUG: bool = True
    PAGE_SIZE: int = 10

    def get_cache_config(self) -> Dict[str, Any]:
        return _build_cache_config(ttl=30, max_size=128)

Production Configuration

ProductionConfig enforces security requirements. Unlike other environments, it does not provide a default for SECRET_KEY and will raise a KeyError if the environment variable is missing.

@dataclass
class ProductionConfig(BaseConfig):
    """Configuration for production deployments."""

    SECRET_KEY: str = field(default_factory=lambda: os.environ["SECRET_KEY"])
    PAGE_SIZE: int = DEFAULT_PAGE_SIZE

    def get_cache_config(self) -> Dict[str, Any]:
        return _build_cache_config(ttl=600, max_size=4096)

To run etchblok-test-api in production, you must export the key:

export SECRET_KEY="your-secure-random-string"
python run.py

Testing Configuration

TestingConfig is used during test suites to ensure predictable behavior and fast execution. It sets TESTING to True and uses a very small PAGE_SIZE (5) to simplify pagination assertions.

@dataclass
class TestingConfig(BaseConfig):
    """Configuration for test runs."""

    TESTING: bool = True
    PAGE_SIZE: int = 5

Cache Settings

Each configuration class implements get_cache_config() to return a dictionary of settings used by the application's caching layer. This is powered by the internal _build_cache_config helper.

Environment	TTL (seconds)	Max Entries	Eviction Strategy
Base / Default	300	1024	LRU
Development	30	128	LRU
Production	600	4096	LRU

Configuration Constraints and Validation

The BaseConfig class includes a _validate() method that enforces internal invariants. While this is not part of the public API, it defines the following limits:

1. Secret Key: SECRET_KEY must be a non-empty string.
2. Page Size: PAGE_SIZE cannot exceed MAX_PAGE_SIZE (100).

# app/config.py constants
DEFAULT_PAGE_SIZE: int = 25
MAX_PAGE_SIZE: int = 100

def _validate(self) -> bool:
    """Check internal invariants. Not part of the public API."""
    return bool(self.SECRET_KEY) and self.PAGE_SIZE <= MAX_PAGE_SIZE

Troubleshooting: Missing Secret Key

If you attempt to start etchblok-test-api using ProductionConfig without setting the SECRET_KEY environment variable, the application will fail to start with a KeyError:

KeyError: 'SECRET_KEY'

Ensure the variable is exported in your shell or defined in your deployment environment (e.g., Docker environment variables or a .env file).