Skip to main content

Typed settings based on attrs classes

Project description

Typed Settings

PyPI PyPI - License PyPI - Python Version Documentation Status Gitlab pipeline status Gitlab code coverage Code style: black

Typed Settings allows you to cleanly structure your settings with attrs classes. Type annotations will be used to automatically convert values to the proper type. 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


Install and update using pip:

$ python -m pip install typed-settings


Hello, World!, with env. vars.

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

import typed_settings as ts

class Settings:
    option: str

settings = ts.load_settings(cls=Settings, appname="example")
$ EXAMPLE_OPTION="Hello, World!" python
Settings(option='Hello, World!')

Nested classes and config files

Settings classes can be nested. Config files define a different section for each class.

import click

import typed_settings as ts

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

class Settings:
    host: Host
    endpoint: str
    retries: int = 3

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

name = ""
port = 443
$ python
Settings(host=Host(name='', port=443), endpoint='/spam', retries=3)


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.

import click
import typed_settings as ts

class Settings:
    a_str: str = "default"
    an_int: int = 3

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

if __name__ == '__main__':
$ python --help
Usage: [OPTIONS]

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


  • 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 !.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

typed-settings-0.9.tar.gz (110.2 kB view hashes)

Uploaded Source

Built Distribution

typed_settings-0.9-py3-none-any.whl (20.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page