Changelog#
23.1.0 (unreleased)#
Changed#
π₯ BREAKING: Dropped support for Python 3.7.
π₯ BREAKING: Refactor internal handling of loaded option values.
This will affect you if you have created a custom loader or processor, or if you rely on internal functionality.
Every loader now stores some meta data with the settings it loaded. This meta data can, for example, be used to resolve relative paths in option values relative to the config file from which they were loaded.
You can re-enable the old behavior by explicitly using the converter returned by
default_converter(resolve_paths=False)
.This also improves error messages for when one or more option values cannot be converted to the desired type.
π₯ BREAKING: Relative paths are now always resolved relative to the source they are loaded from. This is either the parent directory of a config file or the current working directory (#30).
π₯ BREAKING: The signature of
argparse_utils
βmake_parser()
andnamespace2settings()
function changed. They now return and take the merged settings. The Signature ofcli()
remains unchanged. See #41.π₯ BREAKING: The deprecated
typed_settings.attrs.hooks
module has been removed.β¨ Added a built-in
TSConverter
as an alternative forcattrs
(which is still supported and recommended).β¨
cattrs
is now an optional dependency. You can install it withpython -m pip install -U typed-settings[cattrs]
.β¨ Added a dictionary loader. This is useful for testing purposes.
23.0.1 (2023-05-23)#
Changed#
Fixed typing issues with Pylance/Pyright and attrs decorators (see #40)
23.0.0 (2023-03-07)#
Deprecated#
π 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
Changed#
π¦ 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#
β¨ 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#
π 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#
2.0.0 (2022-11-30)#
Changed#
π₯ BREAKING: The
click_utils.TypeHandler
is now calledcli_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).
Added#
β¨ 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
andSecret
) 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#
β¨ 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.
Changed#
π₯ 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
withtomli
for Python <= 3.10.β»οΈ Use
tomllib
on Python 3.11 and do not depend ontomli
.β»οΈ 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.
Added#
β¨ Support Python 3.11
β¨ Improve Click option generation:
Add support for
dict
options toclick_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)#
Deprecated#
π Deprecate the bundled
attrs
validators. They are now part ofattrs.validators
.
Changed#
β Adjust tests for Click 8.1
Fixed#
π Fixed #16: Support new (c)attrs namespaces.
attrs
21.3 andcattrs
1.10 are now required.π Bug fix
1.0.0 (2022-03-04)#
π First stable release!
Changed#
π₯ BREAKING: Change
Loader
andFileFormat
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
OptionInfo
s).π₯ 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).
Added#
β¨ 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 toload()
. The old behavior (which is comparable toload_settings()
still exists.β¨ The
strlisthook
with:
as separator is now activated by default. It helps loading lists from environment variables.
Fixed#
0.11.1 (2021-10-03)#
Fixed#
π 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)#
Deprecated#
π The attrs specific converters and hooks are deprecated and will be removed in a future release.
Changed#
π₯ 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 whileload_settings()
allows full customization of all settings loaders and value converters.
Added#
β¨ 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)#
Deprecated#
π The signature of
load_settings()
will change in a backwars incompatible way in the next release.
Changed#
π₯ 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.
Added#
β¨
load()
is now the new main function for loading settings. It has the same signature asload_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 useload()
instead (See: #8).
0.9.2 (2021-02-10)#
Fixed#
π 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#
π Fixed #6: Properly handle attrs default factories in options.
0.9 (2020-11-29)#
Changed#
π₯ 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%.
Added#
β¨ 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.
Fixed#
π Click help strings no longer show values of secret options.
0.8 (2020-11-05)#
Added#
β¨ 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
Fixed#
π Replace β-β in env. var. names with β_β
0.7 (2020-10-13)#
Added#
π Added API reference to docs.
Fixed#
π Fixed loaded settings not being used as option defaults with click.
0.6 (2020-10-11)#
Added#
β¨ Add
pass_settings
decorator that pass settings to nested Click commands.π Initialize documentaion at https://typed-settings.readthedocs.io
π Improve README and automatically test examples
0.5 (2020-09-30)#
Added#
β¨ Click options for basic data types (
bool
,int
,str
,Enum
) can be generated now.
Fixed#
π Fix bug that prevented nested settings classes from automatically being instantiated when no settings for them were loaded.
0.4 (2020-09-25)#
Changed#
π₯ BREAKING: Flip appname and settings_cls args of
load_settings()
.β»οΈ Refactor internals to improve extensibility.
Added#
β¨ Added convenience wrappers for attrs:
settings
is an alias forattr.frozen
option
is an alias forattr.field
secret
is an alias forattr.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)#
Changed#
π¦ Improved packaging
β»οΈ Refactorings
Added#
π· Added code linting and improve CI
0.2 (2020-09-02)#
Changed#
β¨ Make sure env vars can be read
Added#
β Added tests for
load_settings()
0.1 (2020-08-28)#
π Initial PoC
Legend#
|
|