Skip to main content

Introduction to Application Configuration

etchblok-test-api uses a class-based configuration system to manage environment-specific settings like security keys, pagination limits, and cache behavior. By leveraging Python dataclasses and inheritance, the project ensures that shared defaults are maintained in a single location while allowing strict overrides for production and testing environments.

Environment-Based Configuration​

The configuration is structured around a hierarchy of classes in app/config.py. This approach allows you to switch between local development, automated testing, and production deployments by passing the appropriate class to the application factory.

The Base Configuration​

The BaseConfig class serves as the source of truth for all shared settings. It defines the default behavior for the application, including pagination and security defaults.

@dataclass
class BaseConfig:
"""Base configuration shared across all environments."""

SECRET_KEY: str = field(default_factory=lambda: os.environ.get("SECRET_KEY", "change-me"))
DEBUG: bool = False
TESTING: bool = False
PAGE_SIZE: int = DEFAULT_PAGE_SIZE

def get_cache_config(self) -> Dict[str, Any]:
"""Return cache settings for this environment."""
return _build_cache_config()

Key constants used by BaseConfig include:

  • DEFAULT_PAGE_SIZE: Set to 25.
  • MAX_PAGE_SIZE: Set to 100, used for internal validation.
  • API_VERSION: Set to "v1".

Environment Overrides​

etchblok-test-api provides three specialized subclasses of BaseConfig:

  1. DevelopmentConfig: Enables DEBUG mode and reduces the PAGE_SIZE to 10 for easier manual testing of pagination. It also configures a smaller, short-lived cache (30s TTL, 128 entries).
  2. TestingConfig: Sets TESTING to True and uses a minimal PAGE_SIZE of 5 to isolate test cases.
  3. ProductionConfig: Enforces strict security. Unlike other environments, it will raise a KeyError if the SECRET_KEY environment variable is missing, as it does not provide a default value. It also scales the cache to 4096 entries with a 600s TTL.
@dataclass
class ProductionConfig(BaseConfig):
"""Configuration for production deployments."""

# Enforces that SECRET_KEY must be in the environment
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)

Loading Configuration​

The configuration is applied during application startup in the create_app factory function located in app/__init__.py. Flask's app.config.from_object() method reads the attributes of the provided class and populates the app.config dictionary.

To initialize the app with a specific configuration, pass the class to the factory:

from app import create_app
from app.config import ProductionConfig

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

By default, create_app uses DevelopmentConfig if no argument is provided.

Internal Validation​

The BaseConfig class includes a _validate() method designed to check internal invariants, such as ensuring the SECRET_KEY is present and the PAGE_SIZE does not exceed the MAX_PAGE_SIZE limit:

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

Note that this method is marked as internal and is not automatically invoked by the Flask framework during startup.

Implementation Gotchas​

While the configuration system provides a centralized way to manage settings, some components in etchblok-test-api currently bypass these settings:

  • Hardcoded Cache Size: Although BaseConfig and its subclasses provide a get_cache_config() method, the BookmarkService in app/services/bookmark_service.py currently hardcodes its LRUCache size to 256 entries during initialization:
    # app/services/bookmark_service.py
    def _init_services(self) -> None:
    self._repo = BookmarkRepository()
    self._cache: LRUCache[Bookmark] = LRUCache(max_size=256) # Hardcoded
    self._search = SearchIndex(self._repo)
  • Production Secret Key: If you attempt to start the application using ProductionConfig without setting the SECRET_KEY environment variable, the application will fail to start with a KeyError. Always ensure your environment is configured before deployment.