Mailman 3 September 2010 - docs

[issue9307] Py_TPFLAGS_LONG_SUBCLASS is not documented
by Alexander Belopolsky 28 Apr '14

28 Apr '14

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: Is there a reason for not documenting Py_TPFLAGS_LONG_SUBCLASS (Py_TPFLAGS_INT_SUBCLASS in 2.x)? This flag is used in PyLong_Check, but neither this flag or its inheritance properties are explained anywhere in the docs. See also issue5476. ---------- assignee: docs@python components: Documentation messages: 110787 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: Py_TPFLAGS_LONG_SUBCLASS is not documented type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9307> _______________________________________

6 8

[issue9364] some problems with the documentation of pydoc
by Eli Bendersky 19 Apr '14

19 Apr '14

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

[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

[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

[issue9767] Failures in json doc examples
by Terry J. Reedy 26 Oct '12

26 Oct '12

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

[issue8652] Minor improvements to the "Handling Exceptions" part of the tutorial
by Marien Zwart 07 Jun '12

07 Jun '12

New submission from Marien Zwart <m_zwart(a)123mail.org>: Based on questions asked on freenode's #python by people reading the tutorial I would like to suggest two improvements to http://docs.python.org/tutorial/errors.html#handling-exceptions : - Mention the older "except SomeException, e:" syntax too, not just "except SomeException as e:". I have had people ask me to help them upgrade to a newer python because they thought their version of python did not support catching exception instances (their distro python being 2.5). A big fat warning that they're reading the Python 2.6 tutorial (with links to older tutorials) may also work. - Mention "except IOError as e" before mentioning "except IOError as (errno, strerror):". The latter is an advanced and relatively unusual trick, combining regular exception catching and unpacking. Those two concepts need to be explained before the combination is. I have had people ask me how to do "except KeyError as (key, insert_something_here):" because they thought they *always* needed those parens there. (perhaps just not mentioning unpacking here at all, using "except IOError as e:" and then using e.errno would make more sense, especially since "except IOError as (errno, strerror):" is a SyntaxError in python 3 and up (because of the unpacking) and python 2.5.x and down (because of the "as")...) I can try to write a patch to the documentation if you like. ---------- assignee: docs@python components: Documentation messages: 105218 nosy: docs@python, marienz priority: normal severity: normal status: open title: Minor improvements to the "Handling Exceptions" part of the tutorial _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8652> _______________________________________

4 6

[issue8617] Non-existent variables documented
by Dave Abrahams 09 May '12

09 May '12

New submission from Dave Abrahams <dave(a)boostpro.com>: http://docs.python.org/library/site.html#module-site mentions two variables that don't appear in my Python 2.6.5 installation's site module: PYTHONNOUSERSITE New in version 2.6. PYTHONUSERBASE New in version 2.6. ---------- assignee: docs@python components: Documentation messages: 104985 nosy: dabrahams, docs@python priority: normal severity: normal status: open title: Non-existent variables documented versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8617> _______________________________________

6 13

[issue9442] Update sys.version doc
by Éric Araujo 09 Feb '12

09 Feb '12

New submission from Éric Araujo <merwok(a)netwok.org>: Attaching a patch to edit mention of “build number” in library/sys. I also don’t understand “The first three characters are used to identify the version in the installation directories (where appropriate on each platform)”, maybe someone who does could enlighten me. If #5778 is rejected, the doc will need another update to mention that there may be a newline in sys.version. ---------- assignee: docs@python components: Documentation files: sys.version1.diff keywords: patch messages: 112189 nosy: docs@python, merwok priority: normal severity: normal stage: patch review status: open title: Update sys.version doc versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file18289/sys.version1.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9442> _______________________________________

4 9

[issue9021] no copy.copy problem description
by anatoly techtonik 09 Feb '12

09 Feb '12

New submission from anatoly techtonik <techtonik(a)gmail.com>: `copy` module covers very important aspect of Python programming. However its documentation doesn't provide any intro or overview of this problem starting right from details. When people meet `copy` construction in the code - the refer to module documentation and its doesn't completely answer two basic questions they have: 1. why copy module is needed (i.e. what's the problem with var assignment) 2. when and where it should be used ---------- assignee: docs@python components: Documentation messages: 108069 nosy: docs@python, techtonik priority: normal severity: normal status: open title: no copy.copy problem description versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9021> _______________________________________

5 10

[issue9637] docs do not say that urllib uses HTTP_PROXY
by Kirikaza 10 Jan '12

10 Jan '12

New submission from Kirikaza <kirikaza(a)rambler.ru>: In practice urllib reads HTTP_PROXY firstly and then if HTTP_PROXY is empty urllib reads http_proxy. Documentation (http://docs.python.org/library/urllib.html) says nothing about HTTP_PROXY. Maybe it affects all the versions of Python. ---------- assignee: docs@python components: Documentation messages: 114319 nosy: docs@python, kirikaza priority: normal severity: normal status: open title: docs do not say that urllib uses HTTP_PROXY versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9637> _______________________________________

5 11