Please rename this tool
gvanrossum opened this issue · comments
Tools should not be named after style guide PEPs. A style guide is a document written for humans, and has lots of subtlety. Issues caused by the rigidity or simplicity of the tool end up causing pointless discussion about the letter of the PEP, as if it was a law, which was never the intention of the PEP. If you want to write a tool that checks style, please give it some clever name, don't name it after a PEP, so it's clear that whenever humans don't like what the tool says, it is a tool issue, not an issue with the PEP (which is merely intended to guide humans, not to require them to follow it every time).
FWIW I am happy that pep8 exist! It can be very useful and I use it myself. But I always let it know who's boss. :-)
But I always let it know who's boss. :-)
So do most projects. Every project configures it and projects that use it with Flake8 can use it to make their very own styleguides enforced by checks. OpenStack is one of the best examples of this. They understand (like I contest most users do) that pep8 is an unoriginal name for a tool that is a collection of checks inspired by PEP-0008 (which is a distinction most bug reports will make).
it is a tool issue, not an issue with the PEP
Is there an issue with the (self-described) "living" PEPs receiving too many revisions or "bugs"? We've had a lot of people ask to add their own style imperatives to the tool that we've refused. I wouldn't be surprised if some filed bugs about the document itself as a result.
not to require them to follow it every time
Right, except that some projects appreciate enforcing a specific style which is why they use tools like, pylint, pep8, flake8, pep257, etc. An increasing number of projects are including these tools in their testing pipelines so that the project style is consistent.
That said, I'm merely a contributor. I don't own the package on PyPI and I'm not the maintainer. I just strongly disagree that an unoriginal name is a significant problem.
There are definitely people who pick a fight with PEP 8 (the document) based on the behavior of pep8 (the tool). I think it's reasonable to have deviations between the tool and the document, because projects often have style rules beyond the document, and it would be useful to have a way to have those rules checked by the same tool. Just disabling existing rules in the config file is not always enough.
In general it's important to me that when people informally refer to "pep 8" it's clear they are talking about the document -- and when they are talking about the tool they should be able to use a different name, not have to disambiguate between the two by adding "the document" or "the tool".
I understand it's a pain to change a tool's name, and I don't mind keeping the old name around for backward compatibility -- but I really don't like that the two names sound so alike while being entirely different entities in the same space (Python coding style).
In the world of de-facto corporate trademarks you wouldn't have a leg to stand on. But I really don't want to play by those rules, and I promise I won't involve lawyers -- I don't want that to be a threat. I'd just like you to understand my position.
I think it's reasonable to have deviations between the tool and the document, because projects often have style rules beyond the document
My understanding is that pep8 aims to implement a subset of PEP-0008, and that @sigmavirus24 has been very thorough at maintaining that.
Thus the only "deviations" should be "things specified in PEP-0008 that pep8 doesn't check for".
@sigmavirus24 Am I correct in thinking that?
@gvanrossum It feels (from your language) like part of your objection is "pep8 checks above and beyond PEP-0008" - is that the case? If so, would you be able to point me towards a specific example please?
In the world of de-facto corporate trademarks you wouldn't have a leg to stand on.
I'll take issue with this based on the PSF's Trademark Usage Policy. Notice that "PEP" isn't trademarked there. And even if you, at this point, tried to trademark "PEP", then in all likelihood this tool (and the few others) would be grandfathered because they existed long before it, just like PepsiCo's stock ticker predates that and Pep Boys likely has their own trademarks around "Pep" and "Pep Boys" as well as a bunch of other companies and products.
not have to disambiguate between the two by adding "the document" or "the tool".
So the tool's actual name, is PEP-0008. People can call it PEP-8, but in face-to-face (oral) conversations it's hard to have a distinction between "the document" and "the third-party tool that most developers love and some want to die in a fire".
I really don't like that the two names sound so alike while being entirely different entities in the same space (Python coding style).
I don't like it either (although it makes the tool more discoverable) but it's what it is and I have no power to change that unless I usurp development from @IanLee1521 and register a new package on PyPI. I can't upload a package like pytest has with py.test for pep8 on PyPI.
Thus the only "deviations" should be "things specified in PEP-0008 that pep8 doesn't check for".
As far as I know, most of those are off by default (i.e., in the DEFAULT_IGNORE list). Other things, are (probably) bugs that Guido has filed bugs for in the last ~6 months or so that were imperfections in PEP-0008 that were translated directly to pep8.
My understanding is that pep8 aims to implement a subset of PEP-0008, and that @sigmavirus24 has been very thorough at maintaining that.
How does the tool deal with recommendations like "know when to be inconsistent," which is pretty prominent in the opening section of the PEP (titled "A Foolish Consistency is the Hobgoblin of Little Minds")? And the claim "it's a subset" doesn't apply to this -- the tool just can't ever maintain the spirit of the PEP. And that's why I think it should not be named "pep8" (nor "pep-0008" or whatever capitalization).
If you are interested in solving this issue I am sure all the practical concerns (like who owns the pypi keys) can be solved. If you are not interested, just let me know by closing this as "won't fix". But please do understand this is a real concern of mine.
I can solve the practical concerns, as I do have the keys for PyPI, ReadTheDocs, and here. I don't disagree enough to say "won't fix", so we should keep the discussion going (I've also been following the conversation over on python-dev).
A couple of other practical issues that I see are:
- What to rename it to?
- The likely fairly long switching over effort for projects (a check on PyPI shows ~ 800k downloads in the last month).
As a bit of an aside, I personally would be happy to see more contributions from the PEP authors to move it into better alignment as needed. Though in all fairness I need to get myself more active on fixing some of the existing issues that have happened since I took over the maintainership.
Additionally, as a full disclaimer I'd personally rather see the tool and document become more in line and more of a requirement for Python syntax, in the way that go / gofmt seem to. E.g. that a uniform style for all Python code is a requirement / expectation and that this is just one style for all code. (Before everyone explodes, I do accept that this is unlikely to ever happen, but I can dream can't I?)
How does the tool deal with recommendations like "know when to be inconsistent,"
It's a simple tool. At the moment it has no such capabilities. That said, most people don't want inconsistencies. PEP-0008 describes a super-set of style guidelines. When you combine those with other style guidelines (e.g., Google's as some people have done in varying degrees) then you have a custom style-guide which can be enforced by these projects. People who set-up those style guides often (in my interactions) do not want inconsistency.
What to rename it to?
Preferably something obvious. What we won't be able to do is rename the actual module or the entry-point because that will horribly break people's testing integrations and anyone importing pep8. We can change the package, but the entry-point will take a while before we can properly rename.
That said, downloads don't equate to dependencies. Also the download size is likely a factor larger than what PyPI reports because recent versions of pip cache wheels of pep8 and anything depending on pep8 will continue using that cached version so long as the version is satisfactory.
Additionally, as a full disclaimer I'd personally rather see the tool and document become more in line and more of a requirement for Python syntax, in the way that go / gofmt seem to.
That brings up autopep8 as maintained by @myint. What is to be the fate of that tool? There are other tools that are working on autoformatting and I'm working on making Flake8 handle extensions that auto-format code.
The community is heading this way but they want tools that will do it for them (like gofmt does) so they don't have to think about it. The tooling is heading that way. And yet we're still having discussions about tools not being sufficiently flexible.
The Zen of Python encourages us to write the simplest solution, pep8 and pep257 are exactly that.
As an aside, @IanLee1521 if you want me to take a more active role in the project, I'm happy to do so. I've avoided it because I haven't heard from you and I'm not sure what benefit there is to having an appearance of activity without being able to publish new releases.
pep8lint? Still easy to find in search, isn't confused with PEP8 the document, says what it does and most people know that a lint tool is limited in scope whereas PEP8 may have higher aspirations.
Of course that name is already taken. Sorry.
@gvanrossum mentioned in the discussion for pep257's rename, he'd rather not have PEP or the number of the PEP in the tool's name.
pep257 is going to be renamed. If pep8 will be renamed as well, it might be a good idea to choose similiarly styled names. Like pycodestyle and pydocstyle, or pycodelint and pydoclint.
@Nurdok, I think this is reasonable. Did you decide if you're leaning more towards *style or *lint ?
Also, is the py prefix redundant? Would not just codelint / doclint work, are is there a concern with those being to general?
I was leaning towards *lint, but pycodelint is definitly the worst name in that group, since it will be hard to distinguish from pylint by just the name. I don't mind going with *style, and taking on the name change together will be worth it.
+1 for *style
Since scripts are installed in PATH, there is collision potential with different languages. Also, it makes for a consistent style with pylint and pyflakes (where I work we call them "pychecks" as a group).
This is certainly a good idea, I am personally sick of people complaining that Twisted or Twisted-ecosystem projects do not follow PEP 8, because they run flake8 and pep8 freaks out about our newline convention, even though Twisted follows the golden rule of PEP 8 ("A Foolish Consistency is the Hobgoblin of Little Minds") -- we have our own style guide, and our style conventions are older than PEP 8, so it is entirely reasonable we stick with them.
So I would disagree that the name causes that problem. Different style guides will always cause problems with people who are used to a different style guide. I think it's more likely that a name like pycodestyle will cause problems than pep8.
But the problem is that pep8 does not and can not check PEP 8 compliance. It checks compliance for a grab bag of suggestions from the PEP8 document, with none of the sublety of the document's meaning or stated goal -- which is where I believe gvr's core issue lies. pycodestyle doesn't make any assumptions about what it checks for from the outside alone, and will hopefully break the idea of pep8 throws up on this project vs this project not being PEP 8 compliant. (Seriously, if I had a penny for every time someone said Twisted was not PEP 8 compliant because they've associated the tool's output with the actual PEP, I wouldn't need to worry about writing PSF grant proposals to fund my work ;) )
On 14 Jan 2016 00:11, Ian Cordasco notifications@github.com wrote:So I would disagree that the name causes that problem. Different style guides will always cause problems with people who are used to a different style guide. I think it's more likely that a name like pycodestyle will cause problems than pep8.
—Reply to this email directly or view it on GitHub.
@IanLee1521 so do you like pycodestyle and pydocstyle?
@Nurdok I registered pycodestyle for Ian (and added him as a package owner). He seemed to be in favor of those names.
Also to answer his question about the py being redundant, downstream packagers will definitely have problems with us not adding some kind of classifier (e.g., py or something else) because codestyle/codelint are way too general.
Thanks Ian. Yes, I think that that pycodestyle and pydocstyle are good ways to go.
Now for the actual transition roadmap, what should be the best order? Just do everything at once (repo , package, and script name), or should there be a more gradual transition?
I know @gvanrossum will probably hate this but I think both tools should have a deprecation period of ~1 year. pycodestyle/pydocstyle should ship command-line entry-points for pep8/pep257 that issue deprecation warnings when using them.
It's okay. You guys are great for listening!
On Fri, Jan 22, 2016 at 11:30 AM, Ian Cordasco notifications@github.com
wrote:
I know @gvanrossum https://github.com/gvanrossum will probably hate
this but I think both tools should have a deprecation period of ~1 year.
pycodestyle/pydocstyle should ship command-line entry-points for
pep8/pep257 that issue deprecation warnings when using them.—
Reply to this email directly or view it on GitHub
#466 (comment).
--Guido van Rossum (python.org/~guido)
Ok, I propose the following as the transition timeline (dates are all approximate at this point):
This week -- Rename the repo here on GitHub to pycodestyle, while leaving the code untouched for the moment. This will alert developers looking for the repo to the change thats coming. Also, push the 1.7.0 code to the pycodestyle package on pypi, meaning there will be both a pep8 and a pycodestyle package available on pypi.
~ March 1 -- Update flake8 and other similar tools to start depending on the new package, pycodestyle, which would likely be transparent to those users that only interact with this package via those tools.
~ April 1 -- Add deprecation warning to the pep8 tool that users should instead install pycodestyle (which at that point should probably start installing a pycodestyle console_entry in addition to the pep8 console command.
~ June 1 -- Update code base to start only referring to pycodestyle as the command, removing references to pep8, except maybe keeping the console script that is installed (still installing both pep8 and pycodestyle. (Though maybe this should technically occur before May 28, e.g. PyCon 2016? Maybe that has value?)
~ September 1 -- Remove pep8 command from installation of both the pep8 and pycodestyle python packages on pypi. Double check that the usage on pypi of pep8 is shrinking.
~ December 1 -- Remove the pep8 package from pypi. @gvanrossum rejoices! :)
Those are my thoughts, trying to keep in line with @sigmavirus24 suggestion of a 1 year deprecation period. I'd be open to moving faster, but probably not less than a month or so for each of the steps, which would move the December 1 target up to July 1. Thoughts?
~ December 1 -- Remove the pep8 package from pypi.
How about a new version with a setup.py that errors out with a helpful message (cf. https://github.com/pytest-dev/pytest/blob/1f6988bdec07caa0c6488a488b390beeed32e529/extra/setup-py.test/setup.py)
Then you're still providing downloads for people yet to update (if they're pinned to old versions), while providing a good user experience for people updating existing dependencies AND for those in the habit of just doing pip install pep8
Yeah. I think we should not simply remove the pep8 package from PyPI. That will allow someone to re-register that name only further antagonizing Guido.
As for Flake8, we will likely want to keep a fallback import for pep8. And to simplify the changes to flake8, we will likely simply do something like:
try:
import pycodestyle as pep8
except ImportError:
import pep8Sound fair?
That's fair. Certainly the not dropping the pep8 package from PyPI.
As far as flake8, I feel like eventually we should update to just inport pycodestyle and use that, though I'd be fine waiting for a while / beyond the end of the timeline listed above.
Right. I'm speaking about the more immediate term. We currently have very loose lower bounds on pep8. I would be happy eventually releasing Flake8 2.6.0 or 2.7.0 with a dependency that looks like:
pycodestyle>=1.7.0,<1.8.0
As an aside, pep8.org was just registered but not by anyone associated with this project. Any complaints about what content eventually lands there should be filed elsewhere.
Any timeline for when you plan to push a pycodestyle package to pip?
Going to try to get it pushed out this weekend.
FYI, in case you want to lock this thread, I submitted this issue to r/Python for discussion.
(I wish GitHub offered "non-participating" links like Reddit. i.e. The np.reddit.com domain.)
@IanLee1521 Any chance you can push a pycodestyle package to Pypi soon? Got a few projects I'd like to get swapped over
@jeffwidman what exactly do you want to switch over? Just to the new dependency name? If so, I can help with that, but the module itself will still be pep8
@jeffwidman -- I have hope that I'll be able to push this out this week. Some high priority items popped up at work to bump this off my radar. Cheers.
Isn't it a little late by now? This tool has been around by this name since 2006. A decade. Given the number of links of various forms to this tool by the name pep8, surely the cost of renaming it outweighs the benefit.
I'd rather that the "Foolish consistency ..." section of the PEP8 document noted that tools such as this one exist and aren't to be taken too seriously.
Well, unless you rename it the Spanish Inquisition. 😄
@dckc it's a bit late now to be arguing for not changing the name. Further, I'd rather not create more contention over the use of tooling to enforce a project's chosen style guide. There's already enough arguments over a project's chosen style guide and adherence to it when contributors disagree, we don't need people to be told to not take these tools seriously, especially when people are choosing to use them for their projects.
Just noting that http://pycodestyle.readthedocs.io/ doesnt exist yet, and http://pep8.readthedocs.io/ is being updated with post-name-change docs.
@jayvdb pycodestyle.pycqa.org should work just fine.
Yes... Unfortunately the issue (and why a number of the items I laid out in the transition timeline haven't occurred yet) was that work and a trip into the mountains with no internet, have kept me from actually fixing this in RTD.
My goal is to get caught up by the end of PyCon US if all goes well!
Ok, I just looked at where I'd left off with this... It looks like what happened is that RTD doesn't really support project renaming which also changes the URL (see: readthedocs/readthedocs.org#523, readthedocs/readthedocs.org#327, and readthedocs/readthedocs.org#1440) and so my changing the project name didn't have the desired effect (see the difference between the URL and HTML on https://readthedocs.org/projects/pep8/...
I just created a new project in RTD that now has the URL that we want, looks like next step is for me to update the docs to have the "pycodestyle" name in the docs rather than "pep8" (though if anyone else has time, I'm happy to review a PR to update those).
Side note...
| I love trips into the mountains or desert without net access! Hope you enjoyed it. No worries.
Enjoyed it very much! Was just building not quite _soft_ware ;) https://goo.gl/photos/UG5SVMVQFSbjbGw59
Just pushed the pre-release version of pycodestyle 1.8.0.dev0 to pypi -- https://pypi.python.org/pypi/pycodestyle/1.8.0.dev0
Try it out if you're able!
Came up at the open space today... Did we ever figure out what @kennethreitz is doing with pep8.org ?
Hopefully he'll continue to show a nicely formatted version of PEP 8.
On Tue, May 31, 2016 at 12:23 AM, Ian Lee notifications@github.com wrote:
Came up at the open space today... Did we ever figure out what
@kennethreitz https://github.com/kennethreitz is doing with pep8.org ?—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#466 (comment),
or mute the thread
https://github.com/notifications/unsubscribe/ACwrMr1vrOSlD1fkvFxOH-qjLtLht7kAks5qG-HxgaJpZM4G-N_W
.
--Guido van Rossum (python.org/~guido)
Going to go ahead and close this since it was completed for the 2.0 release. Any outstanding tasks I'll open as new issues.
Thanks everyone for your help and feedback on this transition!
pep8.org will indeed continue to be exactly what it is: a well-presented version of the contents of PEP 8.
The site is not tremendously popular. It receives only between 40 and 90 visitors daily.
It's already a little behind. It turns out, PEP 8 receives more revisions than I realized, and I have to replicate these changes manually. I'll hopefully sit down to do this soon.
There is also a bug with the drop-case titles on very latest versions of Safari, which features improved typographic rendering for drop-caps. I will likely simply drop the drop-caps in order to fix this.
If anyone wants to help with the above tasks, your contribution is more than welcome! :)
https://pypi.python.org/pypi/pep8 says nothing about the name change, hence it'd be easy to conclude 1.7.0 is the latest version.
Also, the note on http://pep8.readthedocs.io/en/release-1.7.x/ (where the "read documentation" points to) mentions the rename but doesn't provide links to either PyPI or RTD for the new name, both of which would be helpful.
Great points @gsnedders , I've opened two new tickets to track those.
Would happily review pull requests if you had the time to make a first pass.
Hello @IanLee1521, I am new to contributing to open source projects. This would be my first commit and I would love to help out. Are those tickets resolved yet or is it still available for me to contribute?
Tools should not be named after style guide PEPs. A style guide is a document written for humans, and has lots of subtlety. Issues caused by the rigidity or simplicity of the tool end up causing pointless discussion about the letter of the PEP, as if it was a law, which was never the intention of the PEP. If you want to write a tool that checks style, please give it some clever name, don't name it after a PEP, so it's clear that whenever humans don't like what the tool says, it is a tool issue, not an issue with the PEP (which is merely intended to guide humans, not to require them to follow it every time).
FWIW I am happy that pep8 exist! It can be very useful and I use it myself. But I always let it know who's boss. :-)
try it press out