Mailman 3 February 2012 - docs

[issue10434] Document the rules for "public names"
by Alexander Belopolsky Aug. 1, 2013

Aug. 1, 2013

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: As discussed in "Breaking undocumented API" thread [1] on python-dev, a definition of "public names" is buried deep in the language reference manual: """ The public names defined by a module are determined by checking the module’s namespace for a variable named __all__; if defined, it must be a sequence of strings which are names defined or imported by that module. The names given in __all__ are all considered public and are required to exist. If __all__ is not defined, the set of public names includes all names found in the module’s namespace which do not begin with an underscore character ('_'). __all__ should contain the entire public API. It is intended to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module). """ [2] It has been argued that this is not the authoritative definition and alternatives have been suggested such as "any name that does not begin with an underscore except imported modules." mportant for the users and developers of cpython and other python implementations to know what names they can rely upon to stay defined between releases, the rules for "public names" should be documented. I agree that the library manual is a more appropriate place for such documentation. The definition should include the naming conventions and the set of promises that Python makes about public name availability in the future releases. [1] http://mail.python.org/pipermail/python-dev/2010-November/105490.html [2] http://docs.python.org/reference/simple_stmts.html ---------- assignee: docs@python components: Documentation messages: 121297 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: Document the rules for "public names" versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10434> _______________________________________

6 7

[issue11908] Weird `slice.stop or sys.maxint`
by Ram Rachum July 11, 2013

July 11, 2013

New submission from Ram Rachum <cool-rr(a)cool-rr.com>: In the documentation for `itertools.islice` I see this line: it = iter(xrange(s.start or 0, s.stop or sys.maxint, s.step or 1)) Is it really okay to do `s.stop or sys.maxint`? I'm assuming this was targeting `None`, but what if `s.stop == 0`? And `s.step` could (pathologically) be `0` too, no? ---------- assignee: docs@python components: Documentation messages: 134276 nosy: cool-RR, docs@python priority: normal severity: normal status: open title: Weird `slice.stop or sys.maxint` type: behavior versions: Python 2.5, Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11908> _______________________________________

8 13

[issue12716] Reorganize os docs for files/dirs/fds
by Benjamin Peterson June 29, 2013

June 29, 2013

New submission from Benjamin Peterson <benjamin(a)python.org>: Right now many of the os function docs are split up into "Files and directories" and "file descriptor operations". This means, for example, that fchmod() and fchmodat() are in a different section than chmod(). It would make more sense to organize the docs such that functions that do the same thing are right next to each other. ---------- assignee: docs@python components: Documentation keywords: easy messages: 141820 nosy: benjamin.peterson, docs@python priority: low severity: normal status: open title: Reorganize os docs for files/dirs/fds versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12716> _______________________________________

7 9

[issue14015] surrogateescape largely missing from documentation
by Jim Jewett June 16, 2013

June 16, 2013

New submission from Jim Jewett <jimjjewett(a)gmail.com>: Recent discussion on the mailing lists and in http://bugs.python.org/issue13997 make it clear that the best way to get python2 results for "ASCII-in-the-parts-I-might-process-or-change" is to replace f = open(fname) with f = open(fname, encoding="ascii", errors="surrogateescape") Unfortunately, surrogateescape (let alone this recipe) is not easily discoverable. http://docs.python.org/dev/library/functions.html#open lists 5 error-handlers -- but not this one. It says that other error handlers are possible if they are registered with http://docs.python.org/dev/library/codecs.html#codecs.register_error but I haven't found a way to determine which error handlers are already registered. The codecs.register (as opposed to register_error) documentation does list it as a possible value, but that is the only reference. The other 5 error handlers are also available as module-level functions within the codecs module, and have their own documenation sections within http://docs.python.org/dev/library/codecs.html Neither help(open) nor import codecs; help(codecs) provides any hints of the existence of surrogateescape. Both explicitly suggest that it does not exist, by enumerating other values. ---------- assignee: docs@python components: Documentation, Unicode messages: 153359 nosy: Jim.Jewett, docs@python, ezio.melotti priority: normal severity: normal status: open title: surrogateescape largely missing from documentation versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14015> _______________________________________

5 5

[issue14009] Clearer documentation for cElementTree
by Éric Araujo May 20, 2013

May 20, 2013

New submission from Éric Araujo <merwok(a)netwok.org>: This patch should clarify how to use cElementTree usage, as well as improving indexing. ---------- assignee: docs@python components: Documentation messages: 153338 nosy: docs@python, eli.bendersky, eric.araujo priority: normal severity: normal stage: commit review status: open title: Clearer documentation for cElementTree versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________

4 13

[issue12825] Missing and incorrect link to a command line option.
by Kyle Simpson April 23, 2013

April 23, 2013

New submission from Kyle Simpson <illwhipyou(a)gmail.com>: The documentation for the runpy module has a link to the -m command line option. In version 2.7.2 of the docs, the link doesn't exist. http://docs.python.org/release/2.7/library/runpy.html http://docs.python.org/release/2.7.2/library/runpy.html If you run touch library/runpy.rst make html then the link is created, but with an anchor of "cmdoption-unittest-discover-m" instead of "cmdoption-m". http://docs.python.org/release/2.7.2/using/cmdline.html#cmdoption-unittest-… ---------- assignee: docs@python components: Documentation messages: 142797 nosy: Kyle.Simpson, docs@python priority: normal severity: normal status: open title: Missing and incorrect link to a command line option. versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12825> _______________________________________

2 3

[issue13510] Clarify that readlines() is not needed to iterate over a file
by Peter Otten April 15, 2013

April 15, 2013

New submission from Peter Otten <__peter__(a)web.de>: I've been looking at code on the tutor mailing list for some time, and for line in file.readlines(): ... is a common idiom there. I suppose this is because the readlines() method is easily discoverable while the proper way (iterate over the file object directly) is not. A note added to the readlines() documentation might help: """ You don't need the readlines() method to loop over the lines of a file. for line in file: process(line) consumes less memory and is often faster. """ ---------- assignee: docs@python components: Documentation messages: 148679 nosy: docs@python, potten priority: normal severity: normal status: open title: Clarify that readlines() is not needed to iterate over a file type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13510> _______________________________________

12 21

[issue13050] RLock support the context manager protocol but this is not documented
by Brian Brazil April 14, 2013

April 14, 2013

New submission from Brian Brazil <brian.brazil(a)gmail.com>: This is already documented: http://docs.python.org/library/threading.html#using-locks-conditions-and-se… ---------- nosy: +bbrazil _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13050> _______________________________________

6 5

compileall module: exclusion example is path separator-specific
by Paul A. Giannaros April 14, 2013

April 14, 2013

Hi, The docs for compileall give an example of compiling pyc files in a directory while excluding '.svn' subdirectories: compileall.compile_dir('Lib/', rx=re.compile('/[.]svn'), force=True) Neither this part nor documentation for the 'rx' attribute make clear that the paths searched with the regular expression will have OS specific separators. This example doesn't work on Windows, for example. I think the example should be explicit that the paths will contain the native separators (or it should use pathsep instead of '/', or maybe '[/\\]', to make it clearer in the example). Thanks, Paul

2 1

Bug in the Reference Data Model
by Ted Yin April 14, 2013

April 14, 2013

It's said that : When it would yield a class method object, it is transformed into a bound user-defined method object whose im_class and im_self attributes are both C. in the Reference <http://docs.python.org/reference/datamodel.html> And I did an EX. >>> class C(object) : ... @classmethod ... def cm(cls) : print cls ... >>> C.cm <bound method type.cm of <class '__main__.C'>> >>> C.cm.im_self <class '__main__.C'> >>> C.cm.im_class <type 'type'> It's not hard for me to understand the result. But unfortunately, in the reference, it's told that im_self should be *the same* as im_class. And in my opinion , 'im_self' shold be C, but im_class is 'type' since C's metaclass is type. So they're obviously *not* 'both C'. -- [This information is automatically generated] *ted.sybil* aka. *ymfoi* aka. *Ted Yin*

2 2