{"id":9567,"library":"cabina","title":"Cabina Configuration","description":"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.","status":"active","version":"1.1.2","language":"en","source_language":"en","source_url":"https://github.com/tsv1/cabina","tags":["configuration","environment-variables","pydantic","settings"],"install":[{"cmd":"pip install cabina","lang":"bash","label":"Install Cabina"}],"dependencies":[],"imports":[{"symbol":"Cabina","correct":"from cabina import Cabina"}],"quickstart":{"code":"import os\nfrom cabina import Cabina\nfrom pydantic import Field\n\nos.environ['APP_NAME'] = os.environ.get('APP_NAME', 'MyDefaultApp')\nos.environ['APP_PORT'] = os.environ.get('APP_PORT', '8000')\nos.environ['DEBUG_MODE'] = os.environ.get('DEBUG_MODE', 'true')\n\n\nclass AppConfig(Cabina):\n    app_name: str\n    app_port: int = Field(8000, env=\"APP_PORT\")\n    debug_mode: bool = False\n\n    class Config:\n        env_prefix = 'APP_'\n        case_sensitive = False\n\n\nconfig = AppConfig()\n\nprint(f\"App Name: {config.app_name}\")\nprint(f\"App Port: {config.app_port}\")\nprint(f\"Debug Mode: {config.debug_mode}\")\n\nassert config.app_name == os.environ['APP_NAME']\nassert config.app_port == int(os.environ['APP_PORT'])\nassert config.debug_mode == (os.environ['DEBUG_MODE'].lower() == 'true')","lang":"python","description":"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)."},"warnings":[{"fix":"Rewrite configuration classes to fully leverage Pydantic's `BaseSettings` features, including `Field` for `env` mapping and Pydantic's validation mechanisms.","message":"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.","severity":"breaking","affected_versions":"<1.0.0 to >=1.0.0"},{"fix":"Ensure environment variable values strictly conform to the expected type of the corresponding Pydantic field. Consult Pydantic documentation for specific type coercion rules.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install cabina` to install the library.","cause":"The Cabina library is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'cabina'"},{"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\"`).","cause":"A required configuration field (e.g., `app_name`) was not provided via environment variables, and no default value was set.","error":"pydantic.v1.error_wrappers.ValidationError: 1 validation error for AppConfig\napp_name\n  field required (type=value_error.missing)"},{"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\"`).","cause":"The environment variable for an integer field (e.g., `APP_PORT`) contains a non-integer value (e.g., 'abc').","error":"pydantic.v1.error_wrappers.ValidationError: 1 validation error for AppConfig\napp_port\n  value is not a valid integer (type=type_error.integer)"}]}