What level of detail wanted for import and the language reference?
At this point importlib is done for its public API for Python 3.1. That means it's time to turn my attention to making sure the semantics of import are well documented. But where to put all of the details? The language reference for import ( http://docs.python.org/dev/py3k/reference/simple_stmts.html#the-import-state...) explains the basics, but is lacking all of the details of PEP 302 and other stuff like __path__ that have existed for ages. My question is if I should flesh out the details in the language reference or do it in importlib's intro docs. The main reason I could see not doing it in the langauge reference (or at least duplicating it) is it would be somewhat easier to reference specific objects in importlib but I am not sure if the language reference should try to stay away from stdlib references. -Brett
Brett Cannon wrote:
At this point importlib is done for its public API for Python 3.1. That means it's time to turn my attention to making sure the semantics of import are well documented. But where to put all of the details? The language reference for import (http://docs.python.org/dev/py3k/reference/simple_stmts.html#the-import-state...) explains the basics, but is lacking all of the details of PEP 302 and other stuff like __path__ that have existed for ages.
My question is if I should flesh out the details in the language reference or do it in importlib's intro docs. The main reason I could see not doing it in the langauge reference (or at least duplicating it) is it would be somewhat easier to reference specific objects in importlib but I am not sure if the language reference should try to stay away from stdlib references.
Having the Python import semantics well documented will be an *excellent* side effect of importlib. Thank you for your astonishing efforts on this project. Personally I would rather see the import semantics themselves in the language reference. Michael
-Brett ------------------------------------------------------------------------
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.u...
-- http://www.ironpythoninaction.com/ http://www.voidspace.org.uk/blog
On Mon, Mar 16, 2009, Michael Foord wrote:
Personally I would rather see the import semantics themselves in the language reference.
Either way is fine with me, but it needs to be cross-referenced. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ Adopt A Process -- stop killing all your children!
2009/3/16 Brett Cannon <brett@python.org>:
At this point importlib is done for its public API for Python 3.1. That means it's time to turn my attention to making sure the semantics of import are well documented. But where to put all of the details? The language reference for import (http://docs.python.org/dev/py3k/reference/simple_stmts.html#the-import-state...) explains the basics, but is lacking all of the details of PEP 302 and other stuff like __path__ that have existed for ages.
My question is if I should flesh out the details in the language reference or do it in importlib's intro docs. The main reason I could see not doing it in the langauge reference (or at least duplicating it) is it would be somewhat easier to reference specific objects in importlib but I am not sure if the language reference should try to stay away from stdlib references.
Thanks so much for doing this! Personally, I think you should put it in the language reference. (I think it deserves it's own file if it's as big as I suspect it will be.) If I wanted to use importlib, I wouldn't really want to slog through a in-depth description of how exactly import works. -- Regards, Benjamin
Benjamin Peterson schrieb:
2009/3/16 Brett Cannon <brett@python.org>:
At this point importlib is done for its public API for Python 3.1. That means it's time to turn my attention to making sure the semantics of import are well documented. But where to put all of the details? The language reference for import (http://docs.python.org/dev/py3k/reference/simple_stmts.html#the-import-state...) explains the basics, but is lacking all of the details of PEP 302 and other stuff like __path__ that have existed for ages.
My question is if I should flesh out the details in the language reference or do it in importlib's intro docs. The main reason I could see not doing it in the langauge reference (or at least duplicating it) is it would be somewhat easier to reference specific objects in importlib but I am not sure if the language reference should try to stay away from stdlib references.
Thanks so much for doing this! Personally, I think you should put it in the language reference. (I think it deserves it's own file if it's as big as I suspect it will be.)
If you asked me, I'd concur with Benjamin. Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out.
Brett Cannon wrote:
At this point importlib is done for its public API for Python 3.1. That means it's time to turn my attention to making sure the semantics of import are well documented. But where to put all of the details? The language reference for import (http://docs.python.org/dev/py3k/reference/simple_stmts.html#the-import-state...) explains the basics, but is lacking all of the details of PEP 302 and other stuff like __path__ that have existed for ages.
My question is if I should flesh out the details in the language reference or do it in importlib's intro docs. The main reason I could see not doing it in the langauge reference (or at least duplicating it) is it would be somewhat easier to reference specific objects in importlib but I am not sure if the language reference should try to stay away from stdlib references.
Why not just put a section in both places that says "can't be bothered to spell this out right now" and put a URL in referring to this thread on Google ... that appears to have been the traditional approach to import semantics :) regards Steve -- Steve Holden +1 571 484 6266 +1 800 494 3119 Holden Web LLC http://www.holdenweb.com/ Want to know? Come to PyCon - soon! http://us.pycon.org/
Steve Holden wrote:
Why not just put a section in both places that says "can't be bothered to spell this out right now" and put a URL in referring to this thread on Google ... that appears to have been the traditional approach to import semantics :)
Well, first we point to Guido's original package essay, then to PEP 302, then to PEP 338, then to PEP 366... and then we count the number of people that slogged through all that without needing to take our shoes off :) On a more helpful note, Brett, you may find the write-up I did of the import system a year or two ago helpful: http://svn.python.org/view/sandbox/trunk/userref/ODF/Chapter07_ModulesAndApp... (some parts are a little dated now obviously, but you may still find it better than starting with a blank page) Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia ---------------------------------------------------------------
On Tue, Mar 17, 2009 at 06:55, Nick Coghlan <ncoghlan@gmail.com> wrote:
Steve Holden wrote:
Why not just put a section in both places that says "can't be bothered to spell this out right now" and put a URL in referring to this thread on Google ... that appears to have been the traditional approach to import semantics :)
Well, first we point to Guido's original package essay, then to PEP 302, then to PEP 338, then to PEP 366... and then we count the number of people that slogged through all that without needing to take our shoes off :)
The See Also section in importlib probably has the most links of any other module in the stdlib.
On a more helpful note, Brett, you may find the write-up I did of the import system a year or two ago helpful:
http://svn.python.org/view/sandbox/trunk/userref/ODF/Chapter07_ModulesAndApp...
(some parts are a little dated now obviously, but you may still find it better than starting with a blank page)
I'll have a look. -Brett
Doc changes are now checked in. Someone who has not been starting at import for over two years should probably go in and clean it up as it is probably not clear to a newbie (but then again newbies should not be reading the language ref; more worried about the docs in sys). On Mon, Mar 16, 2009 at 15:39, Brett Cannon <brett@python.org> wrote:
At this point importlib is done for its public API for Python 3.1. That means it's time to turn my attention to making sure the semantics of import are well documented. But where to put all of the details? The language reference for import ( http://docs.python.org/dev/py3k/reference/simple_stmts.html#the-import-state...) explains the basics, but is lacking all of the details of PEP 302 and other stuff like __path__ that have existed for ages.
My question is if I should flesh out the details in the language reference or do it in importlib's intro docs. The main reason I could see not doing it in the langauge reference (or at least duplicating it) is it would be somewhat easier to reference specific objects in importlib but I am not sure if the language reference should try to stay away from stdlib references.
-Brett
2009/3/20 Brett Cannon <brett@python.org>:
Doc changes are now checked in. Someone who has not been starting at import for over two years should probably go in and clean it up as it is probably not clear to a newbie (but then again newbies should not be reading the language ref; more worried about the docs in sys).
It would be nice to have at least the sys docs backported to the trunk. -- Regards, Benjamin
On Fri, Mar 20, 2009 at 20:18, Benjamin Peterson <benjamin@python.org>wrote:
Doc changes are now checked in. Someone who has not been starting at import for over two years should probably go in and clean it up as it is
2009/3/20 Brett Cannon <brett@python.org>: probably
not clear to a newbie (but then again newbies should not be reading the language ref; more worried about the docs in sys).
It would be nice to have at least the sys docs backported to the trunk.
That would also require backporting stuff from the glossary. In other words I ain't doing it now, but you might be able to convince me at PyCon. I will at least create a bug about it, though. -Brett
participants (7)
-
Aahz -
Benjamin Peterson -
Brett Cannon -
Georg Brandl -
Michael Foord -
Nick Coghlan -
Steve Holden