Install & Compatibility
Where this runs
tested against v1.1.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Config
✓ from cabina import Config
✗ from cabina import Cabina
Environment
✓ from cabina import Environment
env
✓ from cabina import env
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')
Debug
Known issues
breakingCabina 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.fixRewrite configuration classes to fully leverage Pydantic's `BaseSettings` features, including `Field` for `env` mapping and Pydantic's validation mechanisms.
affects: <1.0.0 to >=1.0.0
gotchaCabina (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).fixEnsure environment variable values strictly conform to the expected type of the corresponding Pydantic field. Consult Pydantic documentation for specific type coercion rules.
affects: >=1.0.0
gotchaWhen 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.fixExplicitly 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.
affects: >=1.0.0
Upgrade
Version history
1.1.2latest on PyPI · released Jan 7, 2025
Audit
Dependencies
No dependency data recorded yet.