Mailman 3 April 2011 - docs

[issue11585] Documentation 1.8 shows Python 2 example
by Clive Darke 07 Oct '13

07 Oct '13

New submission from Clive Darke <clive.darke(a)qa.com>: Python 3.2 version attached ---------- assignee: docs@python components: Documentation files: parrot.c messages: 131246 nosy: cdarke, docs@python priority: normal severity: normal status: open title: Documentation 1.8 shows Python 2 example versions: Python 3.1, Python 3.2 Added file: http://bugs.python.org/file21267/parrot.c _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11585> _______________________________________

2 2

[issue11807] Documentation of add_subparsers lacks information about parametres
by Filip Gruszczyński 06 Oct '13

06 Oct '13

New submission from Filip Gruszczyński <gruszczy(a)gmail.com>: In argparse documentation parametres of add_subparsers are not listed. And yet there are some really useful parametres like parser_class. It would be useful, it they were described there well and one wouldn't have to look into the code to find them :-) I'll be happy to provide documentation patch tomorrow. ---------- assignee: docs@python components: Documentation messages: 133379 nosy: docs@python, gruszczy priority: normal severity: normal status: open title: Documentation of add_subparsers lacks information about parametres versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11807> _______________________________________

3 8

[issue11163] iter() documentation code doesn't work
by Michael Grazebrook 12 Sep '13

12 Sep '13

New submission from Michael Grazebrook <michael(a)grazebrook.com>: This code fragment from the documentation of iter() doesn't work as intended. Change "STOP" to "STOP\n". Maybe also check for EOF as it hangs. with open("mydata.txt") as fp: for line in iter(fp.readline, "STOP"): process_line(line) Or maybe this makes a better example because it's clearer wha'ts going on: square_generator = (i * i for i in range(100000)) for n in iter( square_generator.next, 144): print n ---------- assignee: docs@python components: Documentation messages: 128238 nosy: docs@python, mgrazebrook priority: normal severity: normal status: open title: iter() documentation code doesn't work type: behavior versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11163> _______________________________________

6 10

[issue10434] Document the rules for "public names"
by Alexander Belopolsky 01 Aug '13

01 Aug '13

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 11 Jul '13

11 Jul '13

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

[issue8913] Document that datetime.__format__ is datetime.strftime
by Brett Cannon 04 Apr '13

04 Apr '13

New submission from Brett Cannon <brett(a)python.org>: Documenting that would help get people using datetime objects with string.format more. ---------- assignee: docs@python components: Documentation keywords: easy messages: 107179 nosy: brett.cannon, docs@python priority: low severity: normal status: open title: Document that datetime.__format__ is datetime.strftime versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8913> _______________________________________

12 28

[issue11367] xml.etree.ElementTree.find(all): docs are wrong
by anatoly techtonik 12 Mar '13

12 Mar '13

New submission from anatoly techtonik <techtonik(a)gmail.com>: ElementTree.find(path) docs say: "Finds the first toplevel element with given tag. Same as getroot().find(path). path is the element to look for." That's not true. path can take the form of "//tag" to find any child element with given tag, not strictly top level. ---------- assignee: docs@python components: Documentation messages: 129847 nosy: docs@python, techtonik priority: normal severity: normal status: open title: xml.etree.ElementTree.find(all): docs are wrong versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________

5 19

[issue10994] implementation details in sys module
by Maciej Fijalkowski 22 Jan '13

22 Jan '13

New submission from Maciej Fijalkowski <fijall(a)gmail.com>: sys module documentation (as it is online) has some things that in my opinion should be marked as implementation details, but are not. Feel free to counter why not. Some of them has info it should be used for specialized purposes only, but IMO it's not the same as not mandatory for other implementations. Temporary list: _clear_type_cache dllhandle getrefcount getdlopenflags (?) getsizeof - it might be not well defined on other implementations setdlopenflags api_version ---------- assignee: docs@python components: Documentation messages: 126925 nosy: docs@python, fijall priority: normal severity: normal status: open title: implementation details in sys module type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10994> _______________________________________

8 17

[issue10358] Doc styles for print should only use dark colors
by Fred L. Drake, Jr. 08 Nov '12

08 Nov '12

New submission from Fred L. Drake, Jr. <fdrake(a)acm.org>: The HTML version of the documentation should include style settings for printing that use fairly dark colors, so that printed copies of pages are more readable. Using a printer that reduces colors to grays causes the light colors in code examples (or inlined references to classes and the like) to nearly drop out, making the result very painful to read. ---------- assignee: docs@python components: Documentation keywords: easy messages: 120741 nosy: docs@python, fdrake priority: normal severity: normal stage: needs patch status: open title: Doc styles for print should only use dark colors type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10358> _______________________________________

3 3

[issue8996] Add a default role to allow writing bare `len` instead of :func:`len`
by Éric Araujo 27 Oct '12

27 Oct '12

New submission from Éric Araujo <merwok(a)netwok.org>: Following a discussion on IRC: <birkenfeld> I would even prefer having more of just `object` instead of :func:`object` or :class:`object` I think it would be feasible to write a reST role that would use inspect or pydoc to find the type. It would not violate “In the face of ambiguity, refuse the temptation to guess” if it only resolves `somebuiltin` and `some.fully.qualified.name`. Cons: People unfamiliar with reST might confuse ``code`` with `name`; interpreting the role may prove non-trivial (either requiring importing Python module to introspect them, or keeping a mapping of names→types in some file). Thoughts? ---------- assignee: docs@python components: Documentation messages: 107790 nosy: docs@python, merwok priority: normal severity: normal status: open title: Add a default role to allow writing bare `len` instead of :func:`len` type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8996> _______________________________________

5 9