Release Targets and Upgrades

### The filter list is the mechanism, not the warning class `DeprecationWarning` is an ordinary exception class, but a deprecation is normally not raised. `warnings.warn(message, DeprecationWarning)` hands the category to the warnings machinery, which consults `warnings.filters` — an ordered list of tuples of the form `(action, message_regex, category, module_regex, lineno)`. Python walks that list top to bottom and the **first** entry that matches decides the action: `error` raises the warning as an exception, `default` prints it once per unique source location, `always` prints every occurrence, `module` prints once per module, `once` prints once per process, and `ignore` drops it silently. ### What a stock CPython 3.14 ships with The startup filter list is, in order, effectively: ``` default::DeprecationWarning:__main__ ignore::DeprecationWarning ignore::PendingDeprecationWarning ignore::ImportWarning ignore::ResourceWarning ``` Read top-down: a `DeprecationWarning` attributed to the module named `__main__` prints once per location; every other `DeprecationWarning` matches the second entry and is dropped before it reaches stderr. `UserWarning`, `FutureWarning`, `SyntaxWarning` and `RuntimeWarning` match no ignore entry, fall off the end of the list, and are shown. ### Why `__main__` is special The split is about audience. A `DeprecationWarning` is addressed to *the author of the calling code*, not to whoever runs the program: it says "this call site needs changing before the next release". A `FutureWarning` is the mirror image — it is aimed at end users, which is why it is visible by default. Deprecations were made silent everywhere in the 2.7/3.2 era because end users were being flooded with warnings about libraries they did not write and could not fix. That over-corrected: the people who most needed to see them — someone iterating on a script or working in the REPL — stopped seeing them too. PEP 565, in Python 3.7, restored visibility for `__main__` only, which is the compromise still in force on 3.14. ### "Attributed to" is not "raised in" The module a filter matches against is the `__name__` of the frame the warning is *blamed on*, which `warnings.warn`'s `stacklevel` argument selects. A well-written deprecation inside a library uses `stacklevel=2` so that the warning points at the caller — your file, your line number — rather than at the library's own internals. That is what makes the `__main__` rule useful: a deprecated helper called directly from a script is attributed to `__main__` and therefore printed, while the same helper called two packages deep is attributed to that package and stays quiet. It is also the reason module-scoped filters behave surprisingly: filtering "that library's deprecations" often does not work, because with a correct `stacklevel` the warning is attributed to *your* module. ### The four levers that turn them on * **Command line.** `python -W default::DeprecationWarning app.py`. The spec is `action:message:category:module:lineno`, and empty fields mean "match anything". * **Environment.** `PYTHONWARNINGS=default::DeprecationWarning` takes the same comma-separated specs, and — unlike `-W` — is inherited by child processes. * **Development mode.** `python -X dev` (or `PYTHONDEVMODE=1`) installs `default` filters and turns on a batch of other runtime checks; it is the one-flag answer for local work. * **In code.** `warnings.simplefilter("default", DeprecationWarning)` inserts a match-everything-of-this-category filter at the head of the list; `warnings.filterwarnings(...)` does the same with message and module regexes; `warnings.resetwarnings()` clears the list entirely. Test runners matter here too: `unittest` installs `default` filters for the code under test unless you passed `-W` yourself, so warnings that are invisible in production often do appear in a test run. ### Once per location, and why warnings seem to vanish Even with the `default` action, a given warning prints once per unique `(message, category, module, line number)` — a deprecated call inside a loop yields one line, not a million. Python remembers what it has already shown in a per-module registry, which is why a warning that fired in one part of a long-running process is silent later. Mutating the filter list invalidates those registries, so calling `simplefilter` mid-run can make previously-suppressed warnings reappear. Use the `always` action when you actually want every occurrence, for example when counting call sites before a migration. ### The consequence to state in an interview Because the default is silence, a deprecation that CPython or a dependency has been announcing for two releases produces *no signal at all* in a normal run, and the first thing the team sees is an `AttributeError` or a `ModuleNotFoundError` on the upgrade. Surfacing them is therefore not a nicety: it is how a scheduled removal turns into a planned migration instead of an incident.