Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog
and this project adheres to Semantic Versioning.
Types of changes are:
- Breaking changes for breaking changes.
- Features for new features or changes in existing functionality.
- Fixes for any bug fixes.
- Deprecated for soon-to-be removed features.
Unreleased
4.3.1 - 2024-09-19
Fixes
settings-doc
now handles nestedBaseSettings
correctly. Make sure to use--class
to point to the top level class.--module
will pick up allBaseSettings
subclasses even if they are nested. (#38 by @mssalvatore)- Use
__future__.annotations
everywhere.
4.3.0 - 2024-09-14
Features
- Correct rendering of default values
IntEnum
,StrEnum
(Python >= 3.11) andStrEnum(str, Enum)
(Python < 3.11). - Rendering of possible values from
Enum
subclasses. - New template global functions:
is_enum
: likeisinstance(field.annotation, EnumMeta)
fix_str_enum_value
: for correct displaying ofStrEnum(str, Enum)
values for Python < 3.11
4.2.0 - 2024-08-13
Features
- Removed dependency on
typer
in favour of plainclick
. It is not as pretty, but it is more stable and easier to maintain.
4.1.0 - 2024-08-13
Features
- Allow rendering documentation from code with
settings_doc.render()
.
4.0.1 - 2024-04-06
Fixes
- Unstable ordering of discovered settings classes (fixes #34).
4.0.0 - 2024-01-31
Breaking changes
- Values used for verbose "possible values" in
json_schema_extra={"possible_values": [...]}
must belist[list[str]]
instead of previouslist[tuple[str, ...]]
. Usingtuple
results in failing type checks. Examples of valid values and their Markdown rendering:- Plain list of values, e.g.
["foo", "bar"]
:
`foo`, `bar`
- List of lists of a single item, e.g.
[["foo"], ["bar"]]
:- `foo` - `bar`
- List of lists of two items, e.g.
[["foo", "explanation of foo"], ["bar", "explanation of bar"]]
:- `foo`: explanation of foo - `bar`: explanation of bar
- Plain list of values, e.g.
Features
- Added rendering of
env_prefix
frompydantic_settings.SettingsConfigDict
(#29 by @dekkers). - Added rendering of
env_nested_delimiter
frompydantic_settings.SettingsConfigDict
.
Fixes
- Dependencies update
3.1.2 - 2023-11-07
Fixes
Markdown template
- Swap
possible_values
andexamples
sections, so thatexamples
are displayed beforepossible_values
. This is the original display order from2.x
.
3.1.1 - 2023-11-07
Fixes
Markdown template
- Remove extra space between "Possible values" and "Examples" sections.
DotEnv template
- Fix wrapping of
possible_values
. - Fix displaying of
possible_values
for tuples. - Remove
None
as a default value.
3.1.0 - 2023-11-06
Features
- Add back verbose
possible_values
removed in3.0.0
. Since arbitrary**extra
is no longer supported inpydantic>=2.0
, thepossible_values
are now passed asjson_schema_extra={"possible_values": [...]}
. If both the field is type ofLiteral
andpossible_values
is specified,possible_values
will be used. It accepts:- Plain list of values, e.g.
["foo", "bar"]
. This will be formatted either as a single line or an unordered list, depending on the length of the string. Example of the resulting Markdown:
`foo`, `bar`
- List of tuples of a single item, e.g.
[("foo", ), ("bar", )]
. This will be formatted as an unordered list. Example of the resulting Markdown:- `foo` - `bar`
- List of tuples of two items, e.g.
[("foo", "explanation of foo"), ("bar", "explanation of bar")]
. Example of the resulting Markdown:- `foo`: explanation of foo - `bar`: explanation of bar
- Plain list of values, e.g.
- Adds more control over
examples
by moving them injson_schema_extra["examples": ...]
. It accepts all the formats thatpossible_values
accepts, plus a plain string, which won't be formatted on the output. If bothexamples
andjson_schema_extra.examples
are present,json_schema_extra.examples
will be used.
3.0.1 - 2023-11-01
Fixes
- Correctly pass field names from
validation_alias
when used.
3.0.0 - 2023-09-19
Breaking changes
Upgrade to pydantic
2.x. If you need to use pydantic 1.x, please use the 2.x
release of settings-doc
. New features will be available only in settings-doc
3.x and later, unless a backport is requested.
The upgrade changes couple of things in the pydantic
library that also need to be reflected in the templates:
-
pydantic.BaseSettings
is nowpydantic_settings.BaseSettings
-
pydantic.Field
no longer accepts arbitrary**kwargs
. This has several implications for the Jinja2 templates:field.field_info
is no longer available. All the attributes have moved to thefield
object itself. For examplefield.field_info.description
is nowfield.description
.json_schema_extra
must be passed as a keyword argument and contain a dictionary. This is then available in the Jinja2 templates asfield.json_schema_extra
instead of the previousfield.field_info.extra
.
-
The type of the field exposed to templates changed from
ModelField
toFieldInfo
. This means that:FieldInfo
no longer contain the name of the settings key. Therefore,fields
has been changed tolist[tuple[str, FieldInfo]]
(instead oflist[ModelField]
), where thestr
value is name of the settings key. To iterate over the fields, usefor env_name, field in fields
instead offor field in fields
.ModelField.type_
has changed toFieldInfo.annotation
.ModelField.required
has changed toFieldInfo.is_required()
.ModelField.default is not None
has changed toFieldInfo.default is not pydantic_core.PydanticUndefined
. A new helper functionhas_default_value(field)
has been added to the templates to make this easier to check.- Check if
FieldInfo
type istyping.Literal
has been abstracted into helper functionis_typing_literal
. The check is different for Python 3.8 and for later versions of Python.
2.1.0 - 2023-09-16
Features
2.0.0 - 2023-06-25
Breaking changes
- Drops Python 3.7 support.
1.0.0 - 2022-12-29
Features
- Add support for Python 3.11.
Fixes
- Dependencies update.
0.8.1 - 2022-02-02
Fixes
- Missing space before headings in Markdown template.
0.8.0 - 2022-01-25
Features
classes
of typeDict[Type[BaseSettings], List[ModelField]]
exposed to templates.
0.7.0 - 2021-11-26
Breaking changes
- Removed support for Python 3.6.
- Removed
tasks
folder, in favour ofdelfino
.
0.6.1 - 2021-11-17
Fixes
- Removed unused dependency on
termcolor
.
0.6.0 - 2021-11-17
Features
- The
--class
option can be specified more than once and is also optional. - Option to use all subclasses of
pydantic.BaseSettings
inside a module with a new--module
option.
0.5.1 - 2021-11-12
Fixes
- Updating document when the content hasn't changed, no longer fails.
0.5.0 - 2021-11-12
Features
- Remove top level heading from the Markdown template.
Fixes
- Description of
generate --templates
.
0.4.0 - 2021-11-11
Breaking changes
- All existing options moved in the
generate
sub-command.
Features
- New sub-command
templates
for copying templates into selected folder.
0.3.0 - 2021-11-10
Breaking changes
- Project renamed to
settings-doc
0.2.0 - 2021-11-09
Features
- Option
--update
to overwrite an existing file. - Option
--between
to update only a portion of a file specified by--update
, between two given marks.
0.1.1 - 2021-11-07
Fixes
Add classifiers to the package.
0.1.0 - 2021-11-05
- Initial release