Mailman 3 January 2011 - docs

[issue9364] some problems with the documentation of pydoc
by Eli Bendersky April 19, 2014

April 19, 2014

New submission from Eli Bendersky <eliben(a)gmail.com>: The first paragraph in its documentation says: """ In the Python interpreter, do "from pydoc import help" to provide online help. Calling help(thing) on a Python object documents the object. """ Which is no longer accurate, because the help() function has long ago become a built-in. Below is an excerpt from Terry Reedy in a private email discussion on this subject, that raises more issues. --------------------------------------------- 1. The output from help(help) could be made more clear. The nature of 'help' has been a point of confusion. A recent python-list post asked something like "What is 'help'?" Now (with some parallel examples: >>> help(int) Help on class int in module builtins: class int(object) [snip] >>> help(1) Help on int object: class int(object) [snip] >>> help(help) Help on _Helper in module site object: class _Helper(builtins.object) | Define the built-in 'help'. | This is a wrapper around pydoc.help (with a twist). | | Methods defined here: | | __call__(self, *args, **kwds) | a. 'module site object' is nonsense, it should just be 'module site', except that to be parallel to what is done for other instances, it should be 'Help on _Helper object'. Why should help special-case itself (with a slightly garbled line?) Is that done in site._Helper or pydoc.help? However, it would be more helpful for all instances to give the location of the class when one asks for help on an instance, just as when one asks for help on the class itself. It is annoying to to have to repeat help(<classname>) just to get that info. So I would like to see "Help on instance of class int in module builtins:" "Help on instance of class _Helper in module site:" This would be a code patch to pydoc.help b. "This is a wrapper around pydoc.help" good so far "(with a twist)" thanks a lot. I think the comment should be either removed or explained. A reference manual should explain, not tease. Replace "Define the built-in 'help'." with something clearer and more accurate, such as "The name 'help' is injected in module builtins after being bound to an instance of this class.". Put this after, not before, the 'wrapper' line. A patch for site._Helper doc string. 2. Improve manual chapter for site module. a. It currently starts "Importing this module will append site-specific paths to the module search path." Add "inject 'help' into builtins and " after append. Then add a short explanation paragraph before the search path stuff. Something like "This module contains a class (_Helper) that wraps function pydoc.help. An instance of the class is bound to name 'help' in the builtins module." A recent discussion on pydev or maybe python-list (in the thread mentioned above?) implied that one could usefully make another instance of _Helper or maybe a subclass thereof. I did not pay enough attention, though, to really get it. b. It currently ends with "XXX Update documentation XXX document python -m site –user-base –user-site" ---------- assignee: docs@python components: Documentation messages: 111426 nosy: docs@python, eli.bendersky, tjreedy priority: normal severity: normal status: open title: some problems with the documentation of pydoc type: behavior versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________

9 21

[issue10481] subprocess PIPEs are byte streams
by Glenn Linderman April 14, 2014

April 14, 2014

New submission from Glenn Linderman <v+python(a)g.nevcal.com>: While http://bugs.python.org/issue2683 did clarify the fact that the .communicate API takes a byte stream as input, it is easy to miss the implication. Because Python programs start up with stdin as a text stream, it might be good to point out that some action may need to be taken to be sure that the receiving program expects a byte stream, or that the byte stream supplied should be in an encoding that the receiving program is expecting and can decode appropriately. No mention is presently made in the documentation for .communicate that its output is also a byte stream, and if text will correspond to whatever encoding is used by the sending program. ---------- assignee: docs@python components: Documentation messages: 121869 nosy: docs@python, v+python priority: normal severity: normal status: open title: subprocess PIPEs are byte streams versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10481> _______________________________________

4 5

[issue11009] urllib.splituser is not documented
by anatoly techtonik Oct. 8, 2013

Oct. 8, 2013

New submission from anatoly techtonik <techtonik(a)gmail.com>: I'm studying old code that uses urllib.splituser() call and can't find description of this function in Python 2.6.6 docs. ---------- assignee: docs@python components: Documentation messages: 127047 nosy: docs@python, techtonik priority: normal severity: normal status: open title: urllib.splituser is not documented versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11009> _______________________________________

6 8

[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

[issue8913] Document that datetime.__format__ is datetime.strftime
by Brett Cannon April 4, 2013

April 4, 2013

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

[issue10994] implementation details in sys module
by Maciej Fijalkowski Jan. 22, 2013

Jan. 22, 2013

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. Nov. 8, 2012

Nov. 8, 2012

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 Oct. 27, 2012

Oct. 27, 2012

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

[issue9767] Failures in json doc examples
by Terry J. Reedy Oct. 26, 2012

Oct. 26, 2012

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: I ran doctest on LibRef 17.2 json saved as .txt. There are 4 failures: 2 are clearly doc issues, the other 2 I do not know. I hope someone reads this who is already familiar DOC PATCHES dumps(2 + 1j, cls=ComplexEncoder) should be json.dumps(2 + 1j, cls=ComplexEncoder) and JSONEncoder().encode({"foo": ["bar", "baz"]}) should be json.JSONEncoder().encode({"foo": ["bar", "baz"]}) Needing similar additions in example code (not caught by doctest) are return JSONEncoder.default(self, o) for chunk in JSONEncoder().iterencode(bigobject): Those fixes leave 2 failures I an unclear about and hope a json expert will comment on. 1.''' Failed example: print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4)) Expected: { "4": 5, "6": 7 } Got: { "4": 5, "6": 7 } ''' The difference is that json puts a trailing space after '5,'. Should it? or should one be added to the doc? 2. ''' Failed example: list(ComplexEncoder().iterencode(2 + 1j)) Expected: ['[', '2.0', ', ', '1.0', ']'] Got: ['[2.0', ', 1.0', ']'] ''' Without knowing how the default iterencode interacts with the overwridden .default() method, I have no idea. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 115512 nosy: docs@python, terry.reedy priority: normal severity: normal status: open title: Failures in json doc examples type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9767> _______________________________________

3 4

[issue10405] IDLE breakpoint facility undocumented
by Ned Deily Oct. 20, 2012

Oct. 20, 2012

New submission from Ned Deily <nad(a)acm.org>: In neither the IDLE section of the Library Reference nor in IDLE's own help file is there any documentation on how to use its breakpoint capability. Since the menu options only appear if the user knows to Right-click (or Control-click on OS X - see issue10404), it would be easy for a user to never realize that the breakpoint capability exists. ---------- assignee: docs@python components: Documentation, IDLE messages: 121121 nosy: docs@python, kbk, ned.deily, taleinat, terry.reedy priority: normal severity: normal status: open title: IDLE breakpoint facility undocumented versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10405> _______________________________________

5 9