gh-154490: Only keep permission bits of the mode argument in ZipFile.mkdir()

[DevoidSloth]

ZipFile.mkdir() combines the caller-provided mode into the entry's external attributes without clearing the file type bits, so those bits can mark the created entry as something other than a directory:

>>> import io, stat, zipfile
>>> with zipfile.ZipFile(io.BytesIO(), 'w') as zh:
...     zh.mkdir('foo/', 0o107777)
...     print(oct(stat.S_IFMT(zh.getinfo('foo/').external_attr >> 16)))
...
0o140000   # socket, not a directory

This PR sanitizes mode to its permission bits before combining it with S_IFDIR, matching what stat.S_IMODE() does, as suggested in the issue:

zinfo.external_attr = (0o40000 | (mode & 0o7777)) << 16

It also spells the default mode as 0o777 instead of 511 in the signature and documentation, for consistency with os.mkdir() (same value, clearer intent).

Included:

• Regression assertions in test_mkdir covering S_IFREG and S_IFLNK type bits in mode, plus an extractall() round-trip.
• Documentation update for ZipFile.mkdir() with a versionchanged note.
• NEWS entry.

• Issue: Improper sanitization and documentation for ZipFile.mkdir(mode) #154490

[python-cla-bot]

The following commit authors need to sign the Contributor License Agreement:

• 121908598+DevoidSloth@users.noreply.github.com

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34885871 | 📁 Comparing ec37f0d against main (a2a8466)

  🔍 Preview build  

403 files changed · + 9 added · ± 394 modified

+ Added

• builtins/constants.html
• builtins/exceptions.html
• builtins/functions.html
• builtins/index.html
• builtins/stdtypes.html
• builtins/threadsafety.html
• builtins/time-complexity.html
• library/time-complexity.html
• library/tkinter.dialogs.html

± Modified

• glossary.html
• index.html
• license.html
• py-modindex.html
• c-api/arg.html
• c-api/bool.html
• c-api/buffer.html
• c-api/bytearray.html
• c-api/bytes.html
• c-api/capsule.html
• and 384 more...

[danny0838]

LGTM. But I would personally treat this as a bug fix and documentation improvement rather than a behavior change, which means that the detailed doc about behavior change across major versions is not needed and we can backport this to older maintaining Python versions.

The compatibility issue it may introduce should be minimal since there should be no actual requirement to call ZipFile.mkdir with file format bits other than a directory.

Tracing the history, the issue gh-84353 and related PR had a more significant behavior change and actually introduced a regression, while it was still implemented as a bug fix and has been backported.