# cabina
[](https://codecov.io/gh/tsv1/cabina)
[](https://pypi.python.org/pypi/cabina/)
[](https://pypi.python.org/pypi/cabina/)
[](https://pypi.python.org/pypi/cabina/)
**cabina** is a Python library that simplifies building hierarchical, environment-driven configurations. It provides:
- **Simple class-based configurations**
- **Automatic environment variable parsing**
- **Type-safe defaults**
- **Computed values**
- **Flexible customization**
## Installation
```sh
pip3 install cabina
```
## Quick Start
Here’s a minimal example showing how cabina handles environment variables, defaults, and computed properties:
```python
import cabina
from cabina import computed, env
class Config(cabina.Config):
class Main(cabina.Section):
API_HOST: str = env.str("API_HOST", default="localhost")
API_PORT: int = env.int("API_PORT", default=8080)
@computed
def API_URL(cls) -> str:
return f"http://{cls.API_HOST}:{cls.API_PORT}"
# Usage
assert Config.Main.API_URL == "http://localhost:8080"
assert Config["Main"]["API_URL"] == "http://localhost:8080"
# Print
print(Config)
# class <Config>:
# class <Main>:
# API_HOST = 'localhost'
# API_PORT = 8080
# API_URL = 'http://localhost:8080'
```
## Recipes
Below are some common patterns and features you can use with **cabina**:
- [Root Section](#root-section)
- [Computed Values](#computed-values)
- [Default Values](#default-values)
- [Raw Values](#raw-values)
- [Custom Parsers](#custom-parsers)
- [JSON Parser](#json-parser)
- [Lazy Env](#lazy-env)
- [Env Vars Prefix](#env-vars-prefix)
- [Inheritance](#inheritance)
### Root Section
You can use **cabina** for simple, flat configurations by inheriting `cabina.Section` in your main config:
```sh
export API_HOST=localhost
export API_PORT=8080
```
```python
import cabina
from cabina import env
class Config(cabina.Config, cabina.Section): # Note the inheritance
API_HOST = env.str("API_HOST")
API_PORT = env.int("API_PORT")
assert Config.API_HOST == "localhost"
assert Config.API_PORT == 8080
```
### Computed Values
You can define dynamic or derived config values via the `@computed` decorator:
```sh
export API_HOST=localhost
export API_PORT=8080
```
```python
import cabina
from cabina import computed, env
class Config(cabina.Config, cabina.Section):
API_HOST: str = env.str("API_HOST")
API_PORT: int = env.int("API_PORT")
@computed
def API_URL(cls) -> str:
return f"http://{cls.API_HOST}:{cls.API_PORT}"
assert Config.API_URL == "http://localhost:8080"
```
### Default Values
Provide a default if an environment variable isn’t set:
```sh
export API_HOST=127.0.0.1
```
```python
import cabina
from cabina import env
class Config(cabina.Config, cabina.Section):
API_HOST = env.str("API_HOST", default="localhost")
API_PORT = env.int("API_PORT", default=8080)
assert Config.API_HOST == "127.0.0.1"
assert Config.API_PORT == 8080
```
### Raw Values
Get the raw, unprocessed string from an environment variable — even if it includes leading/trailing spaces:
```sh
export DEBUG=" yes"
```
```python
import cabina
from cabina import env
class Config(cabina.Config, cabina.Section):
DEBUG_RAW = env.raw("DEBUG") # Same as env("DEBUG") without processing
DEBUG_STR = env.str("DEBUG") # Strips whitespace
assert Config.DEBUG_RAW == " yes" # The raw value includes whitespace
assert Config.DEBUG_STR == "yes" # Whitespace is stripped
```
### Custom Parsers
Use custom parsing functions to handle special formats. For instance, parse a duration string with `pytimeparse`:
```sh
export HTTP_TIMEOUT=10s
```
```python
import cabina
from cabina import env
from pytimeparse import parse as parse_duration
class Config(cabina.Config, cabina.Section):
HTTP_TIMEOUT: int = env("HTTP_TIMEOUT", parser=parse_duration)
assert Config.HTTP_TIMEOUT == 10
```
### JSON Parser
Easily load JSON data from an environment variable:
```sh
export IMAGE_SETTINGS='{"AllowedContentTypes": ["image/png", "image/jpeg"]}'
```
```python
import json
import cabina
from cabina import env
class Config(cabina.Config, cabina.Section):
IMAGE_SETTINGS = env("IMAGE_SETTINGS", parser=json.loads)
assert Config.IMAGE_SETTINGS == {
"AllowedContentTypes": ["image/png", "image/jpeg"]
}
```
### Lazy Env
Defer parsing environment variables until their first access. This can be useful if some variables may not exist at import time:
```sh
export DEBUG=yes
export API_PORT=80a # Contains an invalid int "80a"
```
```python
import cabina
from cabina import lazy_env
class Config(cabina.Config, cabina.Section):
DEBUG = lazy_env.bool("DEBUG")
API_HOST = lazy_env.str("API_HOST") # Only fetched upon attribute access
API_PORT = lazy_env.int("API_PORT")
# Attempt to fetch all at once
Config.prefetch()
# Raises ConfigEnvError with:
# - Config.API_HOST: 'API_HOST' does not exist
# - Config.API_PORT: Failed to parse '80a' as int
```
### Env Vars Prefix
Use a prefix for all your environment variables to avoid collisions:
```sh
export APP_HOST=localhost
export APP_PORT=8080
```
```python
import cabina
env = cabina.Environment(prefix="APP_")
class Config(cabina.Config, cabina.Section):
API_HOST = env.str("HOST") # 'APP_HOST' will be used
API_PORT = env.int("PORT") # 'APP_PORT' will be used
assert Config.API_HOST == "localhost"
assert Config.API_PORT == 8080
```
### Inheritance
Create a base configuration and extend it for local or specialized use cases:
```python
import cabina
class Config(cabina.Config, cabina.Section):
DEBUG = False
class Api(cabina.Section):
API_HOST = "app.dev"
API_PORT = 5000
class ConfigLocal(Config):
DEBUG = True
class Api(Config.Api):
API_HOST = "localhost"
assert ConfigLocal.DEBUG is True
assert ConfigLocal.Api.API_HOST == "localhost"
assert ConfigLocal.Api.API_PORT == 5000
```
## Contributing
Contributions, bug reports, and feature requests are welcome! Feel free to open an [issue](https://github.com/tsv1/cabina/issues) or submit a pull request.
Raw data
{
"_id": null,
"home_page": "https://github.com/tsv1/cabina",
"name": "cabina",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Nikita Tsvetkov",
"author_email": "tsv1@fastmail.com",
"download_url": "https://files.pythonhosted.org/packages/f5/42/cb2fd18fb213823470ae5e6e40c3b68180e0e630f08fd836074e7fcbc7b9/cabina-1.1.2.tar.gz",
"platform": null,
"description": "# cabina\n\n[](https://codecov.io/gh/tsv1/cabina)\n[](https://pypi.python.org/pypi/cabina/)\n[](https://pypi.python.org/pypi/cabina/)\n[](https://pypi.python.org/pypi/cabina/)\n\n**cabina** is a Python library that simplifies building hierarchical, environment-driven configurations. It provides:\n\n- **Simple class-based configurations** \n- **Automatic environment variable parsing** \n- **Type-safe defaults** \n- **Computed values** \n- **Flexible customization** \n\n## Installation\n\n```sh\npip3 install cabina\n```\n\n## Quick Start\n\nHere\u2019s a minimal example showing how cabina handles environment variables, defaults, and computed properties:\n\n```python\nimport cabina\nfrom cabina import computed, env\n\nclass Config(cabina.Config):\n class Main(cabina.Section):\n API_HOST: str = env.str(\"API_HOST\", default=\"localhost\")\n API_PORT: int = env.int(\"API_PORT\", default=8080)\n\n @computed\n def API_URL(cls) -> str:\n return f\"http://{cls.API_HOST}:{cls.API_PORT}\"\n\n# Usage\nassert Config.Main.API_URL == \"http://localhost:8080\"\nassert Config[\"Main\"][\"API_URL\"] == \"http://localhost:8080\"\n\n# Print\nprint(Config)\n# class <Config>:\n# class <Main>:\n# API_HOST = 'localhost'\n# API_PORT = 8080\n# API_URL = 'http://localhost:8080'\n```\n\n## Recipes\n\nBelow are some common patterns and features you can use with **cabina**:\n\n- [Root Section](#root-section) \n- [Computed Values](#computed-values) \n- [Default Values](#default-values) \n- [Raw Values](#raw-values) \n- [Custom Parsers](#custom-parsers) \n- [JSON Parser](#json-parser) \n- [Lazy Env](#lazy-env) \n- [Env Vars Prefix](#env-vars-prefix) \n- [Inheritance](#inheritance)\n\n### Root Section\n\nYou can use **cabina** for simple, flat configurations by inheriting `cabina.Section` in your main config:\n\n```sh\nexport API_HOST=localhost\nexport API_PORT=8080\n```\n\n```python\nimport cabina\nfrom cabina import env\n\nclass Config(cabina.Config, cabina.Section): # Note the inheritance\n API_HOST = env.str(\"API_HOST\")\n API_PORT = env.int(\"API_PORT\")\n\nassert Config.API_HOST == \"localhost\"\nassert Config.API_PORT == 8080\n```\n\n### Computed Values\n\nYou can define dynamic or derived config values via the `@computed` decorator:\n\n```sh\nexport API_HOST=localhost\nexport API_PORT=8080\n```\n\n```python\nimport cabina\nfrom cabina import computed, env\n\nclass Config(cabina.Config, cabina.Section):\n API_HOST: str = env.str(\"API_HOST\")\n API_PORT: int = env.int(\"API_PORT\")\n\n @computed\n def API_URL(cls) -> str:\n return f\"http://{cls.API_HOST}:{cls.API_PORT}\"\n\nassert Config.API_URL == \"http://localhost:8080\"\n```\n\n### Default Values\n\nProvide a default if an environment variable isn\u2019t set:\n\n```sh\nexport API_HOST=127.0.0.1\n```\n\n```python\nimport cabina\nfrom cabina import env\n\nclass Config(cabina.Config, cabina.Section):\n API_HOST = env.str(\"API_HOST\", default=\"localhost\")\n API_PORT = env.int(\"API_PORT\", default=8080)\n\nassert Config.API_HOST == \"127.0.0.1\"\nassert Config.API_PORT == 8080\n```\n\n### Raw Values\n\nGet the raw, unprocessed string from an environment variable \u2014 even if it includes leading/trailing spaces:\n\n```sh\nexport DEBUG=\" yes\"\n```\n\n```python\nimport cabina\nfrom cabina import env\n\nclass Config(cabina.Config, cabina.Section):\n DEBUG_RAW = env.raw(\"DEBUG\") # Same as env(\"DEBUG\") without processing\n DEBUG_STR = env.str(\"DEBUG\") # Strips whitespace\n\nassert Config.DEBUG_RAW == \" yes\" # The raw value includes whitespace\nassert Config.DEBUG_STR == \"yes\" # Whitespace is stripped\n```\n\n### Custom Parsers\n\nUse custom parsing functions to handle special formats. For instance, parse a duration string with `pytimeparse`:\n\n```sh\nexport HTTP_TIMEOUT=10s\n```\n\n```python\nimport cabina\nfrom cabina import env\nfrom pytimeparse import parse as parse_duration\n\nclass Config(cabina.Config, cabina.Section):\n HTTP_TIMEOUT: int = env(\"HTTP_TIMEOUT\", parser=parse_duration)\n\nassert Config.HTTP_TIMEOUT == 10\n```\n\n### JSON Parser\n\nEasily load JSON data from an environment variable:\n\n```sh\nexport IMAGE_SETTINGS='{\"AllowedContentTypes\": [\"image/png\", \"image/jpeg\"]}'\n```\n\n```python\nimport json\nimport cabina\nfrom cabina import env\n\nclass Config(cabina.Config, cabina.Section):\n IMAGE_SETTINGS = env(\"IMAGE_SETTINGS\", parser=json.loads)\n\nassert Config.IMAGE_SETTINGS == {\n \"AllowedContentTypes\": [\"image/png\", \"image/jpeg\"]\n}\n```\n\n### Lazy Env\n\nDefer parsing environment variables until their first access. This can be useful if some variables may not exist at import time:\n\n```sh\nexport DEBUG=yes\nexport API_PORT=80a # Contains an invalid int \"80a\"\n```\n\n```python\nimport cabina\nfrom cabina import lazy_env\n\nclass Config(cabina.Config, cabina.Section):\n DEBUG = lazy_env.bool(\"DEBUG\")\n API_HOST = lazy_env.str(\"API_HOST\") # Only fetched upon attribute access\n API_PORT = lazy_env.int(\"API_PORT\")\n\n# Attempt to fetch all at once\nConfig.prefetch()\n# Raises ConfigEnvError with:\n# - Config.API_HOST: 'API_HOST' does not exist\n# - Config.API_PORT: Failed to parse '80a' as int\n```\n\n### Env Vars Prefix\n\nUse a prefix for all your environment variables to avoid collisions:\n\n```sh\nexport APP_HOST=localhost\nexport APP_PORT=8080\n```\n\n```python\nimport cabina\n\nenv = cabina.Environment(prefix=\"APP_\")\n\nclass Config(cabina.Config, cabina.Section):\n API_HOST = env.str(\"HOST\") # 'APP_HOST' will be used\n API_PORT = env.int(\"PORT\") # 'APP_PORT' will be used\n\nassert Config.API_HOST == \"localhost\"\nassert Config.API_PORT == 8080\n```\n\n### Inheritance\n\nCreate a base configuration and extend it for local or specialized use cases:\n\n```python\nimport cabina\n\nclass Config(cabina.Config, cabina.Section):\n DEBUG = False\n\n class Api(cabina.Section):\n API_HOST = \"app.dev\"\n API_PORT = 5000\n\nclass ConfigLocal(Config):\n DEBUG = True\n\n class Api(Config.Api):\n API_HOST = \"localhost\"\n\nassert ConfigLocal.DEBUG is True\nassert ConfigLocal.Api.API_HOST == \"localhost\"\nassert ConfigLocal.Api.API_PORT == 5000\n```\n\n## Contributing\n\nContributions, bug reports, and feature requests are welcome! Feel free to open an [issue](https://github.com/tsv1/cabina/issues) or submit a pull request.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Configuration with typed env vars",
"version": "1.1.2",
"project_urls": {
"Homepage": "https://github.com/tsv1/cabina"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "54cc7db5582ec76688c65132265829ab56c1cea2d9f79755c91bd23a3762e61f",
"md5": "7514e84626287831ff033e6895956794",
"sha256": "1be6c0b7e411d91af7bbe3c0315ea6e31251cbd24e9d7fa8e3c1b3c78b90eb63"
},
"downloads": -1,
"filename": "cabina-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7514e84626287831ff033e6895956794",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18948,
"upload_time": "2025-01-07T11:55:46",
"upload_time_iso_8601": "2025-01-07T11:55:46.010776Z",
"url": "https://files.pythonhosted.org/packages/54/cc/7db5582ec76688c65132265829ab56c1cea2d9f79755c91bd23a3762e61f/cabina-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f542cb2fd18fb213823470ae5e6e40c3b68180e0e630f08fd836074e7fcbc7b9",
"md5": "37bc27316a6881930bf1b7a5804d888d",
"sha256": "91502936f2e75143403999be96bb199d4819825a462aabb8ffd2d8848b702bd5"
},
"downloads": -1,
"filename": "cabina-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "37bc27316a6881930bf1b7a5804d888d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22180,
"upload_time": "2025-01-07T11:55:47",
"upload_time_iso_8601": "2025-01-07T11:55:47.248279Z",
"url": "https://files.pythonhosted.org/packages/f5/42/cb2fd18fb213823470ae5e6e40c3b68180e0e630f08fd836074e7fcbc7b9/cabina-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-07 11:55:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tsv1",
"github_project": "cabina",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "niltype",
"specs": [
[
"<",
"2.0"
],
[
">=",
"0.3"
]
]
}
],
"lcname": "cabina"
}
JSON
