classification
Title: Clarify the pkgutil.walk_packages() note
Type: Stage:
Components: Documentation Versions: Python 3.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Ronan.Lamy, brett.cannon, chris.jerdonek, docs@python, python-dev
Priority: normal Keywords: easy

Created on 2012-07-07 18:15 by chris.jerdonek, last changed 2012-07-09 18:48 by brett.cannon. This issue is now closed.

Messages (6)
msg164916 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-07 18:15
The note at the end of the pkgutil.walk_packages() (and iter_modules()) documentation can be improved somewhat:

http://docs.python.org/dev/library/pkgutil.html#pkgutil.walk_packages

For example, "importers" aren't referenced earlier in the documentation of the function, so it's not immediately clear what they are referring to.  I also think that enough information should be given so that one can run the examples given and have them work.  They currently don't.

I can put together proposed wording.  See the issue 14982 discussion for background.
msg164959 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2012-07-08 01:44
Probably linking the term "importers" into the glossary should be enough.
msg165096 - (view) Author: Ronan Lamy (Ronan.Lamy) * Date: 2012-07-09 17:08
It seems that most, if not all, uses of "importer" in pkgutil refer to finders, e.g. ImpImporter is a actually only a finder, not an importer. So s/importer/finder/ is needed, and perhaps also a note explaining that ImpImporter isn't in fact an importer, in addition to glossary links.
msg165102 - (view) Author: Roundup Robot (python-dev) Date: 2012-07-09 18:10
New changeset 96f7926ea444 by Brett Cannon in branch 'default':
Issue #15288: Clarify that pkgutil.walk_packages() and friends will no
http://hg.python.org/cpython/rev/96f7926ea444
msg165103 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2012-07-09 18:11
I changed to term to "loader" and linked to the glossary. I also added a versionchanged note for Python 3.3 so people are not too surprised that pkgutil no longer does what it did in Python 3.2.
msg165106 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2012-07-09 18:48
Ronan is right that it is all about finders, not importers per-se. I fixed the docs to not say "loader".
History
Date User Action Args
2012-07-09 18:48:42brett.cannonsetmessages: + msg165106
2012-07-09 18:11:20brett.cannonsetstatus: open -> closed
resolution: fixed
messages: + msg165103
2012-07-09 18:10:30python-devsetnosy: + python-dev
messages: + msg165102
2012-07-09 17:08:47Ronan.Lamysetnosy: + Ronan.Lamy
messages: + msg165096
2012-07-08 01:44:19brett.cannonsetnosy: + brett.cannon
messages: + msg164959
2012-07-07 18:15:57chris.jerdonekcreate