How do you retire a public function from a Python library without breaking callers?

## The cycle, not the commit Removing a name from a library's public surface is a breaking change, so the work is spread across releases rather than done in one edit. A standard cycle looks like this: 1. **Announce.** In the release where the replacement lands, mark the old name deprecated in its docstring and in the changelog, and say two concrete things: what to use instead, and which release removes it. "Deprecated" with no removal target is an announcement no one can plan against. 2. **Warn at runtime.** The old function keeps working — ideally as a thin shim delegating to the new implementation, so there is one behaviour, not two — and calls `warnings.warn(message, DeprecationWarning, stacklevel=2)`. 3. **Wait.** At least one full minor release, and for a widely-used library considerably longer. The clock people actually experience starts when they upgrade, not when you publish. 4. **Remove.** In a major release, delete the shim and drop the name from `__all__`. The version bump is the signal that the promise has been withdrawn. ## Getting the warning seen This is where most deprecations quietly fail. Python's default warning filters ignore `DeprecationWarning` everywhere except code attributed to `__main__`: ```pycon >>> import warnings >>> warnings.filters[0] ('default', None, <class 'DeprecationWarning'>, '__main__', 0) ``` The rationale is that a `DeprecationWarning` is aimed at *developers*, not at the end user of an application, so it stays quiet in normal runs. Two consequences follow. First, `stacklevel` matters enormously. The default `stacklevel=1` attributes the warning to the line inside your library, which is never `__main__`, so it is filtered out and the message that is printed — when it is printed — points at your source instead of the caller's. `stacklevel=2` attributes it to your caller, which both makes the default filter fire when that caller is the user's script and shows the line the developer has to change. A wrapper an extra frame deep needs `stacklevel=3`. Second, tell downstream teams how to surface warnings deliberately: running their test suite with `-W error::DeprecationWarning`, or setting `PYTHONWARNINGS=error::DeprecationWarning`, turns your notice into a failing build while they still have time to act. Many test runners enable warnings by default, but you cannot rely on that. Use the right category. `DeprecationWarning` targets the developers calling your API. `FutureWarning` is shown by default and is for behaviour changes that will affect *end users* of a running application — a changed default value, a result that will start being computed differently. `PendingDeprecationWarning` is largely historical and is ignored by default too; reaching for it usually means you wanted `DeprecationWarning` a release earlier. ## Where to put the warning Warn from the call, not from the import. A module-level `warnings.warn` fires for everyone who imports the package, including people who never touch the deprecated name, and it cannot be attributed to any useful caller line. If the deprecated thing is a class, warn in `__init__`; if it is a parameter rather than a whole function, warn only when the caller actually passes it, which is easy to detect by giving it a sentinel default and checking for it. Write the message like a work item: the name, the version that deprecated it, the replacement, and the version that removes it. "Deprecated" alone forces every downstream maintainer to go read your source. ## Test it, and count who is affected Assert the warning in your own suite, with `warnings.catch_warnings(record=True)` and `warnings.simplefilter("always")`, or with `unittest.TestCase.assertWarns`. That does two jobs: it proves the shim still warns after refactoring, and it stops the shim's own tests failing when your CI runs with warnings as errors. Keep a test that the shim still returns the right answer too — a deprecated function that silently broke during the grace period is worse than an outright removal. Before you finally delete, get evidence. For an internal library that means grepping the monorepo or querying whatever import telemetry you have; for a public one it means the issue tracker and, if the surface is large, a release that raises the warning to an error behind an opt-in flag. The point of the cycle is that removal is uneventful, and it is uneventful only when you know who is still calling. A closing caution about scope: deprecating your own library's function is the case above. Migrating off an interpreter or standard-library API that is itself going away is a different exercise, driven by someone else's timetable, and it is planned against the Python release schedule rather than your own.