Rework ConfigOption schemas as class-based #2962
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
oprypin
force-pushed
the
meta
branch
3 times, most recently
from
6a0dca0
to
579cf17
Compare
oprypin
force-pushed
the
meta
branch
3 times, most recently
from
f4c4cf1
to
19fd8f5
Compare
oprypin
force-pushed
the
meta
branch
2 times, most recently
from
39f30fd
to
8557a68
Compare
This is NOT a breaking change, the old style keeps working. Now developers can make a subclass of Config, declare the schema of the config as fields of the class, and instances of this class will hold the processed config. This better represents the relationship between what a config definition and a config instance is, now you think of configs definitions as classes and parsed configs as instances. We also can write these fields as descriptors and enable safe attribute-based access. Static analysis will be able to see when a missing fields is accessed. And in followup changes I plan to add type annotations which will make even type checking fully sound.
when subclassing BasePlugin[FooConfig]
They are validated by default
The old-style tests are intentionally kept at config_options_legacy_tests.py
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is NOT a breaking change, the old style keeps working.
Now plugin developers can make a subclass of
Config, declare the schema of the config as fields of the class, and instances of this class will hold the processed config.This better represents the relationship between what a config definition and a config instance is, now you think of config definitions as classes and parsed configs as instances.
We write these fields as descriptors and enable safe attribute-based access. Static analysis will be able to see when a missing field is accessed and, thanks to the Generic type annotations, even if the variable is of a mismatched type!
MkDocs' own config also becomes a subclass of
Config, rather than just a sequence of field definitions. Then thisMkDocsConfigis used as a more precise type restriction in many places like plugin events.In the new style, fields become required by default, but can be wrapped into
config_options.Optional. Validation ofSubConfigis enabled by default as well.Configsubclasses can now also be passed toSubConfigandConfigItems, rather than just a sequence of field definitions. This also recursively enables type safety.