chore(deps): update poetry #1503

renovate · 2024-12-08T00:15:31Z

This PR contains the following updates:

Package	Change	Type	Update
PyYAML (source)	`6.0.1` -> `6.0.2`	dependencies	patch
dunamai	`1.22.0` -> `1.23.0`	dependencies	minor
importlib-metadata	`6.7.0` -> `6.11.0`	dev	minor
jsonschema (changelog)	`4.17.3` -> `4.23.0`	dependencies	minor
mkdocs (changelog)	`1.5.3` -> `1.6.1`	dev	minor
mkdocs-material (changelog)	`9.2.7` -> `9.5.48`	dev	minor
mkdocs-print-site-plugin	`2.3.6` -> `2.6.0`	dev	minor
mkdocstrings (changelog)	`0.22.0` -> `0.27.0`	dev	minor
packaging	`24.0` -> `24.2`	dependencies	minor
python	`>=3.7,<3.13` -> `>=3.13,<3.14`	dependencies	minor
xmldiff	`2.6.3` -> `2.7.0`	dev	minor

Release Notes

yaml/pyyaml (PyYAML)

`v6.0.2`

Compare Source

What's Changed

Support for Cython 3.x and Python 3.13.

Full Changelog: yaml/pyyaml@6.0.1...6.0.2

mtkennerly/dunamai (dunamai)

`v1.23.0`

Compare Source

Added: {major}, {minor}, and {patch} format placeholders.

python/importlib_metadata (importlib-metadata)

python-jsonschema/jsonschema (jsonschema)

`v4.23.0`

Compare Source

=======

Do not reorder dictionaries (schemas, instances) that are printed as part of validation errors.
Declare support for Py3.13

`v4.22.0`

Compare Source

=======

Improve best_match (and thereby error messages from jsonschema.validate) in cases where there are multiple sibling errors from applying anyOf / allOf -- i.e. when multiple elements of a JSON array have errors, we now do prefer showing errors from earlier elements rather than simply showing an error for the full array (#1250).
(Micro-)optimize equality checks when comparing for JSON Schema equality by first checking for object identity, as == would.

`v4.21.1`

Compare Source

=======

Slightly speed up the contains keyword by removing some unnecessary validator (re-)creation.

`v4.21.0`

Compare Source

=======

Fix the behavior of enum in the presence of 0 or 1 to properly consider True and False unequal (#1208).
Special case the error message for {min,max}{Items,Length,Properties} when they're checking for emptiness rather than true length.

`v4.20.0`

Compare Source

=======

Properly consider items (and properties) to be evaluated by unevaluatedItems (resp. unevaluatedProperties) when behind a $dynamicRef as specified by the 2020 and 2019 specifications.
jsonschema.exceptions.ErrorTree.__setitem__ is now deprecated.
More broadly, in general users of jsonschema should never be mutating objects owned by the library.

`v4.19.2`

Compare Source

=======

Fix the error message for additional items when used with heterogeneous arrays.
Don't leak the additionalItems keyword into JSON Schema draft 2020-12, where it was replaced by items.

`v4.19.1`

Compare Source

=======

Single label hostnames are now properly considered valid according to the hostname format.
This is the behavior specified by the relevant RFC (1123).
IDN hostname behavior was already correct.

`v4.19.0`

Compare Source

=======

Importing the Validator protocol directly from the package root is deprecated.
Import it from jsonschema.protocols.Validator instead.
Automatic retrieval of remote references (which is still deprecated) now properly succeeds even if the retrieved resource does not declare which version of JSON Schema it uses.
Such resources are assumed to be 2020-12 schemas.
This more closely matches the pre-referencing library behavior.

`v4.18.6`

Compare Source

=======

Set a jsonschema specific user agent when automatically retrieving remote references (which is deprecated).

`v4.18.5`

Compare Source

=======

Declare support for Py3.12

`v4.18.4`

Compare Source

=======

Improve the hashability of wrapped referencing exceptions when they contain hashable data.

`v4.18.3`

Compare Source

=======

Properly preserve applicable_validators in extended validators.
Specifically, validators extending early drafts where siblings of $ref were ignored will properly ignore siblings in the extended validator.

`v4.18.2`

Compare Source

=======

Fix an additional regression with the deprecated jsonschema.RefResolver and pointer resolution.

`v4.18.1`

Compare Source

=======

Fix a regression with jsonschema.RefResolver based resolution when used in combination with a custom validation dialect (via jsonschema.validators.create).

`v4.18.0`

Compare Source

=======

This release majorly rehauls the way in which JSON Schema reference resolution is configured.
It does so in a way that should be backwards compatible, preserving old behavior whilst emitting deprecation warnings.

jsonschema.RefResolver is now deprecated in favor of the new referencing library <https://github.com/python-jsonschema/referencing/>_.
referencing will begin in beta, but already is more compliant than the existing $ref support.
This change is a culmination of a meaningful chunk of work to make $ref resolution more flexible and more correct.
Backwards compatibility should be preserved for existing code which uses RefResolver, though doing so is again now deprecated, and all such use cases should be doable using the new APIs.
Please file issues on the referencing tracker if there is functionality missing from it, or here on the jsonschema issue tracker if you have issues with existing code not functioning the same, or with figuring out how to change it to use referencing.
In particular, this referencing change includes a change concerning automatic retrieval of remote references (retrieving http://foo/bar automatically within a schema).
This behavior has always been a potential security risk and counter to the recommendations of the JSON Schema specifications; it has survived this long essentially only for backwards compatibility reasons, and now explicitly produces warnings.
The referencing library itself will not automatically retrieve references if you interact directly with it, so the deprecated behavior is only triggered if you fully rely on the default $ref resolution behavior and also include remote references in your schema, which will still be retrieved during the deprecation period (after which they will become an error).
Support for Python 3.7 has been dropped, as it is nearing end-of-life.
This should not be a "visible" change in the sense that requires-python has been updated, so users using 3.7 should still receive v4.17.3 when installing the library.
On draft 2019-09, unevaluatedItems now properly does not consider items to be evaluated by an additionalItems schema if items is missing from the schema, as the specification says in this case that additionalItems must be completely ignored.
Fix the date format checker on Python 3.11 (when format assertion behavior is enabled), where it was too liberal (#1076).
Speed up validation of unevaluatedProperties (#1075).

Deprecations

jsonschema.RefResolver -- see above for details on the replacement
jsonschema.RefResolutionError -- see above for details on the replacement
relying on automatic resolution of remote references -- see above for details on the replacement
importing jsonschema.ErrorTree -- instead import it via jsonschema.exceptions.ErrorTree
importing jsonschema.FormatError -- instead import it via jsonschema.exceptions.FormatError

mkdocs/mkdocs (mkdocs)

`v1.6.1`

Compare Source

Version 1.6.1 (Friday 30th August, 2024)

Fixed

Fix build error when environment variable SOURCE_DATE_EPOCH=0 is set. #3795
Fix build error when mkdocs_theme.yml config is empty. #3700
Support python -W and PYTHONWARNINGS instead of overriding the configuration. #3809
Support running with Docker under strict mode, by removing 0.0.0.0 dev server warning. #3784
Drop unnecessary changefreq from sitemap.xml. #3629
Fix JavaScript console error when closing menu dropdown. #3774
Fix JavaScript console error that occur on repeated clicks. #3730
Fix JavaScript console error that can occur on dropdown selections. #3694

Added

Added translations for Dutch. #3804
Added and updated translations for Chinese (Simplified). #3684

`v1.6.0`

Compare Source

Local preview

mkdocs serve no longer locks up the browser when more than 5 tabs are open. This is achieved by closing the polling connection whenever a tab becomes inactive. Background tabs will no longer auto-reload either - that will instead happen as soon the tab is opened again. Context: #3391
New flag serve --open to open the site in a browser.
After the first build is finished, this flag will cause the default OS Web browser to be opened at the home page of the local site.
Context: #3500

Drafts

[!warning]
Changed from version 1.5:

The exclude_docs config was split up into two separate concepts.

The exclude_docs config no longer has any special behavior for mkdocs serve - it now always completely excludes the listed documents from the site.

If you wish to use the "drafts" functionality like the exclude_docs key used to do in MkDocs 1.5, please switch to the new config key draft_docs.

See documentation.

Other changes:

Reduce warning levels when a "draft" page has a link to a non-existent file. Context: #3449

Update to deduction of page titles

MkDocs 1.5 had a change in behavior in deducing the page titles from the first heading. Unfortunately this could cause unescaped HTML tags or entities to appear in edge cases.

Now tags are always fully sanitized from the title. Though it still remains the case that Page.title is expected to contain HTML entities and is passed directly to the themes.

Images (notably, emojis in some extensions) get preserved in the title only through their alt attribute's value.

Context: #3564, #3578

Themes

Built-in themes now also support Polish language (#3613)

"readthedocs" theme

Fix: "readthedocs" theme can now correctly handle deeply nested nav configurations (over 2 levels deep), without confusedly expanding all sections and jumping around vertically. (#3464)
Fix: "readthedocs" theme now shows a link to the repository (with a generic logo) even when isn't one of the 3 known hosters. (#3435)
"readthedocs" theme now also has translation for the word "theme" in the footer that mistakenly always remained in English. (#3613, #3625)

"mkdocs" theme

The "mkdocs" theme got a big update to a newer version of Bootstrap, meaning a slight overhaul of styles. Colors (most notably of admonitions) have much better contrast.

The "mkdocs" theme now has support for dark mode - both automatic (based on the OS/browser setting) and with a manual toggle. Both of these options are not enabled by default and need to be configured explicitly.
See color_mode, user_color_mode_toggle in documentation.

[!warning]
Possible breaking change:

jQuery is no longer included into the "mkdocs" theme. If you were relying on it in your scripts, you will need to separately add it first (into mkdocs.yml) as an extra script:
extra_javascript:
  - https://code.jquery.com/jquery-3.7.1.min.js
Or even better if the script file is copied and included from your docs dir.

Context: #3493, #3649

Configuration

New "`enabled`" setting for all plugins

You may have seen some plugins take up the convention of having a setting enabled: false (or usually controlled through an environment variable) to make the plugin do nothing.

Now every plugin has this setting. Plugins can still choose to implement this config themselves and decide how it behaves (and unless they drop older versions of MkDocs, they still should for now), but now there's always a fallback for every plugin.

See documentation. Context: #3395

Validation

Validation of hyperlinks between pages

Absolute links

Historically, within Markdown, MkDocs only recognized relative links that lead to another physical *.md document (or media file). This is a good convention to follow because then the source pages are also freely browsable without MkDocs, for example on GitHub. Whereas absolute links were left unmodified (making them often not work as expected or, more recently, warned against).

If you dislike having to always use relative links, now you can opt into absolute links and have them work correctly.

If you set the setting validation.links.absolute_links to the new value relative_to_docs, all Markdown links starting with / will be understood as being relative to the docs_dir root. The links will then be validated for correctness according to all the other rules that were already working for relative links in prior versions of MkDocs. For the HTML output, these links will still be turned relative so that the site still works reliably.

So, now any document (e.g. "dir1/foo.md") can link to the document "dir2/bar.md" as [link](/dir2/bar.md), in addition to the previously only correct way [link](../dir2/bar.md).

You have to enable the setting, though. The default is still to just skip any processing of such links.

See documentation. Context: #3485

Absolute links within nav

Absolute links within the nav: config were also always skipped. It is now possible to also validate them in the same way with validation.nav.absolute_links. Though it makes a bit less sense because then the syntax is simply redundant with the syntax that comes without the leading slash.

Anchors

There is a new config setting that is recommended to enable warnings for:

validation:
  anchors: warn

Example of a warning that this can produce:

WARNING -  Doc file 'foo/example.md' contains a link '../bar.md#some-heading', but the doc 'foo/bar.md' does not contain an anchor '#some-heading'.

Any of the below methods of declaring an anchor will be detected by MkDocs:

#### Heading producing an anchor
#### Another heading {#custom-anchor-for-heading-using-attr-list}

<a id="raw-anchor"></a>

[](){#markdown-anchor-using-attr-list}

Plugins and extensions that insert anchors, in order to be compatible with this, need to be developed as treeprocessors that insert etree elements as their mode of operation, rather than raw HTML which is undetectable for this purpose.

If you as a user are dealing with falsely reported missing anchors and there's no way to resolve this, you can choose to disable these messages by setting this option to ignore (and they are at INFO level by default anyway).

See documentation. Context: #3463

Other changes:

When the nav config is not specified at all, the not_in_nav setting (originally added in 1.5.0) gains an additional behavior: documents covered by not_in_nav will not be part of the automatically deduced navigation. Context: #3443
Fix: the !relative YAML tag for markdown_extensions (originally added in 1.5.0) - it was broken in many typical use cases.

See documentation. Context: #3466
Config validation now exits on first error, to avoid showing bizarre secondary errors. Context: #3437
MkDocs used to shorten error messages for unexpected errors such as "file not found", but that is no longer the case, the full error message and stack trace will be possible to see (unless the error has a proper handler, of course). Context: #3445

Upgrades for plugin developers

Plugins can add multiple handlers for the same event type, at multiple priorities

See mkdocs.plugins.CombinedEvent in documentation. Context: #3448

Enabling true generated files and expanding the `File` API

See documentation.

There is a new pair of attributes File.content_string that becomes the official API for obtaining the content of a file and is used by MkDocs itself.

This replaces the old approach where one had to manually read the file located at File.abs_src_path, although that is still the primary action that these new attributes do under the hood.
The content of a File can be backed by a string and no longer has to be a real existing file at abs_src_path.

It is possible to set the attribute File.content_string or File.content_bytes and it will take precedence over abs_src_path.

Further, abs_src_path is no longer guaranteed to be present and can be None instead. MkDocs itself still uses physical files in all cases, but eventually plugins will appear that don't populate this attribute.
There is a new constructor File.generated() that should be used by plugins instead of the File() constructor. It is much more convenient because one doesn't need to manually look up the values such as docs_dir and use_directory_urls. Its signature is one of:
```
f = File.generated(config: MkDocsConfig, src_uri: str, content: str | bytes)
f = File.generated(config: MkDocsConfig, src_uri: str, abs_src_path: str)
```
This way, it is now extremely easy to add a virtual file even from a hook:
```
def on_files(files: Files, config: MkDocsConfig):
    files.append(File.generated(config, 'fake/path.md', content="Hello, world!"))
```
For large content it is still best to use physical files, but one no longer needs to manipulate the path by providing a fake unused docs_dir.
There is a new attribute File.generated_by that arose by convention - for generated files it should be set to the name of the plugin (the key in the plugins: collection) that produced this file. This attribute is populated automatically when using the File.generated() constructor.
It is possible to set the edit_uri attribute of a File, for example from a plugin or hook, to make it different from the default (equal to src_uri), and this will be reflected in the edit link of the document. This can be useful because some pages aren't backed by a real file and are instead created dynamically from some other source file or script. So a hook could set the edit_uri to that source file or script accordingly.
The File object now stores its original src_dir, dest_dir, use_directory_urls values as attributes.
Fields of File are computed on demand but cached. Only the three above attributes are primary ones, and partly also dest_uri. This way, it is possible to, for example, overwrite dest_uri of a File, and abs_dest_path will be calculated based on it. However you need to clear the attribute first using del f.abs_dest_path, because the values are cached.
File instances are now hashable (can be used as keys of a dict). Two files can no longer be considered "equal" unless it's the exact same instance of File.

Other changes:

The internal storage of File objects inside a Files object has been reworked, so any plugins that choose to access Files._files will get a deprecation warning.
The order of File objects inside a Files collection is no longer significant when automatically inferring the nav. They get forcibly sorted according to the default alphabetic order.

Context: #3451, #3463

Hooks and debugging

Hook files can now import adjacent *.py files using the import statement. Previously this was possible to achieve only through a sys.path workaround. See the new mention in documentation. Context: #3568
Verbose -v log shows the sequence of plugin events in more detail - shows each invoked plugin one by one, not only the event type. Context: #3444

Deprecations

Python 3.7 is no longer supported, Python 3.12 is officially supported. Context: #3429
The theme config file mkdocs_theme.yml no longer executes YAML tags. Context: #3465
The plugin event on_page_read_source is soft-deprecated because there is always a better alternative to it (see the new File API or just on_page_markdown, depending on the desired interaction).

When multiple plugins/hooks apply this event handler, they trample over each other, so now there is a warning in that case.

See documentation. Context: #3503

API deprecations

It is no longer allowed to set File.page to a type other than Page or a subclass thereof. Context: #3443 - following the deprecation in version 1.5.3 and #3381.
Theme._vars is deprecated - use theme['foo'] instead of theme._vars['foo']
utils: modified_time(), get_html_path(), get_url_path(), is_html_file(), is_template_file() are removed. path_to_url() is deprecated.
LiveReloadServer.watch() no longer accepts a custom callback.

Context: #3429

Misc

The sitemap.xml.gz file is slightly more reproducible and no longer changes on every build, but instead only once per day (upon a date change). Context: #3460

Other small improvements; see commit log.

squidfunk/mkdocs-material (mkdocs-material)