Python 3.14: PEP-784 compression.zstd

[Rogdham]

Second PR about PEP-784 in stdlib (first PR):

• Add type hints for _zstd
• Add type hints for compression.zstd

---

The CI current failures are due to the use of 3.14 beta1; to address this:

• Make sure tests failing in CI pass with local build of CPython 3.14 (3.14 branch)
• Wait for CPython 3.14 beta2 to be released (this should fix the stubtest errors) - expected May 26th
• Re-run CI to make sure everything is ok after beta2

[Rogdham]

@emmatyping: if you want to give try this out, or simply comment on the use of Mapping[CompressionParameter, int] and Mapping[DecompressionParameter, int] as type hints for the options parameter. Any feedback would be appreciated!

[emmatyping]

Note that I typed the options as Mapping[CompressionParameter, int] / Mapping[DecompressionParameter, int], while a Mapping[int, int] is technically accepted.

I think we should type that it accepts Mapping[int, int] as well. I consider that a supported usage.

[emmatyping]

I think it might be useful to express these in terms of the ZstdCompressor attributes. It will make it easier to understand I think? If you think it makes the signature too busy then I suppose it is fine as is, but I want discourage passing bare integers.

[emmatyping]

(similarly it'd be good to do the same below with the ZstdFile methods)

[Rogdham]

I believe the below is invalid:

Literal[CONTINUE, FLUSH_BLOCK, FLUSH_FRAME]

But maybe I can try to do something like the following:

_ZstdCompressorContinueType = Literal[0]
_ZstdCompressorFlushBlockType = Literal[1]
_ZstdCompressorFlushFrameType = Literal[2]

@final
class ZstdCompressor:
    CONTINUE: Final[_ZstdCompressorContinueType] = 0
    FLUSH_BLOCK: Final[_ZstdCompressorFlushBlockType] = 1
    FLUSH_FRAME: Final[_ZstdCompressorFlushFrameType] = 2
    def compress(self, /, data: ReadableBuffer, mode: _ZstdCompressorContinueType | _ZstdCompressorFlushBlockType | _ZstdCompressorFlushFrameType = ...) -> bytes: ...

Is it what you meant?

[emmatyping]

Couldn't you do CONTINUE | FLUSH_BLOCK | FLUSH_FRAME?

[Rogdham]

I don't think it's possible (playground)

main.py:8: error: Variable "__main__.ZstdCompressor.CONTINUE" is not valid as a type  [valid-type]
main.py:8: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
main.py:8: error: Variable "__main__.ZstdCompressor.FLUSH_BLOCK" is not valid as a type  [valid-type]
main.py:8: error: Variable "__main__.ZstdCompressor.FLUSH_FRAME" is not valid as a type  [valid-type]

I will go ahead and make the changes of defining the Literal once and reusing them afterwards.

[emmatyping]

Okay, I think that is fine then.

[github-actions]

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉