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 (client facing – simple API’s HTML)
    • Client side (user facing – pip’s output)

(I’ll put my own answers in a follow up post)


NPM has this:

So does Nuget:

10 Likes

I think it is. I can imagine this being useful to wean people off of unsupported projects or help with migrations across project names.

Both? I can see usecases for both. Like, marking versions that are (going to be) unsupported as deprecated is a valid strategy IMO. And, personally, I’d like to use this for pushing users off of pep517 to pyproject-hooks, when the time comes.

On pypi.org:

  • a project-wide deprecation would be presented as “This package has been deprecated” on all non-management project pages
  • a version-specific deprecation would be presented as “This version has been deprecated” on the version-specific page.
  • If both are provided, they’re both presented.

This would be somewhat similar to how npm does things:

In the simple index API, this can be an additional data-deprecated attributes on the body tag and a tags. The body tag refers to the entire project and the specific files refer to that specific distribution (we’d couple this to an entire version at a time though, like data-yanked).

On pip’s end, it’ll present a warning like it does for yanked projects; noting what the problem is and printing the message. There is no diffference in behaviour to avoid installing a deprecated version/package.

3 Likes

I think so - as you say, it would be useful to push people away from abandoned projects towards things that are more likely to be compatible with the current/future state of the world (Python itself, other libraries, servers, etc.).

I would make it somewhat less big and red than the npm example you show. People might be perfectly happy using a stable package with no further updates if it does what they need, and these may even be safer bets than packages where the author has moved on without setting the ‘deprecated’ flag. :person_shrugging:

These packages should probably also be demoted in search listings, though for similar reasons I wouldn’t hide them altogether.

Should it make a difference whether you’re explicitly requesting something deprecated (pip install deprecated-thing) or getting it as a dependency of something else? I don’t particularly have an answer, and maybe the distinction would be hard to implement anyway.

I imagine pip will want an option to suppress such warnings. Should it also have an option to error if any package it would install (or any directly specified package?) is deprecated?

Another way we could go about this would be to allow publishing advisories to pypa/advisory-database and allow auditing tooling to report on deprecated projects in a similar way to vulnerabilities.

This is what the Rust community does for deprecated or unmaintained projects, for example: advisory-db/RUSTSEC-2018-0017.md at c71cfec8c3fe313c9445a9ab0ae9b7faedda850a · rustsec/advisory-db · GitHub

Another open question that’s probably worth discussing: what’s the difference between this and yanking?

3 Likes

Unlike yanking, this won’t affect the selection logic; instead only serving as a mechanism to present messages that the project is deprecated.

I don’t think there should be any difference. I can see why this question comes up, but I don’t see any reason to not print a message in either case.

IIRC, it should be fairly straightforward to figure out if something was directly requested on pip’s end, so implementation complexity isn’t a concern here.

Thoth, the public cloud resolver discussed in Thoth - an enhanced server-side resolution offered to the Python community, runs background data aggregation to collect similar information about Python packages (see handlers available). The pipeline collects information about GitHub repositories and links them to projects. If the project repository is archived, the resolver prints out a warning when such packages are resolved.

We maintain a database similar to pypa/advisory-db which collects “prescriptions”. The “archived project” knowledge is recorded there - see thoth-station/prescriptions. The prescription database is consumed by the resolver. If you would be interested, feel free to consume data we have about packages - we can combine efforts. Also, if such deprecate mechanism would be available on PyPI, we would like to consume it. It could be valuable to users.

I’d really rather we didn’t tie this to vulnerability reporting. Yes, I know that when you’re building critical network infrastructure, or payment processors, or the like, “author doesn’t support this any more” is a big red flag. But for more casual uses, it may not matter so much.

If a deprecation notice gets linked to the idea that a project has security vulnerabilities, projects will get pressure to move away from depending on perfectly good, but abandoned, libraries, they will get marked as unreliable themselves because they depend on deprecated libraries, and ultimately project authors will be less inclined to mark their projects as deprecated as a result.

To put it another way, “I no longer support this project” is valuable information for consumers of the code, and it’s different from “this project has security vulnerabilities”. The two concepts should be kept separate, as merging them loses useful information.

4 Likes

Just a note that while the advisory database currently only includes vulnerabilities, it’s intended to be a repository for publish advisories of any nature. For example, we’re planning to start publishing advisories for malware/typosquats/dependency confusion projects as well. Advisories for deprecated / abandoned projects would be easy for tooling and users to distinguish from vulnerabilities.

Isn’t this roughly what we’re trying to achieve here?

I don’t think so. I thought we were trying to give projects information on which basis they could make their own decisions. Security advisories, like it or not[1], tend to push people to take action rather than just providing information.

If I’ve misunderstood and the intention here is to actively push people away from deprecated packages (as opposed to letting them make their own decision), then I’ll have to rethink my view. I’m not necessarily against the idea, but it’s different, and in particular it affects my view on whether showing deprecation notices for dependencies is a good idea.

Edit: The notice @pradyunsg included “This package is no longer supported. Use at your own risk” is a perfect example. “Use at your own risk” isn’t pushing anyone away, it’s just making it clear that you can’t expect support. A consumer may be perfectly fine with that, and encouraging consumers of that consumer to push the first consumer to drop the dependency is (IMO) counter-productive.


  1. Personally, I’m fine with the fact that they do, but IMO that’s why they are different from deprecation notes. ↩︎

I think @pf_moore’s argument is relevant: if you see these notices for dependencies of the things you want, that will pressure package maintainers to replace deprecated dependencies, even if they are otherwise perfectly happy to continue using them. Is such pressure desirable? I’m inclined to agree with Paul that it’s not.

People certainly might want to identify any deprecated projects in their dependency tree, and there should be a way for them to do so. But I’m not sure that showing that information on every installation is a net gain. Especially because projects can be abandoned without being marked deprecated, so you can’t assume something without this deprecation flag is safe or reliable.

I actually find that wording rather silly. You use any open source package at your own risk, and the popular open source licenses are careful to say so (in block caps!). And you shouldn’t expect that any open source author will give you support, unless you have arranged a support contract with them.

I know what they’re getting at, and that’s useful information. But I think it would be clearer to say something like “This package is unlikely to get any further development or releases”.

1 Like

Another question about pip: if an entire project is deprecated, should it show the warning when installing a specified version (e.g. pip install pytoml==0.1.18)? It would seem odd to warn that a package won’t be updated if you’re opting out of updates anyway.

Of course you could have some other tool which would automatically update a requirements.txt file on new releases (e.g. dependabot on Github). But in that case, maybe it should be the tool that would handle updates that (somehow) tells you not to expect any? :thinking:

This would be extremely useful when old versions become unsupported or actively discouraged due to vulnerabilities.

I think the case for this on a package level is less strong since I can always release a new version with a prominent message in the readme. However messages during install would be useful, so I can see the case for both.

They can use the same mechanism though. They’re both “advisories” – one is an informational advisory (deprecations) and the other is a security advisory.

They will have different metadata associated with them, and can (and should!) be presented / handled differently in the final output tho. I don’t think we should conflate the two – an “advisory” is just a blurb of text with metadata attached. What the blurb is for is something we can communicate through the associated metadata.

I’d be fine with deprecation advisories being added to the advisory-db and making that the mechanism to query things. My only concern with that is: it should be possible to publish these from the manage page on PyPI directly by only pressing buttons/filling fields on pypi.org, should be presented on PyPI and should be accessible via APIs provided by PyPI.

I don’t, even though I wouldn’t publish anything like that for a project I maintain. :slight_smile:

There’s various reasons when even that is useful though:

  • PyPI doesn’t just have community-maintained open source projects.
  • It is also a useful indicator that the “community support” for something is definitely not a thing anymore, even for projects that rely on that.
  • The package authors may have support obligations, like when a project is sponsored in some form.

I think so. If I deprecated pkgA in favour of pkgB, I would want all users of pkgA to see that I’ve deprecated it in favour of pkgB. If they don’t mind, sure, we can give them knobs to suppress that. However, I think this is most beneficial when it is shown to all users by default.

The reasons for deprecation can range from “I don’t want to support this anymore” to “This is an actively dangerous footgun”. In both these extremes though, I think informing users is beneficial; even those who have proactive pins should see these by default.

Having advisories go from PyPI->pypa/advisory-database is something I’m generally interested in providing (e.g. for publishing advisories about malware takedowns) so it seems fairly likely we could make this possible.