[Zikithezikit]

WP-6 for #14 (part of #3). Please do not auto-close #14 from this PR.

The first use of any Kyber512, Kyber768 or Kyber1024 entry point (constructor, from_keys, static encapsulate, static decapsulate) now emits one KyberDeprecationWarning per process. The class is a DeprecationWarning subclass in a new module, python/pykyber/deprecation.py, and is exported from pykyber and listed in all. Importing pykyber warns nothing, ML_KEM* never warns, and python/pykyber/_mlkem.py is untouched. Kyber output is unchanged.

The warning goes through a small decorator applied to the twelve entry points in _kyber.py. "Once per process" is a module-level flag guarded by a lock, so the default per-location registry cannot repeat it and two threads cannot both warn. stacklevel is a named constant (3: the helper, the decorator's wrapper, then the user's call). The message says Kyber (round 3) and ML-KEM are not interoperable, that both sides must switch, that switching changes the shared secret, and links https://github.com/Zikithezikit/pykyber/blob/main/docs/migration.md. Issue #15 needs to create exactly docs/migration.md, since that URL is in the message now.

Commits

• feat: warn once per process on first use of a Kyber class (code and CHANGELOG line)
• test: count Kyber deprecation warnings in subprocesses

Verified (how)

• scripts/check.sh (fetch vectors, cargo fmt --check, cargo clippy --all-targets -- -D warnings, cargo test --locked --no-fail-fast, maturin develop, pytest) passes on each of the two commits, run with git rebase --exec against origin/dev-v2. Final pytest: 2464 passed.
• cargo +stable clippy --all-targets -- -D warnings is clean (run before the rebase; no Rust files changed).
• python/tests/test_kyber_deprecation.py: in child interpreters, three uses of all four entry points on all three classes give exactly one warning under -W always::DeprecationWarning and under -W default; import alone gives none; ML_KEM_512/768/1024 give none; the message carries the required statements and the URL; a call from an imported module prints nothing under the default filters, while a call from main is shown. A parametrized test reads warning.filename for each of the 12 entry points and checks it is the caller's file, so stacklevel is proven for new, the classmethod and the static methods.
• The legacy golden vector tests pass unmodified, and no existing test was edited. The existing Kyber tests now see the warning in-process (pytest shows it in the summary).
• No filterwarnings setting, -W error or PYTHONWARNINGS exists in pyproject.toml, scripts/ or .github/ (git grep), so neither pytest nor CI turns warnings into errors.

Sources checked

• https://docs.python.org/3/library/warnings.html, 2026-10-30: the default filters include default::DeprecationWarning:main followed by ignore::DeprecationWarning, and the stacklevel=2 example for wrapper functions says the warning then refers to the caller. Consistent with the design and the tests.

Believed, not verified

• The CI matrix on Windows and macOS and on Python 3.8 was not run locally. The code uses only functools, threading and warnings, and the test children use subprocess with -c, so I expect no difference.

Out of scope

• README and docs changes, and the migration page itself (Docs: point everything at ML-KEM and write a migration guide #15).
• No version bump.
• Deprecation text in the .pyi stubs and docstrings of the Kyber classes was not touched.

PR checklist

• Spec sections cited in code for new crypto logic (n.a., no crypto code)
• Legacy golden vectors pass unchanged
• No secret-dependent branches, divisions, or indexing (asm checked: n.a.)
• Secret intermediates zeroized on all paths (n.a., no secret handling touched)
• Inputs validated before secret-dependent work (n.a.)
• No new runtime deps; no unsafe; no panics on untrusted input
• No magic numbers: stacklevel and test counts are named constants
• Tests added; fmt/clippy/test/pytest green on every commit (git rebase --exec)
• Review fixes folded into the commits they fix; rebased on current dev-v2
• CHANGELOG updated
• Sources checked: https://docs.python.org/3/library/warnings.html, 2026-10-30, as above

Generated with Claude Code