Skip to main content

Documentation Status Pipeline Status Coverage Report Code style: black

Typed Settings

This package allows you to cleanly structure your settings with attrs classes. Type annotations will be used to automatically convert values to the proper type1. You can currently load settings from these sources:

  • TOML files (multiple, if you want to). Paths can statically specified or dynamically set via a environment variable.
  • Environment variables
  • click command line options

You can use Typed settings, e.g., for

  • server processes
  • containerized apps
  • command line applications

Examples

Hello, World!, with env. vars.

This is a very simple example that demonstrates how you can load settings from environment variables.

# example.py
import typed_settings as ts

@ts.settings
class Settings:
    option: str

settings = ts.load_settings(cls=Settings, appname="example")
print(settings)
$ 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.

# example.py
import click

import typed_settings as ts

@ts.settings
class Host:
    name: str
    port: int = ts.option(converter=int)

@ts.settings(kw_only=True)
class Settings:
    host: Host = ts.option(converter=lambda d: Host(**d))
    endpoint: str
    retries: int = 3

settings = ts.load_settings(
    cls=Settings, appname='example', config_files=['settings.toml']
)
print(settings)
# settings.toml
[example]
endpoint = "/spam"

[example.host]
name = "example.com"
port = 443
$ python example.py
Settings(host=Host(name='example.com', port=443), endpoint='/spam', retries=3)

Click

Optionally, click options can be generated for each option. Config files and environment variables will still be read and can be overriden by passing command line options.

# example.py
import click
import typed_settings as ts

@ts.settings
class Settings:
    a_str: str = "default"
    an_int: int = 3

@click.command()
@ts.click_options(Settings, 'example')
def main(settings):
    print(settings)

if __name__ == '__main__':
    main()
$ python example.py --help
Usage: example.py [OPTIONS]

Options:
  --a-str TEXT      [default: default]
  --an-int INTEGER  [default: 3]
  --help            Show this message and exit.
$ python example.py --a-str=spam --an-int=1
Settings(a_str='spam', an_int=1)

Features

  • Settings are defined as type-hinted attrs classes.

  • Typed Settings’ settings decorator adds automatic type converstion for option values and makes your settings class frozen (immutable) by default.

  • Settings can currently be loaded from:

    • TOML files
    • Environment variables
    • click Commaoptions
  • Paths to settings files can be “hard-coded” into your code or specified via an environment variable.

  • Order of precedence:

    • Default value from settings class
    • First file from hard-coded config files list
    • ...
    • Last file from hard-coded config files list
    • First file from config files env var
    • ...
    • Last file from config files env var
    • Environment variable {PREFIX}_{SETTING_NAME}
    • (Value passed to Click option)
  • Config files are “optional” by default – no error is raised if a specified file does not exist.

  • Config files can be marked as mandatory by prefixing them with an !.

  1. Not yet: https://github.com/python-attrs/attrs/pull/653 ↩

Metadata

Release files for typed-settings 0.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for typed-settings 0.6
File Size Uploaded Provenance Actions
typed-settings-0.6.tar.gz 88.6 kB Without provenance Details for typed-settings-0.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for typed-settings 0.6
File Interpreter ABI Platform Actions
typed_settings-0.6-py3-none-any.whl Python 3 none any Details for typed_settings-0.6-py3-none-any.whl

Total release size: 99.8 kB

Release files / typed-settings-0.6.tar.gz

Download URL typed-settings-0.6.tar.gz
Size 88.6 kB
Tags Source
SHA-256 checksum
How to use checksums
a88f1904d496064199069e773607a375f6516f9b73d0ee25cd20cfc2a6e9a318
BLAKE2b-256 checksum
How to use checksums
8d5317b96ed6d4ea2190304780426744a5ca6a2378986bc3e5be84d0a40296e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/50.3.0 requests-toolbelt/0.9.1 tqdm/4.50.2 CPython/3.9.0

Release files / typed_settings-0.6-py3-none-any.whl

Download URL typed_settings-0.6-py3-none-any.whl
Size 11.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e2776f4889d5ef2c2f1e0d64c6ba6f3f7a4886e8bfc6b891440ec848f4224439
BLAKE2b-256 checksum
How to use checksums
316adcb81c9bc911eca4c897acc870fdf423c706fd96fd16f2f09e013ac267e0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/50.3.0 requests-toolbelt/0.9.1 tqdm/4.50.2 CPython/3.9.0

Security for typed-settings 0.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page