# Typed Settings
Load and merge settings from multiple different sources and present them in a structured, typed, and validated way!
## Why?
There are many different config file formats and libraries.
Many of them have a narrow scope, don't integrate well with other libs, or lack in typing support.
Typed Settings' goal is to enable you to load settings from any source (e.g., env vars, config files, vaults)
and can convert values to anything you need.
You can extend Typed Settings to support config sources that aren't supported yet
and its extensive documentation will help you on your way.
## What can it be used for?
You can use Typed Settings in any context, e.g.:
- server processes
- containerized apps
- command line applications
- scripts and tools for scientific experiments and data analysis
## What does it do?
- It loads settings from multiple sources (e.g., env vars, config files, secret vaults) in a unified way and merges the loaded values.
You can add loaders for sources we cannot imagine yet.
- It can post-process loaded values.
This allows value interpolation/templating or calling helpers that retrieve secrets from vaults.
You can create and add any processors you can image if the built-in ones are not enough.
- You can add a CLI on top to let users update the loaded settings via command line arguments.
[Click](https://click.palletsprojects.com) and [argparse](https://docs.python.org/3/library/argparse.html) are currently supported.
- Settings are cleanly structured and typed.
The type annotations are used to convert the loaded settings to the proper types.
This also includes higher level structures like dates, paths and various collections (lists, dicts, …).
You can use [attrs](https://www.attrs.org), [dataclasses](https://docs.python.org/3/library/dataclasses.html), or [Pydantic](https://docs.pydantic.dev/latest/) to write settings classes.
Types Settings uses the powerful and fast [cattrs](https://cattrs.readthedocs.io)) by default and falls back to an internal converter if **cattrs** is not installed.
- No mandatory requirements. Typed Settings works out-of-the box with dataclasses, argparse and its own converter.
The documentation contains a [full list](https://typed-settings.readthedocs.io/en/latest/why.html#comprehensive-list-of-features) of all features.
## Installation
Install and update using [pip](https://pip.pypa.io/en/stable/quickstart/):
```console
$ python -m pip install typed-settings
```
Typed Settings as **no required dependencies** (except for tomli on older Python versions).
You can install dependencies for optional features via
```console
$ python -m pip install typed-settings[<feature>,...]
```
Available features:
- `typed-settings[attrs]`: Enable settings classes via **attrs**.
- `typed-settings[pydantic]`: Enable settings classes via **Pydantic**.
- `typed-settings[cattrs]`: Enable usage of the powerful and fast **cattrs** converter.
- `typed-settings[click]`: Enable support for **Click** options.
- `typed-settings[option-groups]`: Enable support for **Click** and **Click option groups**.
- `typed-settings[jinja]`: Enable support for value interpolation with **Jinja** templates.
- `typed-settings[all]`: Install all optional requirements.
## Examples
### Hello, World!, with env. vars.
This is a very simple example that demonstrates how you can load settings from environment variables.
```python
# example.py
import attrs
import typed_settings as ts
@attrs.frozen
class Settings:
option: str
settings = ts.load(cls=Settings, appname="example")
print(settings)
```
```console
$ EXAMPLE_OPTION="Hello, World!" python example.py
Settings(option='Hello, World!')
```
### Nested classes and config files
Settings classes can be nested.
Config files define a different section for each class.
```python
# example.py
import attrs
import click
import typed_settings as ts
@attrs.frozen
class Host:
name: str
port: int
@attrs.frozen
class Settings:
host: Host
endpoint: str
retries: int = 3
settings = ts.load(
cls=Settings, appname="example", config_files=["settings.toml"]
)
print(settings)
```
```toml
# settings.toml
[example]
endpoint = "/spam"
[example.host]
name = "example.com"
port = 443
```
```console
$ python example.py
Settings(host=Host(name='example.com', port=443), endpoint='/spam', retries=3)
```
### Configurable settings loaders
The first example used a convenience shortcut with pre-configured settings loaders.
However, Typed Settings lets you explicitly configure which loaders are used and how they work:
```python
# example.py
import attrs
import typed_settings as ts
@attrs.frozen
class Settings:
option: str
settings = ts.load_settings(
cls=Settings,
loaders=[
ts.FileLoader(
files=[],
env_var="EXAMPLE_SETTINGS",
formats={
"*.toml": ts.TomlFormat("example"),
},
),
ts.EnvLoader(prefix="EXAMPLE_"),
],
)
print(settings)
```
```console
$ EXAMPLE_OPTION="Hello, World!" python example.py
Settings(option='Hello, World!')
```
In order to write your own loaders or support new file formats, you need to implement the `Loader` or `FileFormat` [protocols](https://typed-settings.readthedocs.io/en/latest/apiref.html#module-typed_settings.loaders).
You can also pass a custom [cattrs converter](https://cattrs.readthedocs.io/en/latest/index.html) to add support for additional Python types.
### Command Line Interfaces
Typed Settings can generate a command line interfaces (CLI) based on your settings.
These CLIs will load settings as described above and let users override the loades settings with command line argumments.
Typed Settings supports `argparse` and `click`.
#### Argparse
```python
# example.py
import attrs
import typed_settings as ts
@attrs.frozen
class Settings:
a_str: str = ts.option(default="default", help="A string")
an_int: int = ts.option(default=3, help="An int")
@ts.cli(Settings, "example")
def main(settings):
print(settings)
if __name__ == "__main__":
main()
```
```console
$ python example.py --help
usage: example.py [-h] [--a-str TEXT] [--an-int INT]
options:
-h, --help show this help message and exit
Settings:
Settings options
--a-str TEXT A string [default: default]
--an-int INT An int [default: 3]
$ python example.py --a-str=spam --an-int=1
Settings(a_str='spam', an_int=1)
```
#### Click
```python
# example.py
import attrs
import click
import typed_settings as ts
@attrs.frozen
class Settings:
a_str: str = ts.option(default="default", help="A string")
an_int: int = ts.option(default=3, help="An int")
@click.command()
@ts.click_options(Settings, "example")
def main(settings):
print(settings)
if __name__ == "__main__":
main()
```
```console
$ python example.py --help
Usage: example.py [OPTIONS]
Options:
--a-str TEXT A string [default: default]
--an-int INTEGER An int [default: 3]
--help Show this message and exit.
$ python example.py --a-str=spam --an-int=1
Settings(a_str='spam', an_int=1)
```
## Project Links
- [Changelog](https://typed-settings.readthedocs.io/en/latest/changelog.html)
- [Documentation](https://typed-settings.readthedocs.io)
- [GitLab](https://gitlab.com/sscherfke/typed-settings/)
- [Issues and Bugs](https://gitlab.com/sscherfke/typed-settings/-/issues)
- [PyPI](https://pypi.org/project/typed-settings/)
Raw data
{
"_id": null,
"home_page": null,
"name": "typed-settings",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "configuration, options, settings, types, validation",
"author": null,
"author_email": "Stefan Scherfke <stefan@sofa-rockers.org>",
"download_url": "https://files.pythonhosted.org/packages/c0/91/f39cff1a6eb43ba5d8e7eb810405b0a7abed7b7033f7725a09796c625547/typed_settings-24.6.0.tar.gz",
"platform": null,
"description": "# Typed Settings\n\nLoad and merge settings from multiple different sources and present them in a structured, typed, and validated way!\n\n## Why?\n\nThere are many different config file formats and libraries.\nMany of them have a narrow scope, don't integrate well with other libs, or lack in typing support.\n\nTyped Settings' goal is to enable you to load settings from any source (e.g., env vars, config files, vaults)\nand can convert values to anything you need.\n\nYou can extend Typed Settings to support config sources that aren't supported yet\nand its extensive documentation will help you on your way.\n\n## What can it be used for?\n\nYou can use Typed Settings in any context, e.g.:\n\n- server processes\n- containerized apps\n- command line applications\n- scripts and tools for scientific experiments and data analysis\n\n## What does it do?\n\n- It loads settings from multiple sources (e.g., env vars, config files, secret vaults) in a unified way and merges the loaded values.\n You can add loaders for sources we cannot imagine yet.\n\n- It can post-process loaded values.\n This allows value interpolation/templating or calling helpers that retrieve secrets from vaults.\n You can create and add any processors you can image if the built-in ones are not enough.\n\n- You can add a CLI on top to let users update the loaded settings via command line arguments.\n [Click](https://click.palletsprojects.com) and [argparse](https://docs.python.org/3/library/argparse.html) are currently supported.\n\n- Settings are cleanly structured and typed.\n The type annotations are used to convert the loaded settings to the proper types.\n This also includes higher level structures like dates, paths and various collections (lists, dicts, \u2026).\n You can use [attrs](https://www.attrs.org), [dataclasses](https://docs.python.org/3/library/dataclasses.html), or [Pydantic](https://docs.pydantic.dev/latest/) to write settings classes.\n\n Types Settings uses the powerful and fast [cattrs](https://cattrs.readthedocs.io)) by default and falls back to an internal converter if **cattrs** is not installed.\n\n- No mandatory requirements. Typed Settings works out-of-the box with dataclasses, argparse and its own converter.\n\nThe documentation contains a [full list](https://typed-settings.readthedocs.io/en/latest/why.html#comprehensive-list-of-features) of all features.\n\n\n## Installation\n\nInstall and update using [pip](https://pip.pypa.io/en/stable/quickstart/):\n\n```console\n$ python -m pip install typed-settings\n```\n\nTyped Settings as **no required dependencies** (except for tomli on older Python versions).\nYou can install dependencies for optional features via\n\n```console\n$ python -m pip install typed-settings[<feature>,...]\n```\n\nAvailable features:\n\n- `typed-settings[attrs]`: Enable settings classes via **attrs**.\n- `typed-settings[pydantic]`: Enable settings classes via **Pydantic**.\n- `typed-settings[cattrs]`: Enable usage of the powerful and fast **cattrs** converter.\n- `typed-settings[click]`: Enable support for **Click** options.\n- `typed-settings[option-groups]`: Enable support for **Click** and **Click option groups**.\n- `typed-settings[jinja]`: Enable support for value interpolation with **Jinja** templates.\n- `typed-settings[all]`: Install all optional requirements.\n\n## Examples\n\n### Hello, World!, with env. vars.\n\nThis is a very simple example that demonstrates how you can load settings from environment variables.\n\n```python\n# example.py\nimport attrs\nimport typed_settings as ts\n\n@attrs.frozen\nclass Settings:\n option: str\n\nsettings = ts.load(cls=Settings, appname=\"example\")\nprint(settings)\n```\n\n```console\n$ EXAMPLE_OPTION=\"Hello, World!\" python example.py\nSettings(option='Hello, World!')\n```\n\n\n### Nested classes and config files\n\nSettings classes can be nested.\nConfig files define a different section for each class.\n\n```python\n# example.py\nimport attrs\nimport click\n\nimport typed_settings as ts\n\n@attrs.frozen\nclass Host:\n name: str\n port: int\n\n@attrs.frozen\nclass Settings:\n host: Host\n endpoint: str\n retries: int = 3\n\nsettings = ts.load(\n cls=Settings, appname=\"example\", config_files=[\"settings.toml\"]\n)\nprint(settings)\n```\n\n```toml\n# settings.toml\n[example]\nendpoint = \"/spam\"\n\n[example.host]\nname = \"example.com\"\nport = 443\n```\n\n```console\n$ python example.py\nSettings(host=Host(name='example.com', port=443), endpoint='/spam', retries=3)\n```\n\n\n### Configurable settings loaders\n\nThe first example used a convenience shortcut with pre-configured settings loaders.\nHowever, Typed Settings lets you explicitly configure which loaders are used and how they work:\n\n```python\n# example.py\nimport attrs\nimport typed_settings as ts\n\n@attrs.frozen\nclass Settings:\n option: str\n\nsettings = ts.load_settings(\n cls=Settings,\n loaders=[\n ts.FileLoader(\n files=[],\n env_var=\"EXAMPLE_SETTINGS\",\n formats={\n \"*.toml\": ts.TomlFormat(\"example\"),\n },\n ),\n ts.EnvLoader(prefix=\"EXAMPLE_\"),\n ],\n)\nprint(settings)\n```\n\n```console\n$ EXAMPLE_OPTION=\"Hello, World!\" python example.py\nSettings(option='Hello, World!')\n```\n\nIn order to write your own loaders or support new file formats, you need to implement the `Loader` or `FileFormat` [protocols](https://typed-settings.readthedocs.io/en/latest/apiref.html#module-typed_settings.loaders).\n\nYou can also pass a custom [cattrs converter](https://cattrs.readthedocs.io/en/latest/index.html) to add support for additional Python types.\n\n\n### Command Line Interfaces\n\nTyped Settings can generate a command line interfaces (CLI) based on your settings.\nThese CLIs will load settings as described above and let users override the loades settings with command line argumments.\n\nTyped Settings supports `argparse` and `click`.\n\n\n#### Argparse\n\n```python\n# example.py\nimport attrs\nimport typed_settings as ts\n\n@attrs.frozen\nclass Settings:\n a_str: str = ts.option(default=\"default\", help=\"A string\")\n an_int: int = ts.option(default=3, help=\"An int\")\n\n@ts.cli(Settings, \"example\")\ndef main(settings):\n print(settings)\n\nif __name__ == \"__main__\":\n main()\n```\n\n```console\n$ python example.py --help\nusage: example.py [-h] [--a-str TEXT] [--an-int INT]\n\noptions:\n -h, --help show this help message and exit\n\nSettings:\n Settings options\n\n --a-str TEXT A string [default: default]\n --an-int INT An int [default: 3]\n$ python example.py --a-str=spam --an-int=1\nSettings(a_str='spam', an_int=1)\n```\n\n#### Click\n\n\n```python\n# example.py\nimport attrs\nimport click\nimport typed_settings as ts\n\n@attrs.frozen\nclass Settings:\n a_str: str = ts.option(default=\"default\", help=\"A string\")\n an_int: int = ts.option(default=3, help=\"An int\")\n\n@click.command()\n@ts.click_options(Settings, \"example\")\ndef main(settings):\n print(settings)\n\nif __name__ == \"__main__\":\n main()\n```\n\n```console\n$ python example.py --help\nUsage: example.py [OPTIONS]\n\nOptions:\n --a-str TEXT A string [default: default]\n --an-int INTEGER An int [default: 3]\n --help Show this message and exit.\n$ python example.py --a-str=spam --an-int=1\nSettings(a_str='spam', an_int=1)\n```\n\n## Project Links\n\n- [Changelog](https://typed-settings.readthedocs.io/en/latest/changelog.html)\n- [Documentation](https://typed-settings.readthedocs.io)\n- [GitLab](https://gitlab.com/sscherfke/typed-settings/)\n- [Issues and Bugs](https://gitlab.com/sscherfke/typed-settings/-/issues)\n- [PyPI](https://pypi.org/project/typed-settings/)\n",
"bugtrack_url": null,
"license": null,
"summary": "Typed settings based on attrs classes",
"version": "24.6.0",
"project_urls": {
"Changelog": "https://typed-settings.readthedocs.io/en/latest/changelog.html",
"Documentation": "https://typed-settings.readthedocs.io",
"Homepage": "https://gitlab.com/sscherfke/typed-settings",
"Issues": "https://gitlab.com/sscherfke/typed-settings/-/issues",
"Source Code": "https://gitlab.com/sscherfke/typed-settings"
},
"split_keywords": [
"configuration",
" options",
" settings",
" types",
" validation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d665659c1bebd863edc9184715fd1cf2475926cead71d83535d980577bfa2439",
"md5": "70a4bdd9e9567b4922482edc0e467e5b",
"sha256": "22221598a821395700beaafd8eab0e1bc596b394767aa37e0926c5f74d0b6a62"
},
"downloads": -1,
"filename": "typed_settings-24.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "70a4bdd9e9567b4922482edc0e467e5b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 58394,
"upload_time": "2024-11-07T09:46:25",
"upload_time_iso_8601": "2024-11-07T09:46:25.079733Z",
"url": "https://files.pythonhosted.org/packages/d6/65/659c1bebd863edc9184715fd1cf2475926cead71d83535d980577bfa2439/typed_settings-24.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c091f39cff1a6eb43ba5d8e7eb810405b0a7abed7b7033f7725a09796c625547",
"md5": "0f5e4d25b02878e11e8b5724f2ad4b06",
"sha256": "9a5595de33f80452a2038e018bc45508fffc238a8752f08f5c03dc8e7bc0d1e2"
},
"downloads": -1,
"filename": "typed_settings-24.6.0.tar.gz",
"has_sig": false,
"md5_digest": "0f5e4d25b02878e11e8b5724f2ad4b06",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 29469194,
"upload_time": "2024-11-07T09:46:28",
"upload_time_iso_8601": "2024-11-07T09:46:28.562528Z",
"url": "https://files.pythonhosted.org/packages/c0/91/f39cff1a6eb43ba5d8e7eb810405b0a7abed7b7033f7725a09796c625547/typed_settings-24.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-07 09:46:28",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "sscherfke",
"gitlab_project": "typed-settings",
"lcname": "typed-settings"
}
JSON