Deprecating a Python package

[srittau (Sebastian Rittau)]

In typeshed, we often deprecate stub packages, mainly because the upstream added type annotations or stubs themselves. While we do add a note about the deprecation to the package’s description (see here for an example), this is very easily overlooked by our users. In other cases, a maintainer might deprecate a Python package, or a package is superseded by a newer package. There is also no way to signal that to the user.

I suggest to add an optional Deprecated header to package metadata. The value would be an explanation how or why a package is deprecated and for possible alternatives. This could be displayed prominently on a package’s PyPI page, but it could also be displayed by tools like pip or poetry when a deprecated package is installed.

While this doesn’t solve all problems (for example, if a package is just abandoned), at least for typeshed users this would be highly beneficial.

Some previous discussion was here: How to deprecate a python package? · Issue #883 · pypa/packaging.python.org · GitHub.

[pradyunsg (Pradyun Gedam)]

Please see this topic:

Adding a mechanism to deprecate a published project

This firmly along the “getting a sense of how people here feel about this”. This would effectively allow the package author to add a message to the package’s PyPI pages as well as add a note during the installation of the package, clearly stating that it is deprecated and here’s the author’s message. The open questions here are: Is this useful? Should this be per-release or project-wide? How would this be presented in the tooling? Index server side (user facing – pypi.org) Index server side…

[jorenham (Joren Hammudoglu)]

I ran into a similar issue with scipy-stubs where there are currently at least 20 modules that are deprecated. These modules almost always only contain re-exports. We still wanted to use @deprecated, and we ended up duplicating hundreds of functions.

Deprecating packages isn’t that different from deprecating a module, since packages are modules too. So we could tackle both problems though some module-level deprecation feature.
But that’s about as far as my idea goes; I don’t have any concrete suggestions at this point