<!-- `envenom` - an elegant application configurator for the more civilized age
Copyright (C) 2024-2025 Artur Ciesielski <artur.ciesielski@gmail.com>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>. -->
# `envenom`
[](https://gitlab.com/arcanery/python/envenom/-/commits/main)
[](https://gitlab.com/arcanery/python/envenom/-/commits/main)
[](https://gitlab.com/arcanery/python/envenom/-/releases)
## Introduction
`envenom` is an elegant application configurator for the more civilized age.
`envenom` is written with simplicity and type safety in mind. It allows
you to express your application configuration declaratively in a dataclass-like
format while providing your application with type information about each entry,
its nullability and default values.
`envenom` is designed for modern usecases, allowing for pulling configuration from
environment variables or files for more sophisticated deployments on platforms
like Kubernetes - all in the spirit of [12factor](https://12factor.net/).
### How it works
An `envenom` config class looks like a regular Python dataclass - because it is one.
The `@envenom.config` decorator creates a new dataclass by converting the config fields
into their `dataclass` equivalents providing the relevant default field parameters.
This also means it's 100% compatible with dataclasses. You can:
- use a config class as a property of a regular dataclass
- use a regular dataclass as a property of a config class
- declare static or dynamic fields using standard dataclass syntax
- use the `InitVar`/`__post_init__` method for delayed initialization of fields
- use methods, `classmethod`s, `staticmethod`s, and properties
`envenom` will automatically fetch the environment variable values to populate
dataclass fields, optionally running parsers so that fields are automatically
converted to desired types. This works out of the box with all built-in types trivially
convertible from `str` (like `StrEnum` and `UUID`) and with any object type that can be
instantiated easily from a single string (any function `(str,) -> T` will work as a
parser).
If using a static type checker, the type deduction system will correctly identify most
mistakes if you declare fields, parsers or default values with mismatched types. There
are certain exceptions (for example `T` will always satisfy type bounds `T | None`).
`envenom` also offers reading variable contents from file by specifying an environment
variable with the suffix `__FILE` which contains the path to a file with the respective
secret. This aims to facilitate a common deploy pattern where secrets are mounted as
files (especially prevalent with Kubernetes).
### What `envenom` isn't
`envenom` has a clearly defined scope limited to configuration management from the
application's point of view.
This means `envenom` is only interested in converting the environment into application
configuration and does not care about how the environment gets populated in the first place.
Things that are out of scope for `envenom` include, but are not limited to:
- injecting the environment into the runtime or orchestrator
- retrieving configuration or secrets from the cloud or another storage
(AWS Parameter/Secret Store, Azure Key Vault, HashiCorp Vault, etc.)
- retrieving and parsing configuration from structured config files (`YAML`/`JSON`/`INI` etc.)
## Getting started
### Installation
```bash
python -m pip install envenom
```
### Config classes
Config classes are created with the `envenom.config` class decorator. It behaves exactly
like `dataclasses.dataclass` but allows to replace standard `dataclasses.field`
definitions with one of `envenom`-specific configuration field types.
To append a prefix to all your environment variable names within a config class, a namespace
needs to be created.
```python
from uuid import UUID, uuid4
from envenom import config, defaults, namespace, optional, required
@config(namespace("myapp"))
class AppCfg:
required_str = required()
optional_int = optional(int)
defaults_uuid = defaults(UUID, default_factory=uuid4)
```
### Field types
`envenom` offers three supported field types:
- `required` for configuration variables that have to be provided. If the value cannot
be found, `ConfigurationMissing` will be raised.
- `optional` for configuration variables that don't have to be provided. If the value cannot
be found, it will be set to `None`.
- `defaults` for configuration variables where a default value can be provided. If the
value cannot be found, it will be set to the default, which can be either a static value
or created at instantiation by a factory function.
### Supplying values
To generate the environment variable name:
- join all namespace segments and the variable name together with `__`
- replace strings of nonsensical characters (`[^0-9a-zA-Z_]+`) with `_`
- transform to uppercase
As an example, a field named `dsn` in a config class with `Namespace("myapp", "db")`
will be mapped to `MYAPP__DB__DSN`.
## Basic usage - complete example
This example shows how to build a basic config structure for an application using a
database service with injectable configuration as an example. It is available in the
`envenom.examples.quickstart` runnable module.
```python
from functools import cached_property
from uuid import UUID, uuid4
from envenom import config, defaults, namespace, optional, required, subconfig
from envenom.examples import print_config_tree
from envenom.parsers import bool_parser
myapp = namespace("myapp")
myapp_db = myapp / "db"
@config(myapp_db)
class DbCfg:
scheme: str = defaults(default="postgresql+psycopg")
host: str = required()
port: int = defaults(int, default=5432)
database: str = required()
username: str | None = optional()
password: str | None = optional()
connection_timeout: int | None = optional(int)
sslmode_require: bool = defaults(bool_parser, default=False)
@cached_property
def auth(self) -> str:
if not self.username and not self.password:
return ""
auth = ""
if self.username:
auth += self.username
if self.password:
auth += f":{self.password}"
if auth:
auth += "@"
return auth
@cached_property
def query_string(self) -> str:
query: dict[str, str] = {}
if self.connection_timeout:
query["timeout"] = str(self.connection_timeout)
if self.sslmode_require:
query["sslmode"] = "require"
if not query:
return ""
query_string = "&".join((f"{key}={value}" for key, value in query.items()))
return f"?{query_string}"
@cached_property
def connection_string(self) -> str:
return (
f"{self.scheme}://{self.auth}{self.host}:{self.port}"
f"/{self.database}{self.query_string}"
)
@config(myapp)
class AppCfg:
worker_id: UUID = defaults(UUID, default_factory=uuid4)
secret_key: str = required()
db: DbCfg = subconfig(DbCfg)
if __name__ == "__main__":
cfg = AppCfg()
print_config_tree(cfg)
print(f"cfg.db.connection_string: {repr(cfg.db.connection_string)}")
```
Run the example:
```bash
python -m envenom.examples.quickstart
```
```
Traceback (most recent call last):
...
raise ConfigurationMissing(self.env_name)
envenom.errors.ConfigurationMissing: 'MYAPP__SECRET_KEY'
```
As soon as it encounters a required field, the config class returns
an error because there's no environment set.
Run the example again with the environment set:
```bash
MYAPP__SECRET_KEY='}uZ?uvJdKDM+$2[$dR)).n4q1SX!A$0u{(+D$PVB' \
MYAPP__DB__HOST='postgres.example.com' \
MYAPP__DB__DATABASE='test-database' \
MYAPP__DB__USERNAME='user' \
MYAPP__DB__SSLMODE_REQUIRE='t' \
MYAPP__DB__CONNECTION_TIMEOUT='15' \
python -m envenom.examples.quickstart
```
```
-----
cfg:
worker_id: UUID('2fd334a5-5f08-4815-8107-928c291264c3')
secret_key: '}uZ?uvJdKDM+$2[$dR)).n4q1SX!A$0u{(+D$PVB'
db:
scheme: 'postgresql+psycopg'
host: 'postgres.example.com'
port: 5432
database: 'test-database'
username: 'user'
password: None
connection_timeout: 15
sslmode_require: True
-----
cfg.db.connection_string: 'postgresql+psycopg://user@postgres.example.com:5432/test-database?timeout=15&sslmode=require'
```
Raw data
{
"_id": null,
"home_page": null,
"name": "envenom",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": "env, environment, config, configuration",
"author": "Artur Ciesielski",
"author_email": "artur.ciesielski@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a1/a4/62fdee7d7a0c9370e5fcce3d9b0cd8deb7a4262207bd86dbc24e09ce553a/envenom-3.2.2.post1.tar.gz",
"platform": null,
"description": "<!-- `envenom` - an elegant application configurator for the more civilized age\nCopyright (C) 2024-2025 Artur Ciesielski <artur.ciesielski@gmail.com>\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program. If not, see <https://www.gnu.org/licenses/>. -->\n\n# `envenom`\n\n[](https://gitlab.com/arcanery/python/envenom/-/commits/main)\n[](https://gitlab.com/arcanery/python/envenom/-/commits/main)\n[](https://gitlab.com/arcanery/python/envenom/-/releases)\n\n## Introduction\n\n`envenom` is an elegant application configurator for the more civilized age.\n\n`envenom` is written with simplicity and type safety in mind. It allows\nyou to express your application configuration declaratively in a dataclass-like\nformat while providing your application with type information about each entry,\nits nullability and default values.\n\n`envenom` is designed for modern usecases, allowing for pulling configuration from\nenvironment variables or files for more sophisticated deployments on platforms\nlike Kubernetes - all in the spirit of [12factor](https://12factor.net/).\n\n### How it works\n\nAn `envenom` config class looks like a regular Python dataclass - because it is one.\n\nThe `@envenom.config` decorator creates a new dataclass by converting the config fields\ninto their `dataclass` equivalents providing the relevant default field parameters.\n\nThis also means it's 100% compatible with dataclasses. You can:\n\n- use a config class as a property of a regular dataclass\n- use a regular dataclass as a property of a config class\n- declare static or dynamic fields using standard dataclass syntax\n- use the `InitVar`/`__post_init__` method for delayed initialization of fields\n- use methods, `classmethod`s, `staticmethod`s, and properties\n\n`envenom` will automatically fetch the environment variable values to populate\ndataclass fields, optionally running parsers so that fields are automatically\nconverted to desired types. This works out of the box with all built-in types trivially\nconvertible from `str` (like `StrEnum` and `UUID`) and with any object type that can be\ninstantiated easily from a single string (any function `(str,) -> T` will work as a\nparser).\n\nIf using a static type checker, the type deduction system will correctly identify most\nmistakes if you declare fields, parsers or default values with mismatched types. There\nare certain exceptions (for example `T` will always satisfy type bounds `T | None`).\n\n`envenom` also offers reading variable contents from file by specifying an environment\nvariable with the suffix `__FILE` which contains the path to a file with the respective\nsecret. This aims to facilitate a common deploy pattern where secrets are mounted as\nfiles (especially prevalent with Kubernetes).\n\n### What `envenom` isn't\n\n`envenom` has a clearly defined scope limited to configuration management from the\napplication's point of view.\n\nThis means `envenom` is only interested in converting the environment into application\nconfiguration and does not care about how the environment gets populated in the first place.\n\nThings that are out of scope for `envenom` include, but are not limited to:\n\n- injecting the environment into the runtime or orchestrator\n- retrieving configuration or secrets from the cloud or another storage\n(AWS Parameter/Secret Store, Azure Key Vault, HashiCorp Vault, etc.)\n- retrieving and parsing configuration from structured config files (`YAML`/`JSON`/`INI` etc.)\n\n## Getting started\n\n### Installation\n\n```bash\npython -m pip install envenom\n```\n\n### Config classes\n\nConfig classes are created with the `envenom.config` class decorator. It behaves exactly\nlike `dataclasses.dataclass` but allows to replace standard `dataclasses.field`\ndefinitions with one of `envenom`-specific configuration field types.\n\nTo append a prefix to all your environment variable names within a config class, a namespace\nneeds to be created.\n\n```python\nfrom uuid import UUID, uuid4\n\nfrom envenom import config, defaults, namespace, optional, required\n\n\n@config(namespace(\"myapp\"))\nclass AppCfg:\n required_str = required()\n optional_int = optional(int)\n defaults_uuid = defaults(UUID, default_factory=uuid4)\n```\n\n### Field types\n\n`envenom` offers three supported field types:\n\n- `required` for configuration variables that have to be provided. If the value cannot\nbe found, `ConfigurationMissing` will be raised.\n- `optional` for configuration variables that don't have to be provided. If the value cannot\nbe found, it will be set to `None`.\n- `defaults` for configuration variables where a default value can be provided. If the\nvalue cannot be found, it will be set to the default, which can be either a static value\nor created at instantiation by a factory function.\n\n### Supplying values\n\nTo generate the environment variable name:\n\n- join all namespace segments and the variable name together with `__`\n- replace strings of nonsensical characters (`[^0-9a-zA-Z_]+`) with `_`\n- transform to uppercase\n\nAs an example, a field named `dsn` in a config class with `Namespace(\"myapp\", \"db\")`\nwill be mapped to `MYAPP__DB__DSN`.\n\n## Basic usage - complete example\n\nThis example shows how to build a basic config structure for an application using a\ndatabase service with injectable configuration as an example. It is available in the\n`envenom.examples.quickstart` runnable module.\n\n```python\nfrom functools import cached_property\nfrom uuid import UUID, uuid4\n\nfrom envenom import config, defaults, namespace, optional, required, subconfig\nfrom envenom.examples import print_config_tree\nfrom envenom.parsers import bool_parser\n\nmyapp = namespace(\"myapp\")\nmyapp_db = myapp / \"db\"\n\n\n@config(myapp_db)\nclass DbCfg:\n scheme: str = defaults(default=\"postgresql+psycopg\")\n host: str = required()\n port: int = defaults(int, default=5432)\n database: str = required()\n username: str | None = optional()\n password: str | None = optional()\n connection_timeout: int | None = optional(int)\n sslmode_require: bool = defaults(bool_parser, default=False)\n\n @cached_property\n def auth(self) -> str:\n if not self.username and not self.password:\n return \"\"\n\n auth = \"\"\n if self.username:\n auth += self.username\n if self.password:\n auth += f\":{self.password}\"\n if auth:\n auth += \"@\"\n\n return auth\n\n @cached_property\n def query_string(self) -> str:\n query: dict[str, str] = {}\n if self.connection_timeout:\n query[\"timeout\"] = str(self.connection_timeout)\n if self.sslmode_require:\n query[\"sslmode\"] = \"require\"\n\n if not query:\n return \"\"\n\n query_string = \"&\".join((f\"{key}={value}\" for key, value in query.items()))\n return f\"?{query_string}\"\n\n @cached_property\n def connection_string(self) -> str:\n return (\n f\"{self.scheme}://{self.auth}{self.host}:{self.port}\"\n f\"/{self.database}{self.query_string}\"\n )\n\n\n@config(myapp)\nclass AppCfg:\n worker_id: UUID = defaults(UUID, default_factory=uuid4)\n secret_key: str = required()\n db: DbCfg = subconfig(DbCfg)\n\n\nif __name__ == \"__main__\":\n cfg = AppCfg()\n\n print_config_tree(cfg)\n print(f\"cfg.db.connection_string: {repr(cfg.db.connection_string)}\")\n```\n\nRun the example:\n\n```bash\npython -m envenom.examples.quickstart\n```\n\n```\nTraceback (most recent call last):\n ...\n raise ConfigurationMissing(self.env_name)\nenvenom.errors.ConfigurationMissing: 'MYAPP__SECRET_KEY'\n```\n\nAs soon as it encounters a required field, the config class returns\nan error because there's no environment set.\n\nRun the example again with the environment set:\n\n```bash\nMYAPP__SECRET_KEY='}uZ?uvJdKDM+$2[$dR)).n4q1SX!A$0u{(+D$PVB' \\\nMYAPP__DB__HOST='postgres.example.com' \\\nMYAPP__DB__DATABASE='test-database' \\\nMYAPP__DB__USERNAME='user' \\\nMYAPP__DB__SSLMODE_REQUIRE='t' \\\nMYAPP__DB__CONNECTION_TIMEOUT='15' \\\npython -m envenom.examples.quickstart\n```\n\n```\n-----\ncfg:\n worker_id: UUID('2fd334a5-5f08-4815-8107-928c291264c3')\n secret_key: '}uZ?uvJdKDM+$2[$dR)).n4q1SX!A$0u{(+D$PVB'\n db:\n scheme: 'postgresql+psycopg'\n host: 'postgres.example.com'\n port: 5432\n database: 'test-database'\n username: 'user'\n password: None\n connection_timeout: 15\n sslmode_require: True\n-----\ncfg.db.connection_string: 'postgresql+psycopg://user@postgres.example.com:5432/test-database?timeout=15&sslmode=require'\n```\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "An elegant application configurator for the more civilized age",
"version": "3.2.2.post1",
"project_urls": {
"Documentation": "https://arcanery.gitlab.io/python/envenom/",
"Homepage": "https://gitlab.com/arcanery/python/envenom",
"Repository": "https://gitlab.com/arcanery/python/envenom"
},
"split_keywords": [
"env",
" environment",
" config",
" configuration"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e4d48412b311d5b3819f0af6c3c9ee07b0d9cecf92cf77dcaf74309363cb2c05",
"md5": "5f294faacddbe991972f4962455a734d",
"sha256": "e27ecbc4d5b021d250c2fda8313f5f1fbe63fce44eb09709e251d70214054d64"
},
"downloads": -1,
"filename": "envenom-3.2.2.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5f294faacddbe991972f4962455a734d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 40418,
"upload_time": "2025-08-08T20:16:42",
"upload_time_iso_8601": "2025-08-08T20:16:42.388238Z",
"url": "https://files.pythonhosted.org/packages/e4/d4/8412b311d5b3819f0af6c3c9ee07b0d9cecf92cf77dcaf74309363cb2c05/envenom-3.2.2.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a1a462fdee7d7a0c9370e5fcce3d9b0cd8deb7a4262207bd86dbc24e09ce553a",
"md5": "bf4c426a0548f2240aa301fb2b640995",
"sha256": "674cb4b8efc14b83cd95c1ca6cc78c9b62f55311fcba3883ae33d0197fbfcc74"
},
"downloads": -1,
"filename": "envenom-3.2.2.post1.tar.gz",
"has_sig": false,
"md5_digest": "bf4c426a0548f2240aa301fb2b640995",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 27458,
"upload_time": "2025-08-08T20:16:43",
"upload_time_iso_8601": "2025-08-08T20:16:43.233252Z",
"url": "https://files.pythonhosted.org/packages/a1/a4/62fdee7d7a0c9370e5fcce3d9b0cd8deb7a4262207bd86dbc24e09ce553a/envenom-3.2.2.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 20:16:43",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "arcanery",
"gitlab_project": "python",
"lcname": "envenom"
}
JSON