some minor questions about pep8
In pep8 there are two conflicting statements, both
https://www.python.org/dev/peps/pep-0008/#version-bookkeeping https://www.python.org/dev/peps/pep-0008/#imports
Stipulate that they should be "at the top of the file after any module comments and docstrings." Which of these takes precedence?
Secondly, we also have an "__author__", and "__project__" variables, I assume these would be put with the version information as well?
Lewis Coates lewisc@pdx.edu writes:
In pep8 there are two conflicting statements, both
https://www.python.org/dev/peps/pep-0008/#version-bookkeeping https://www.python.org/dev/peps/pep-0008/#imports
Stipulate that they should be "at the top of the file after any module comments and docstrings." Which of these takes precedence?
I don't know an official answer. The convention I've observed is overwhelmingly in one direction: import statements come before any assignment statements.
Secondly, we also have an "__author__", and "__project__" variables, I assume these would be put with the version information as well?
Yes.
FWIW, I think __version__, __author__ etc. were bad ideas. Almost nobody manages these correctly. Note that the PEP 8 section starts with less than an endorsement: "If you *have* to have Subversion, CVS, or RCS crud in your source file, do it as follows."
That said, if an official answer is required, common sense would suggest that __version__ should go before the imports. (I would put it before the docstring too, except then the docstring wouldn't be a docstring any more. Go figure.)
On Fri, Mar 20, 2015 at 6:38 PM, Ben Finney ben+python@benfinney.id.au wrote:
Lewis Coates lewisc@pdx.edu writes:
In pep8 there are two conflicting statements, both
https://www.python.org/dev/peps/pep-0008/#version-bookkeeping https://www.python.org/dev/peps/pep-0008/#imports
Stipulate that they should be "at the top of the file after any module comments and docstrings." Which of these takes precedence?
I don't know an official answer. The convention I've observed is overwhelmingly in one direction: import statements come before any assignment statements.
Secondly, we also have an "__author__", and "__project__" variables, I assume these would be put with the version information as well?
Yes.
-- \ “Welchen Teil von ‘Gestalt’ verstehen Sie nicht? [What part of | `\ ‘gestalt’ don't you understand?]” —Karsten M. Self | _o__) | Ben Finney
Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/guido%40python.org
Guido,
In that case would you be open to a patch to update the PEP accordingly?
Additionally, does that official statement cover other dunder assignments (e.g. "__author__"?). If so I'll update the PEP8 tool accordingly.
Thanks,
~ Ian Lee On Mar 20, 2015 8:55 PM, "Guido van Rossum" guido@python.org wrote:
FWIW, I think __version__, __author__ etc. were bad ideas. Almost nobody manages these correctly. Note that the PEP 8 section starts with less than an endorsement: "If you *have* to have Subversion, CVS, or RCS crud in your source file, do it as follows."
That said, if an official answer is required, common sense would suggest that __version__ should go before the imports. (I would put it before the docstring too, except then the docstring wouldn't be a docstring any more. Go figure.)
On Fri, Mar 20, 2015 at 6:38 PM, Ben Finney ben+python@benfinney.id.au wrote:
Lewis Coates lewisc@pdx.edu writes:
In pep8 there are two conflicting statements, both
https://www.python.org/dev/peps/pep-0008/#version-bookkeeping https://www.python.org/dev/peps/pep-0008/#imports
Stipulate that they should be "at the top of the file after any module comments and docstrings." Which of these takes precedence?
I don't know an official answer. The convention I've observed is overwhelmingly in one direction: import statements come before any assignment statements.
Secondly, we also have an "__author__", and "__project__" variables, I assume these would be put with the version information as well?
Yes.
-- \ “Welchen Teil von ‘Gestalt’ verstehen Sie nicht? [What part of | `\ ‘gestalt’ don't you understand?]” —Karsten M. Self | _o__) | Ben Finney
Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/guido%40python.org
-- --Guido van Rossum (python.org/~guido)
Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/ianlee1521%40gmail.com
FWIW, I would vote for the "__version__", "__author__", etc assignments being after the imports. Reason being cases where the "__version__" is not from VCS, but is calculated from pkg_resources:
from pkg_resources import get_distribution __version__ = get_distribution('mypackage').version
Also, then more useful things like "__all__" (which can very reasonably rely on imports), can be together with "__version__" and "__author__" assignments.
I would vote:
shebang docstring imports dunder assignments other code...
</2 cents>
~ Ian Lee
On Fri, Mar 20, 2015 at 9:24 PM, Ian Lee ianlee1521@gmail.com wrote:
Guido,
In that case would you be open to a patch to update the PEP accordingly?
Additionally, does that official statement cover other dunder assignments (e.g. "__author__"?). If so I'll update the PEP8 tool accordingly.
Thanks,
~ Ian Lee On Mar 20, 2015 8:55 PM, "Guido van Rossum" guido@python.org wrote:
FWIW, I think __version__, __author__ etc. were bad ideas. Almost nobody manages these correctly. Note that the PEP 8 section starts with less than an endorsement: "If you *have* to have Subversion, CVS, or RCS crud in your source file, do it as follows."
That said, if an official answer is required, common sense would suggest that __version__ should go before the imports. (I would put it before the docstring too, except then the docstring wouldn't be a docstring any more. Go figure.)
On Fri, Mar 20, 2015 at 6:38 PM, Ben Finney ben+python@benfinney.id.au wrote:
Lewis Coates lewisc@pdx.edu writes:
In pep8 there are two conflicting statements, both
https://www.python.org/dev/peps/pep-0008/#version-bookkeeping https://www.python.org/dev/peps/pep-0008/#imports
Stipulate that they should be "at the top of the file after any module comments and docstrings." Which of these takes precedence?
I don't know an official answer. The convention I've observed is overwhelmingly in one direction: import statements come before any assignment statements.
Secondly, we also have an "__author__", and "__project__" variables, I assume these would be put with the version information as well?
Yes.
-- \ “Welchen Teil von ‘Gestalt’ verstehen Sie nicht? [What part of | `\ ‘gestalt’ don't you understand?]” —Karsten M. Self | _o__) | Ben Finney
Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/guido%40python.org
-- --Guido van Rossum (python.org/~guido)
Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/ianlee1521%40gmail.com
On Mar 20, 2015, at 09:59 PM, Ian Lee wrote:
shebang docstring imports dunder assignments other code...
I generally put imports after dunders, except for __future__. I want the first screenful of code to contain them, and imports can be a few dozen lines in some modules.
-Barry
On Fri, Mar 20, 2015 at 9:24 PM, Ian Lee ianlee1521@gmail.com wrote:
Guido,
In that case would you be open to a patch to update the PEP accordingly?
Only if it totally eradicate __version__ and similar from the PEP.
Additionally, does that official statement cover other dunder assignments (e.g. "__author__"?). If so I'll update the PEP8 tool accordingly.
What official statement? I'm not the Pope. :-)
--Guido
Thanks,
~ Ian Lee On Mar 20, 2015 8:55 PM, "Guido van Rossum" guido@python.org wrote:
FWIW, I think __version__, __author__ etc. were bad ideas. Almost nobody manages these correctly. Note that the PEP 8 section starts with less than an endorsement: "If you *have* to have Subversion, CVS, or RCS crud in your source file, do it as follows."
That said, if an official answer is required, common sense would suggest that __version__ should go before the imports. (I would put it before the docstring too, except then the docstring wouldn't be a docstring any more. Go figure.)
On Fri, Mar 20, 2015 at 6:38 PM, Ben Finney ben+python@benfinney.id.au wrote:
Lewis Coates lewisc@pdx.edu writes:
In pep8 there are two conflicting statements, both
https://www.python.org/dev/peps/pep-0008/#version-bookkeeping https://www.python.org/dev/peps/pep-0008/#imports
Stipulate that they should be "at the top of the file after any module comments and docstrings." Which of these takes precedence?
I don't know an official answer. The convention I've observed is overwhelmingly in one direction: import statements come before any assignment statements.
Secondly, we also have an "__author__", and "__project__" variables, I assume these would be put with the version information as well?
Yes.
-- \ “Welchen Teil von ‘Gestalt’ verstehen Sie nicht? [What part of | `\ ‘gestalt’ don't you understand?]” —Karsten M. Self | _o__) | Ben Finney
Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/guido%40python.org
-- --Guido van Rossum (python.org/~guido)
Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/ianlee1521%40gmail.com
On Mar 20, 2015, at 08:53 PM, Guido van Rossum wrote:
FWIW, I think __version__, __author__ etc. were bad ideas. Almost nobody manages these correctly. Note that the PEP 8 section starts with less than an endorsement: "If you *have* to have Subversion, CVS, or RCS crud in your source file, do it as follows."
I tend to agree. Individual module version numbers are mostly useless, especially with today's hash-based vcses.
That's different than package versions, and for which I really need to resurrect and update PEP 396.
That said, if an official answer is required, common sense would suggest that __version__ should go before the imports. (I would put it before the docstring too, except then the docstring wouldn't be a docstring any more. Go figure.)
And after __future__ imports too, right?
Cheers, -Barry
On Mar 21, 2015, at 4:53 PM, Barry Warsaw barry@python.org wrote:
On Mar 20, 2015, at 08:53 PM, Guido van Rossum wrote:
FWIW, I think __version__, __author__ etc. were bad ideas. Almost nobody manages these correctly. Note that the PEP 8 section starts with less than an endorsement: "If you *have* to have Subversion, CVS, or RCS crud in your source file, do it as follows."
I tend to agree. Individual module version numbers are mostly useless, especially with today's hash-based vcses.
That's different than package versions, and for which I really need to resurrect and update PEP 396.
I sort of think (though I haven’t completely convinced myself) that adding something like __version__ to a package is a work around to the fact that we don’t have an API that lets someone ask “what is the distribution and version that this module/import-package came from”.
Something like:
>>> import theorticalapi >>> import mymodule >>> >>> d = theorticalapi.module_dist(mymodule) >>> print(d.name) >>> mycustommodules >>> print(d.version) >>> 1.0
Since we (theoretically) should have all of this information already inside of the packaging metadata, we just don’t have a way to say “given a particular import, give me the information I want).
That said, if an official answer is required, common sense would suggest that __version__ should go before the imports. (I would put it before the docstring too, except then the docstring wouldn't be a docstring any more. Go figure.)
And after __future__ imports too, right?
Cheers, -Barry _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/donald%40stufft.io
--- Donald Stufft PGP: 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
On 2015-03-21 21:00, Donald Stufft wrote:
On Mar 21, 2015, at 4:53 PM, Barry Warsaw barry@python.org wrote:
On Mar 20, 2015, at 08:53 PM, Guido van Rossum wrote:
FWIW, I think __version__, __author__ etc. were bad ideas. Almost nobody manages these correctly. Note that the PEP 8 section starts with less than an endorsement: "If you *have* to have Subversion, CVS, or RCS crud in your source file, do it as follows."
I tend to agree. Individual module version numbers are mostly useless, especially with today's hash-based vcses.
That's different than package versions, and for which I really need to resurrect and update PEP 396.
I sort of think (though I haven’t completely convinced myself) that adding something like __version__ to a package is a work around to the fact that we don’t have an API that lets someone ask “what is the distribution and version that this module/import-package came from”.
Something like:
>>> import theorticalapi >>> import mymodule >>> >>> d = theorticalapi.module_dist(mymodule) >>> print(d.name) >>> mycustommodules >>> print(d.version) >>> 1.0Since we (theoretically) should have all of this information already inside of the packaging metadata, we just don’t have a way to say “given a particular import, give me the information I want).
A bit OT (and should probably be in python-ideas), but I've come to think that it might be more helpful to have double version numbers.
What do I mean by that?
Well, an "addition" version that's increased when something is added, and a "deletion" version that's increased when something is removed.
Suppose there's a new release of a module.
If it has a higher "addition version", then something has been added, which won't affect existing code.
If it has a higher "deletion version", then something has been removed, which _might_ affect existing code, so you'll need to check. If the code doesn't use what was removed, then you can accept the higher deletion version.
That said, if an official answer is required, common sense would suggest that __version__ should go before the imports. (I would put it before the docstring too, except then the docstring wouldn't be a docstring any more. Go figure.)
And after __future__ imports too, right?
On Mar 21, 2015, at 5:17 PM, MRAB python@mrabarnett.plus.com wrote:
On 2015-03-21 21:00, Donald Stufft wrote:
On Mar 21, 2015, at 4:53 PM, Barry Warsaw barry@python.org wrote:
On Mar 20, 2015, at 08:53 PM, Guido van Rossum wrote:
FWIW, I think __version__, __author__ etc. were bad ideas. Almost nobody manages these correctly. Note that the PEP 8 section starts with less than an endorsement: "If you *have* to have Subversion, CVS, or RCS crud in your source file, do it as follows."
I tend to agree. Individual module version numbers are mostly useless, especially with today's hash-based vcses.
That's different than package versions, and for which I really need to resurrect and update PEP 396.
I sort of think (though I haven’t completely convinced myself) that adding something like __version__ to a package is a work around to the fact that we don’t have an API that lets someone ask “what is the distribution and version that this module/import-package came from”.
Something like:
>>> import theorticalapi >>> import mymodule >>> >>> d = theorticalapi.module_dist(mymodule) >>> print(d.name) >>> mycustommodules >>> print(d.version) >>> 1.0Since we (theoretically) should have all of this information already inside of the packaging metadata, we just don’t have a way to say “given a particular import, give me the information I want).
A bit OT (and should probably be in python-ideas), but I've come to think that it might be more helpful to have double version numbers.
What do I mean by that?
Well, an "addition" version that's increased when something is added, and a "deletion" version that's increased when something is removed.
Suppose there's a new release of a module.
If it has a higher "addition version", then something has been added, which won't affect existing code.
If it has a higher "deletion version", then something has been removed, which _might_ affect existing code, so you'll need to check. If the code doesn't use what was removed, then you can accept the higher deletion version.
This is likely better solved by something like https://semver.org/ which is similar to what many people do already:
X.Y.Z+1 == Bug fixes only, should be backwards compatible. X.Y+1.0 == New features, should be backwards compatible but comes with new things. X+1.0.0 == Backwards Compatibility Break (Something deleted or changed)
That said, if an official answer is required, common sense would suggest that __version__ should go before the imports. (I would put it before the docstring too, except then the docstring wouldn't be a docstring any more. Go figure.)
And after __future__ imports too, right?
Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/donald%40stufft.io
--- Donald Stufft PGP: 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
On Mar 21, 2015, at 05:00 PM, Donald Stufft wrote:
I sort of think (though I haven’t completely convinced myself) that adding something like __version__ to a package is a work around to the fact that we don’t have an API that lets someone ask “what is the distribution and version that this module/import-package came from”.
I tend to agree. Having that would solve one of the big problems that lead to PEP 394 thinking, that of having to update version numbers in more than one place. ISTM the best place to do it is once in setup.py and let the metadata flow. The only downside is for doing in-tree development without 'installing' the package (e.g. absence of venv, tox, or similar).
Cheers, -Barry
On 22 March 2015 at 07:46, Barry Warsaw barry@python.org wrote:
On Mar 21, 2015, at 05:00 PM, Donald Stufft wrote:
I sort of think (though I haven’t completely convinced myself) that adding something like __version__ to a package is a work around to the fact that we don’t have an API that lets someone ask “what is the distribution and version that this module/import-package came from”.
I tend to agree. Having that would solve one of the big problems that lead to PEP 394 thinking, that of having to update version numbers in more than one place. ISTM the best place to do it is once in setup.py and let the metadata flow. The only downside is for doing in-tree development without 'installing' the package (e.g. absence of venv, tox, or similar).
We don't *quite* track enough distribution metadata currently to reliably build the reverse mapping from module names to the packages that installed them. The draft "python.exports" extension in PEP 459 is supposed to provide that missing piece: https://www.python.org/dev/peps/pep-0459/#the-python-exports-extension
Cheers, Nick.
participants (8)
-
Barry Warsaw -
Ben Finney -
Donald Stufft -
Guido van Rossum -
Ian Lee -
Lewis Coates -
MRAB -
Nick Coghlan