23.1.0 (unreleased)#


  • πŸ’₯ BREAKING: Dropped support for Python 3.7.

  • πŸ“¦ Switched from safety to pip-audit.

23.0.1 (2023-05-23)#


  • Fixed typing issues with Pylance/Pyright and attrs decorators (see #40)

23.0.0 (2023-03-07)#


  • πŸ—‘ The next regular release (23.1.0) will drop support for Python 3.7.

  • πŸ—‘ The next regular release (23.1.0) will introduce breaking changes to the converter API and settings dict. See !16 for details and for feedback.

    Your code will break when:

    • You extend the default converter or pass in your own

    • You have written custom loaders


  • πŸ“¦ Switch to CalVer with scheme YY.MINOR.MICRO (same as pip, attrs and cattrs).

  • πŸ“¦ Switch to ruff as linter.

  • ♻️ Make dict_utils part of the public API.

  • ♻️ Make optional imports in typed_settings more IDE friendly (see !14).

  • πŸ“ Added a copy button to the examples in the docs. Prompt characters and out for doctest examples or bash are not copied, only the actual code / command.

  • πŸ“ Start migration to Markdown docs with MyST-Parser.

  • πŸ“ Start using Sybil for doctests and examples.

  • πŸ“ Fixed spelling and grammatical mistakes.


  • ✨ Added settings (post) processors. They allow modifying loaded settings before they are passed to your app. This allows, e.g., using settings templates/interpolation or loading secrets from external resources via helper scripts. (See #2, #19)

  • ✨ Added a 1Password loader.

  • ✨ Added an op:// resource handler for the new URL processor (see #19).

  • ✨ Optionally show env var name in the help string for Click options (see #33).

2.0.2 (2023-01-18)#


  • πŸ› Fixed #29: Do not modify attrs metadata when creating CLI options. The metadata dict is now copied before popping items from it.

2.0.1 (2023-01-14)#


  • πŸ› Fixed #26: Typing error with Pyright/VSCode.

  • πŸ“ Improve documentation for custom Click flags (see #28).

2.0.0 (2022-11-30)#


  • πŸ’₯ BREAKING: The click_utils.TypeHandler is now called cli_utils.TypeArgsMaker and has a completely different interface. If you do not explicitly use this class, nothing will change for you.

  • πŸ’₯ BREAKING: Remove bundled attrs validators. They are now in attrs.validators (see #17).


  • ✨ Click options: Support optional types (See #22).

  • ✨ Click options: Support dicts (e.g., --env VAR1=val1 --env VAR=val2).

  • ✨ Add support for Argparse based CLIs via typed_settings.cli() (See #14).

  • ✨ Added wrappers for secrets (SecretStr and Secret) that mask their values when they are printed/logged.

  • ✨ Added mypy plugin for our attrs extensions.

  • πŸ“ The guides for core functionality now contain a section about writing settings classes and handling secrets.

1.1.1 (2022-10-08)#


  • ✨ Added support for cattrs 22.2 which renamed the main converter classes. The older version 22.1 remains supported, too.

1.1.0 (2022-07-09)#

This release mainly focuses on improving the integration with Click, especially if you want to use command groups or write extensible applications like Pytest.


  • πŸ’₯ BREAKING: Settings values that are dictionaries are no longer merged when they are provided by different settings sources. They override each other now as other scalar and container types do.

  • ♻️ Replace toml with tomli for Python <= 3.10.

  • ♻️ Use tomllib on Python 3.11 and do not depend on tomli.

  • ♻️ Require cattrs >= 22.1.0.

  • βœ… Increase test coverage to 100% (and enforce it).

  • πŸ“ Impove and extend the docs’ examples section.

  • πŸ“ Extend the guides and split them into multiple pages.


  • ✨ Support Python 3.11

  • ✨ Improve Click option generation:

    • Add support for dict options to click_options() (e.g., --env PWD_FILE=/pwd --env DEBUG=1) (See #5).

    • Allow overriding param decls and parameters for Click options (See #15).

    • You can configure the argument name of your settings in the CLI function. This allows you to use different settings in nested click commands (See #15).

    • Add support for Click option groups (See !6).

    • Add combine() function to merge multiple settings (e.g., from plug-ins) with a base class.

1.0.1 (2022-04-04)#


  • πŸ—‘ Deprecate the bundled attrs validators. They are now part of attrs.validators.


  • βœ… Adjust tests for Click 8.1


  • πŸ› Fixed #16: Support new (c)attrs namespaces. attrs 21.3 and cattrs 1.10 are now required.

  • πŸ› Bug fix

1.0.0 (2022-03-04)#

  • πŸŽ‰ First stable release!


  • πŸ’₯ BREAKING: Change Loader and FileFormat protocols to use __call__(). This allows β€œnormal” functions to be used as loaders, too.

  • πŸ’₯ BREAKING: Pass the settings class to loaders (in addition to the list of OptionInfos).

  • πŸ’₯ BREAKING: Enums are only converted from member name, not by value.

  • ♻️ The attrs auto-convert hook now uses a Cattrs converter instead of custom conversion logic.

  • βœ… Increase test coverage to 100% again.

  • βœ… Migrate to pytest7.

  • πŸ“ Write β€œGuides” section of the docs.

  • πŸ“ Update β€œGetting Started” section of the docs.

  • πŸ“ Update β€œWhy” section of the docs.

  • πŸ“ Try MyST (Markdown) but switch back to ReST (only for now, MyST looks very promising).


  • ✨ Add evolve() function for recursively updading settings.

  • ✨ Add InstanceLoader which loads settings from an existing instance of the settings class.

  • ✨ click_options() accepts just an appname and then works similar to load(). The old behavior (which is comparable to load_settings() still exists.

  • ✨ The strlisthook with : as separator is now activated by default. It helps loading lists from environment variables.


  • πŸ› Fixed #10: Fix handling tuples and sets in strlist hook.

  • πŸ› Fixed #11: Properly convert loaded values to click default values.

0.11.1 (2021-10-03)#


  • πŸ› Allow using instances of nested attrs/settings classes as default values for options again. Fixes a regression introduced by switching to cattrs.

0.11.0 (2021-10-02)#


  • πŸ—‘ The attrs specific converters and hooks are deprecated and will be removed in a future release.


  • πŸ’₯ BREAKING: Use cattrs instead of attrs auto-convert hooks. This makes converters more robust and easier to extend.

  • πŸ’₯ BREAKING: The signature of load_settings() has changed. load() is now the pre-configured convenience loader while load_settings() allows full customization of all settings loaders and value converters.


  • ✨ Loaders can now be extended by users. Typed settings bundles a file loader and an environment loader. New loaders must implement the Loader protocol.

  • ✨ The file loader can be extended to support additional file formats. File loaders must implement the FileFormat protocol.

  • ✨ Add experimental support for Python config files.

  • ✨ Environment variables can now contain list values. Theses lists can eitehr be JSON or simple {separator} spearted lists (the separator can be configured, e.g., : or ,).

0.10.0 (2021-06-23)#


  • πŸ—‘ The signature of load_settings() will change in a backwars incompatible way in the next release.


  • πŸ’₯ BREAKING: Settings classes are now mutable by default. This makes especially testing and monkeypatching a lot easier. Since settings classes are normal attrs classes, you can make your settings immutable again by passing frozen=True to the class decorator.

  • 🐍 Add support for Python 3.10.

  • πŸ— Add support for click 8.


  • ✨ load() is now the new main function for loading settings. It has the same signature as load_settings() (See: #8).

  • ✨ find() searches for a given config file from the current working dir upwards.

  • ✨ The to_bool() converter converts bools from addional values. Please use load() instead (See: #8).

0.9.2 (2021-02-10)#


  • πŸ› Fixed #3: Only replace - with _ for sections and option names, but not for dict keys.

  • πŸ› Remove debug printa.

0.9.1 (2020-12-01)#


  • πŸ› Fixed #6: Properly handle attrs default factories in options.

0.9 (2020-11-29)#


  • πŸ’₯ BREAKING: A ValueError is now raised when a config file contains invalid options.

  • πŸ’₯ BREAKING: Click options without a default (or loaded value) are now marked as required=True.

  • πŸ“ Improve Why Typed Settings docs.

  • πŸ“ Improve docs for attrs converters/validators/hooks.

  • βœ… Increase test coverage to 100%.


  • ✨ Click options support more types (datetimes, lists, tuples, …)

    • List like types use multiple=True

    • Tuple uses nargs=X

    Click types can also be exteded by users now.

  • ✨ Options can specify a help string for Click options via the click_help parameter.

  • ✨ Improve handling of container types (like set) in the attrs auto-converter.


  • πŸ› Click help strings no longer show values of secret options.

0.8 (2020-11-05)#


  • ✨ Depend on attrs 20.3 and implement auto-converters for attribute values.

  • ✨ Properly convert env. vars. with β€œbool strings” to real booleans.

  • πŸ“ Use Furo as documentation theme

  • πŸ“ Update docs:

    • Improve landing page

    • Add Getting Started section to docs

    • Add examples to example guide

    • Add doctests and test examples


  • πŸ› Replace β€œ-” in env. var. names with β€œ_”

0.7 (2020-10-13)#


  • πŸ“ Added API reference to docs.


  • πŸ› Fixed loaded settings not being used as option defaults with click.

0.6 (2020-10-11)#


  • ✨ Add pass_settings decorator that pass settings to nested Click commands.

  • πŸ“ Initialize documentaion at

  • πŸ“ Improve README and automatically test examples

0.5 (2020-09-30)#


  • ✨ Click options for basic data types (bool, int, str, Enum) can be generated now.


  • πŸ› Fix bug that prevented nested settings classes from automatically being instantiated when no settings for them were loaded.

0.4 (2020-09-25)#


  • πŸ’₯ BREAKING: Flip appname and settings_cls args of load_settings().

  • ♻️ Refactor internals to improve extensibility.


  • ✨ Added convenience wrappers for attrs:

    • settings is an alias for attr.frozen

    • option is an alias for attr.field

    • secret is an alias for attr.field and masks the options’s value with *** when the settings classes is printed.

  • ✨ Added update_settings() method which is useful for overriding settings in tests.

  • ✨ Mandatory config files can be prefixed with ! (e.g., !./credentials.toml). An error is raised if a mandatory config file does not exist.

  • πŸ‘· Add pre-commit hooks

0.3 (2020-09-17)#


  • πŸ“¦ Improved packaging

  • ♻️ Refactorings


  • πŸ‘· Added code linting and improve CI

0.2 (2020-09-02)#


  • ✨ Make sure env vars can be read


  • βœ… Added tests for load_settings()

0.1 (2020-08-28)#

  • πŸŽ‰ Initial PoC


  • πŸ’₯ Breaking change

  • ✨ New feature

  • πŸ—‘ Deprecation

  • πŸ› Bug fix

  • βœ… Tests added or improved

  • πŸ“ Docs added or improved

  • ♻️ Refactorings

  • πŸ“¦ Packaging

  • πŸ‘· CI/CD

  • πŸŽ‰ Something to celebrate