Cabina Configuration

1.1.2 · active · verified Fri Apr 17

Cabina is a Python library for managing application configuration, primarily focused on typed environment variables. It builds upon Pydantic's BaseSettings to provide robust validation and type coercion for settings loaded from environment variables. As of version 1.1.2, it offers a streamlined way to define configuration schemas, leveraging Pydantic's powerful features. The release cadence is moderate, with stable updates building on Pydantic's advancements.

Common errors

```
ModuleNotFoundError: No module named 'cabina'
```
cause The Cabina library is not installed in your current Python environment.

fix Run `pip install cabina` to install the library.
```
pydantic.v1.error_wrappers.ValidationError: 1 validation error for AppConfig
app_name
  field required (type=value_error.missing)
```
cause A required configuration field (e.g., `app_name`) was not provided via environment variables, and no default value was set.

fix Set the corresponding environment variable (e.g., `export APP_APP_NAME="Your App"` or `APP_NAME="Your App"` if no `env_prefix` is used) or provide a default value for the field in your `AppConfig` class (e.g., `app_name: str = "Default App"`).
```
pydantic.v1.error_wrappers.ValidationError: 1 validation error for AppConfig
app_port
  value is not a valid integer (type=type_error.integer)
```
cause The environment variable for an integer field (e.g., `APP_PORT`) contains a non-integer value (e.g., 'abc').

fix Ensure the environment variable is set to a string that can be coerced into the expected type (e.g., `export APP_APP_PORT="8000"`).

Warnings

breaking Cabina v1.0.0 rebased the entire library on Pydantic's BaseSettings. If upgrading from pre-1.0.0 versions, custom parsing/validation logic that was previously handled by Cabina directly will likely break, as Pydantic now handles these aspects. Ensure your configuration classes are compatible with Pydantic's BaseModel/BaseSettings features.
Fix: Rewrite configuration classes to fully leverage Pydantic's `BaseSettings` features, including `Field` for `env` mapping and Pydantic's validation mechanisms.
gotcha Cabina (and underlying Pydantic BaseSettings) strictly applies type coercion. An environment variable like `APP_PORT="abc"` for an `app_port: int` field will result in a `ValidationError`. Similarly, for boolean fields, string values like '0', 'f', 'false', 'n', 'no', 'off' are typically coerced to `False`, and '1', 't', 'true', 'y', 'yes', 'on' to `True` (case-insensitive).
Fix: Ensure environment variable values strictly conform to the expected type of the corresponding Pydantic field. Consult Pydantic documentation for specific type coercion rules.
gotcha When defining fields, using `pydantic.Field(default=..., env="ENV_VAR_NAME")` is crucial for clarity and overriding. Without `env="ENV_VAR_NAME"`, Pydantic's `BaseSettings` might prioritize field names derived from `env_prefix` or other sources in an unexpected way, especially if the default value is present.
Fix: Explicitly use `pydantic.Field(..., env="YOUR_ENV_VAR_NAME")` to precisely map environment variables to fields, especially when defaults are provided or when the env var name deviates from the auto-derived name based on `env_prefix` and field name.

Install

pip install cabina Install Cabina

Imports

Cabina
```
from cabina import Cabina
```

Quickstart

Define your configuration schema by inheriting from `cabina.Cabina`. Cabina automatically picks up environment variables that match the field names, optionally using an `env_prefix` defined in the nested `Config` class. Variables can have default values and explicit `env` mapping via `pydantic.Field` for clearer control. Run this code after setting environment variables like `APP_NAME=MyApp` and `APP_PORT=8080` (or let it use the defaults/os.environ values).

import os
from cabina import Cabina
from pydantic import Field

os.environ['APP_NAME'] = os.environ.get('APP_NAME', 'MyDefaultApp')
os.environ['APP_PORT'] = os.environ.get('APP_PORT', '8000')
os.environ['DEBUG_MODE'] = os.environ.get('DEBUG_MODE', 'true')


class AppConfig(Cabina):
    app_name: str
    app_port: int = Field(8000, env="APP_PORT")
    debug_mode: bool = False

    class Config:
        env_prefix = 'APP_'
        case_sensitive = False


config = AppConfig()

print(f"App Name: {config.app_name}")
print(f"App Port: {config.app_port}")
print(f"Debug Mode: {config.debug_mode}")

assert config.app_name == os.environ['APP_NAME']
assert config.app_port == int(os.environ['APP_PORT'])
assert config.debug_mode == (os.environ['DEBUG_MODE'].lower() == 'true')

view raw JSON →