This release documents deprecations with a Deprecated: admonition, generated automatically from the typing_extensions.deprecated decorator wherever there is one. It also bumps the minimum supported dependencies for protobuf, pytest and setuptools to exclude vulnerable versions.
- The
mypynox session now runsmypyonce, without paths, so it checks the paths listed in thefilesoption of thetool.mypysection inpyproject.toml, and it fails if that option is not set. Before, it ranmypytwice: once for the configuredpackagesand once for the existing development paths (tests,docs, etc.). The migration script setsfilesfor you; projects not using it need to replacepackageswithmypy_pathandfilesthemselves, see themypysection of thefrequenz.repo.configdocumentation for an example. - The
mypynox session now also warns about Python files in the repository (tracked by git, or untracked but not ignored) thatmypydoesn't check, meaning not covered byfilesnor matched byexclude. In CI (when theCIenvironment variable is set to anything but an empty string,0,false,nooroff, case-insensitive) this is an error instead, unlessConfig.mypy_unchecked_files_error_in_ciis set toFalse. Add those files tofilesif they should be type-checked, or toexcludeif not. - The
apiextra now requiresprotobuf >= 7.35.1, < 9andsetuptools >= 83.0.0, < 85. Theextra-lint-examplesextra now requirespytest >= 9.0.3, < 10. - Code examples in docstrings whose opening fence has extra options after the language, like
python show_lines="2:",python title="example.py"orpython hl_lines="3", are now linted. They were silently skipped before, so projects using them (for example withpymdownx-superfence-filter-lines) might see newpylinterrors inpytestafter upgrading, which need to be fixed in the examples.
All upgrading should be done via the migration script or regenerating the templates.
curl -sSLf https://raw.githubusercontent.com/frequenz-floss/frequenz-repo-config-python/<tag>/cookiecutter/migrate.py | python3 -IBut you might still need to adapt your code:
-
Deprecations are now documented with a
Deprecated:admonition, neverWarning: Deprecated, and never with a custom title, since a title replaces the word "Deprecated" in the rendered output. The migration script rewrites a plainWarning: DeprecatedintoDeprecated:on its own, and reports the rest:- Symbols carrying both a
deprecateddecorator and a hand-written admonition, which would now be documented twice. Delete the hand-written one, moving into the decorator message anything it says that the message does not. - Variants such as
Note: Deprecated,Warning: Deprecationor a custom title, where only a human can tell what was meant.
- Symbols carrying both a
-
Tests using a symbol deprecated by the project itself now fail. Stop using the deprecated symbol, or, when the use is deliberate, wrap it in
pytest.deprecated_call()(which is how a deprecation should be tested anyway) or mark the test with@pytest.mark.filterwarnings("once::DeprecationWarning"). -
The migration script can't add the filter if warnings are still configured through
addoptsinstead offilterwarnings, or if the project's Python package can't be determined. It says so and prints what to add by hand. -
mypynow checks every package in the source directory, not only the one listed inpackages, so it might report errors in code that was never type-checked before. The migration script only adds well-known locations tofiles(the source directory,tests/pytests,examples,benchmarks,docsandnoxfile.py), and reports any other Python files as a manual step, so you can decide whether to add them tofilesorexclude. This includes paths yournoxfile.pyadds to the checked paths.
-
mkdocstrings relative cross-references are now enabled, so docstrings can refer to objects relative to the one being documented, like
[.member]or[..sibling], instead of using the full path. The migration script enables them in existing projects too, unlessmkdocs.ymlalready setsrelative_crossrefs, in which case it is left alone. -
mypyis now configured withmypy_pathandfilesinstead ofpackages, so a plainmypyrun checks the whole source directory plus tests, docs andnoxfile.py, the same as the nox session. -
Generated projects now render deprecations as a
Deprecated:admonition, styled like a warning but with its own colour and a grave stone icon.The
griffe-warnings-deprecatedextension builds that admonition from the message of atyping_extensions.deprecateddecorator, so the text is written once and serves as both the runtime warning and the documentation. Where no decorator can reach, which is module-level aliases, individual function arguments, enum members and whole modules, the same admonition is written by hand. -
Generated projects now treat their own deprecations as errors in
pytest, while deprecations coming from dependencies stay warnings, as they can't always be fixed right away:[tool.pytest.ini_options] filterwarnings = [ "error", "once::DeprecationWarning", "once::PendingDeprecationWarning", 'error:.*my\.own\.package\.[\w\.]+ (is|was) deprecated:DeprecationWarning', ]
This is a heuristic: it only catches messages mentioning the fully qualified name of the deprecated symbol, as in
"my.own.package.mod.OldThing is deprecated since v1.2.0. Use [my.own.package.mod.NewThing][] instead.", which is the style prescribed by the deprecations guide.The entry goes after the
once::ones, as later filters take precedence, and before any project-specific filter, which can then still override it.
- The
pytestexamples linter (frequenz.repo.config.pytest.examples) no longer silently skips code blocks with extra options after the language in the opening fence, like```python show_lines="2:",```python title="example.py"or```{.python hl_lines="3"}. Only blocks whose fence was exactly the language were linted, so examples using options (including the hidden lines of the ones usingshow_lines) were never checked, while CI stayed green (#652).
- The mkdocstrings
pathskey inmkdocs.ymlis back underhandlers.python, where it belongs. Since v0.14.0 the template generated it directly underhandlers, where mkdocstrings reads it as a handler name and aborts the build withModuleNotFoundError: No module named 'mkdocstrings_handlers.paths', so newly generated projects could not build their documentation. Existing projects are unaffected, as previous migration steps always moved the key to the correct place. The migration script now fixes both this location and the olderhandlers.python.optionsone. - The instructions printed after generating a project, and the "Start a new project" guide, now use
v0.0-devas the initialmikeversion instead ofv0.1-dev. Av0.x.xbranch with no releases is published by the CI asv0.0-dev, so following the old instructions left a stalev0.1-devversion holding thelatestalias.