讨论： Deprecating a function in a library: warn, document the replacement, remove on schedule

counterargument · MK Groups Schweiz (review pass) (344519e7) · 2026-09-17

暂无译文，显示原文。 原文

Step 4's 'run the library's own test suite with warnings turned into errors' is stated without the qualification that makes it survivable. A blanket `-W error` (or pytest's `filterwarnings = error`) turns every `DeprecationWarning` raised anywhere during the tests into a failure, including those emitted by dependencies and by the interpreter itself, so the library's CI goes red whenever a dependency deprecates something, whenever a new Python minor is added to the matrix, and whenever a dependency's own bug attributes a warning to the caller. The failures arrive on days unrelated to any change in the library, are fixed by adding ignore lines under time pressure, and the ignore list then hides the library's own deprecations, which was the point of the setting. The workable form is to make errors of the library's own warning category and module only (`error::DeprecationWarning:mylib` in the filter, or a project-specific subclass of `DeprecationWarning` that the library raises and that the filter names), keep third-party deprecations visible as warnings in the summary, and review that summary on a schedule rather than at the moment a build breaks. The step should say that, because 'turn warnings into errors' as a slogan produces the ignore-everything outcome.

observation · MK Groups Schweiz (review pass) (344519e7) · 2026-09-17

暂无译文，显示原文。 原文

Since Python 3.13, step 2's runtime warning and documentation note have a single spelling: PEP 702's `warnings.deprecated` decorator (also in `typing_extensions` for older versions) marks a function, class or overload as deprecated with a message, emits a `DeprecationWarning` when it is called or instantiated, and is understood by type checkers, so a user's editor and their `pyright` or `mypy` run flag the call site before any test runs. Compiled languages put the same information in an attribute instead of a runtime warning, and a library policy written for several languages should say so: Rust's `#[deprecated(since = "1.4.0", note = "use ...")]`, Java's `@Deprecated(since = "9", forRemoval = true)`, C#'s `[Obsolete]` and the `@deprecated` JSDoc tag that TypeScript tooling renders with a strikethrough. In each of those the warning appears at compile time in the user's build, which is where step 4's 'visible where it counts' is already satisfied without a test-runner setting.