`fnmatch.translate` changed in an undocumented way in Python 3.14

[Avasam]

Documentation

Since Python 3.14, fnmatch.translate appends a lowercase z, whilst 3.13 and below used an uppercase Z.
https://docs.python.org/3/library/fnmatch.html#fnmatch.translate makes no mention of this. Searching for fnmatch in https://docs.python.org/3/whatsnew/3.14.html only finds https://docs.python.org/3/whatsnew/3.14.html#fnmatch .

> uvx --python=3.13 python -c "import fnmatch; print(fnmatch.translate('foo*'))"
(?s:foo.*)\Z
> uvx --python=3.14 python -c "import fnmatch; print(fnmatch.translate('foo*'))"
(?s:foo.*)\z

(noticed in pypa/distutils#381)

---

Edit:
After further research, the only mention I could find in "What's new in Python 3.14" is https://docs.python.org/3/whatsnew/3.14.html#re, which only says

Support \z as a synonym for \Z

not that \z is now also used in place of \Z.
https://docs.python.org/3/howto/regex.html#more-metacharacters does mention that

\Z
The same as \z. For compatibility with old Python versions.

Up to you to see if this is worth acting upon. It did confuse me and I had a bit of a hard time finding reference for this change. But I understand if it's considered "implementation detail" and that distutils (setuptools)'s test validating a regex is too niche of a use-case to be worth documenting.

Linked PRs

• gh-140922: Document fnmatch.translate \Z to \z change in 3.14 #144457

[serhiy-storchaka]

This is an implementation detail. It changed several times in the past. It was foo.*$, then foo.*\Z(?ms), then (?s:foo.*)\Z, then (?s:foo.*)\z. There were also changes in other parts of the regular expression.

I understand that some code depends on such details, but they do this on their own risk, and this is not the first time they have had to adapt.

[serhiy-storchaka]

On other hand, we can be nice this time and document this change in "Porting to 3.14".

Yet one option -- restore \Z and add an option to control whether it should be added at all. Users that depends on this implementation detail usually just want to remove \Z, so they will be glad to use the new option. Years later we can change \Z to \z. If users use the new option, this change will not affect them.

\Z and \z will be aliases of one other at least next 5 years. Then \Z will became an error.

[picnixz]

I am not very fond of having an option either. While it would solve this specific problem, it doesn't mean that it can remain consistent with how we would modify the regexp in the future.

I will however document the fact that the exact regular expression being returned by fnmatch.translate is an implementation detail, without explicitly saying what we produce. @serhiy-storchaka WDYT?

[Avasam]

I don't think behaviour changes / options are warranted either. I'm perfectly happy with a documentation update. It's just something I noticed and caught me off-guard despite duefully reading the changelogs whilst upgrading.

[picnixz]

I will (next week):

• Document the change in "Porting to 3.14"
• Explicitly state that the obtained regular expression is an implementation detail. It will do what you want it to do but it won't do it necessarily using the same patterns.
• I will not indicate the change from \Z to \z in the fnmatch translate function itself. Otherwise, whenever we do a change we need to re-document it and it will definitely not be desirable.