Mailman 3 April 2011 - docs

[issue10503] os.getuid() documentation should be clear on what kind of uid it is referring
by Giampaolo Rodola' June 7, 2014

June 7, 2014

New submission from Giampaolo Rodola' <g.rodola(a)gmail.com>: http://docs.python.org/library/os.html#os.getuid os.getuid() documentation just states: > Return the current process’s user id. It is not clear, however, whether "user id" refers to real, effective or saved user id. As per: http://linux.about.com/library/cmd/blcmdl2_getuid.htm ...it should refer to _real_ user id. ---------- assignee: docs@python components: Documentation messages: 122117 nosy: docs@python, giampaolo.… [View More]

5 6

[issue9307] Py_TPFLAGS_LONG_SUBCLASS is not documented
by Alexander Belopolsky April 28, 2014

April 28, 2014

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: … [View More]

6 8

[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. ---------------------------------------… [View More]------ 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> _______________________________________ [View Less]

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 … [View More]

4 5

[issue11481] The copy module already uses copyreg
by Daniel Urban March 24, 2014

March 24, 2014

New submission from Daniel Urban <urban.dani+py(a)gmail.com>: In the copyreg documentation there is this sentence: "The copy module is likely to use this in the future as well." (http://docs.python.org/dev/py3k/library/copyreg) But the copy module already uses the copyreg module. ---------- assignee: docs@python components: Documentation messages: 130732 nosy: docs@python, durban priority: normal severity: normal status: open title: The copy module already uses copyreg versions: Python … [View More]

5 5

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous
by Ryan Kelly March 16, 2014

March 16, 2014

New submission from Ryan Kelly <ryan(a)rfk.id.au>: The docs for HTTPConnection.set_tunnel(host,port) are ambiguous. They simply say "Set the host and the port for HTTP Connect Tunnelling". But should I specify the address of the server *through* which I want to tunnel, or the address of the *endpoint* of the tunnel? Turns out it's the latter, but I just wasted an hour "debugging" thinking it was the former :-( Attached is a simple doc patch to try to clarify this issue. ---------- … [View More]

8 14

[issue11379] Remove "lightweight" from minidom description
by Stefan Behnel Dec. 22, 2013

Dec. 22, 2013

New submission from Stefan Behnel <scoder(a)users.sourceforge.net>: http://docs.python.org/library/xml.dom.minidom.html presents MiniDOM as a "Lightweight DOM implementation". The word "lightweight" is easily misunderstood as meaning "efficient" or "memory friendly". MiniDOM is well known to be neither of the two. The first paragraph then continues: """ xml.dom.minidom is a light-weight implementation of the Document Object Model interface. It is intended to be simpler than the full … [View More]

12 66

[issue11120] threading.Thread.daemon Documentation Incomplete
by cardinalbiggles Oct. 13, 2013

Oct. 13, 2013

New submission from cardinalbiggles <jmandersen(a)gmail.com>: In the threading module, the documentation for Thread.isDaemon()/Thread.setDaemon() indicates they are the old API for Thread.daemon, which does not indicate the version in which it was introduced (2.6 I believe). Additionally, the documentation for Thread.setDaemon() should at least include the daemonic parameter, if not the full usage documentation for those targeting older versions. Targeting Python 2.4, and being unable … [View More]

2 1

[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> &… [View More]

6 8

[issue11789] Extend upon metaclass/type class documentation, here: zope.interface and usage of instances of classes as base classes
by Carsten Klein Oct. 6, 2013

Oct. 6, 2013

New submission from Carsten Klein <carsten.klein(a)axn-software.de>: In zope.interface, you have something the following construct: class InterfaceBase: pass Interface = InterfaceBase() Using the above Interface as a derivation base for your own classes, will make that instance a type derived class: class IFoo(Interface): pass type(IFoo) -> Interface type(Interface) -> type I wonder why this behavior is not documented in the official documentation, or at least, I was … [View More]

2 2