More clearly deprecate the pep8 package

PennRobotics commented 3 weeks ago

Background

The 1.7.1 tag deals with the rename from pep8 to pycodestyle. I believe there are a few additional steps that could be taken in a theoretical 1.7.2 tag to get users on the right track.

As a two-year-old issue (#1131) has noted—and their note is still accurate—there are over a million downloads of pep8 per month. While most users can be trusted to notice the warning and upgrade, some users might overlook the notice for a variety of reasons, and each of these users would be missing out on nearly a decade of updates:

pep8 is part of an automation script (e.g. a self-rolled clone of autopep8, or even a pinned legacy version)
They are an experienced user coding on autopilot and scrolling past the regex FutureWarning and deprecation notice straight to the output warning/error list
They are a new user following an old tutorial

(I was the second case; relying on muscle memory. I nearly missed type(e) != NoAlertPresentException which is valid in pep8==1.7.1 but currently should be e is not NoAlertPresentException. I noticed the deprecation notice after multiple iterations of fixing my script's warnings and only because I was scrolling back to check for a debug statement's output and started to read/understand the other output in my console.)

Suggested changes

1. Make the pep8 package status "inactive"

One change which I don't think will make much difference (but is mentioned for the sake of completeness) is changing the classifier in setup.py to Development Status :: 7 - Inactive

2. Change the documentation to only redirect users

The other would be to indicate at the top of README.md that pycodestyle is the current development of pep8. Right now, many users will attempt to install pep8 and find they can no longer install via their package manager. (This was me, today.) They then either blindly assume it's available via pip3 install pep8 or search for more info online. A typical search engine result shows the first few lines of README.md:

PyPI
https://pypi.org › project › pep8

pep8 - Python style guide checker. pep8 is a tool to check your Python code against some of the
style conventions in PEP 8.

Navigating to https://pypi.org/project/pep8/, a user would see the package they've always used plus instructions to install and usage examples. The only indication that this is an unmaintained package name is near the end of a bullet point inside the changelog.

In contrast, a project like hashbox simply states:

hashbox is now ducks

This package has been renamed. Use `pip install ducks` instead.

New package: https://pypi.org/project/ducks/

It cannot get clearer than that.

3. Increase visibility of the notice at runtime

One last option—but I think it's a lot of extra work to get totally right on the first attempt for ALL users—would be to colorize the deprecation notice. Just as the pip version warnings grab your attention, it would be hard not to notice a colorized warning to upgrade. This might be ignored or even broken in certain specific workflows. On the other hand, breaking a workflow for some users might get their attention and prompt most of them to upgrade to pycodestyle.

Summary and PR offer

So, that's three options for improving the deprecation notice. I think changing README.md and setup.py (the first two suggestions) without further adjusting the latest pep8 release (tag 1.7.1, branch 1.7.x) would redirect a significant portion of those 50k daily downloads and wouldn't introduce more maintenance burden (which the third suggestion would require).

~~If you prefer I make this a PR, I could fork 1.7.1 and propose a 1.7.2 tag.~~

I created PR #1270 with these changes if you're interested.

asottile commented 3 weeks ago

the ship has sailed. I don't think we're going to do any of this at this point

PennRobotics commented 3 weeks ago

Makes sense. Thanks regardless!

PyCQA / pycodestyle