Mailman 3 December 2012 - docs

[issue11975] Fix intersphinx-ing of built-in types (list, int, ...)
by Jonas H. April 28, 2021

April 28, 2021

New submission from Jonas H. <jonas(a)lophus.org>: Intersphinx-ing of int, list, float, ... should work with ":class:`int`" (list, float, ...). Also, intersphinx-ing list methods, e.g. ":meth:`list.insert`", should work. ---------- assignee: docs@python components: Documentation messages: 134923 nosy: docs@python, jonash priority: normal severity: normal status: open title: Fix intersphinx-ing of built-in types (list, int, ...) _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11975> _______________________________________

11 50

[issue16386] imp.find_module does not specify registry key it searches on windows
by Jan Duzinkiewicz April 24, 2021

April 24, 2021

New submission from Jan Duzinkiewicz: quote from http://docs.python.org/3/library/imp.html#imp.find_module: "...on some systems some other places are looked in as well (on Windows, it looks in the registry which may point to a specific file)." I actually didn't know the registry key is listed in "using Python on Window" guide until I grepped for PythonCore (which kind of requires to know the key already) - so I'm submitting a patch that cross references find_module docs and using Python on Windows guide. ---------- assignee: docs@python components: Documentation files: import_nt_reg.patch keywords: patch messages: 174508 nosy: dhgmgn, docs@python priority: normal severity: normal status: open title: imp.find_module does not specify registry key it searches on windows versions: Python 2.7, Python 3.3 Added file: http://bugs.python.org/file27843/import_nt_reg.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16386> _______________________________________

4 5

[issue11977] Document int.conjugate, .denominator, ...
by Jonas H. April 23, 2021

April 23, 2021

New submission from Jonas H. <jonas(a)lophus.org>: Various `int` attributes and methods seem undocumented (at least it does not work to intersphinx them): * .conjugate * .denominator * .imag * .numerator * .real ---------- assignee: docs@python components: Documentation messages: 134926 nosy: docs@python, jonash priority: normal severity: normal status: open title: Document int.conjugate, .denominator, ... versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

6 8

[issue14189] Documentation for some C APIs is missing clear specification of the type of reference they return
by Baruch Sterin March 21, 2021

March 21, 2021

New submission from Baruch Sterin <python(a)bsterin.com>: In addition to the description text, most C API functions have a one-line, emphasized specification whether they return a new or a borrowed reference. (e.g. 'Return value: New reference.'). The following API functions are missing that. Some of them, like PyMemoryView_FromBuffer(), have descriptions that are clear, but it would still be nice to have an unambiguous statement like most other API functions have. The list has been generated automatically, so it might contain some errors. Doc/c-api/arg.rst: Py_VaBuildValue Doc/c-api/buffer.rst: PyMemoryView_FromBuffer Doc/c-api/buffer.rst: PyMemoryView_FromObject Doc/c-api/buffer.rst: PyMemoryView_GetContiguous Doc/c-api/bytearray.rst: PyByteArray_Concat Doc/c-api/bytearray.rst: PyByteArray_FromObject Doc/c-api/bytearray.rst: PyByteArray_FromStringAndSize Doc/c-api/code.rst: PyCode_New Doc/c-api/codec.rst: PyCodec_BackslashReplaceErrors Doc/c-api/codec.rst: PyCodec_Decode Doc/c-api/codec.rst: PyCodec_Decoder Doc/c-api/codec.rst: PyCodec_Encode Doc/c-api/codec.rst: PyCodec_Encoder Doc/c-api/codec.rst: PyCodec_IgnoreErrors Doc/c-api/codec.rst: PyCodec_IncrementalDecoder Doc/c-api/codec.rst: PyCodec_IncrementalEncoder Doc/c-api/codec.rst: PyCodec_LookupError Doc/c-api/codec.rst: PyCodec_ReplaceErrors Doc/c-api/codec.rst: PyCodec_StreamReader Doc/c-api/codec.rst: PyCodec_StreamWriter Doc/c-api/codec.rst: PyCodec_StrictErrors Doc/c-api/codec.rst: PyCodec_XMLCharRefReplaceErrors Doc/c-api/exceptions.rst: PyUnicodeDecodeError_Create Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetEncoding Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetObject Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetReason Doc/c-api/exceptions.rst: PyUnicodeEncodeError_Create Doc/c-api/exceptions.rst: PyUnicodeTranslateError_Create Doc/c-api/float.rst: PyFloat_GetInfo Doc/c-api/import.rst: PyImport_GetImporter Doc/c-api/import.rst: PyImport_ImportModuleNoBlock Doc/c-api/import.rst: _PyImport_FindExtension Doc/c-api/import.rst: _PyImport_FixupExtension Doc/c-api/init.rst: PyEval_GetCallStats Doc/c-api/int.rst: PyInt_FromSize_t Doc/c-api/long.rst: PyLong_FromSize_t Doc/c-api/long.rst: PyLong_FromSsize_t Doc/c-api/number.rst: PyNumber_Index Doc/c-api/number.rst: PyNumber_ToBase Doc/c-api/object.rst: PyObject_Bytes Doc/c-api/object.rst: PyObject_GenericGetAttr Doc/c-api/unicode.rst: PyUnicode_AsUTF32String Doc/c-api/unicode.rst: PyUnicode_DecodeMBCSStateful Doc/c-api/unicode.rst: PyUnicode_DecodeUTF32 Doc/c-api/unicode.rst: PyUnicode_DecodeUTF32Stateful Doc/c-api/unicode.rst: PyUnicode_DecodeUTF7 Doc/c-api/unicode.rst: PyUnicode_DecodeUTF7Stateful Doc/c-api/unicode.rst: PyUnicode_EncodeUTF32 Doc/c-api/unicode.rst: PyUnicode_EncodeUTF7 Doc/c-api/veryhigh.rst: PyEval_EvalCodeEx Doc/c-api/veryhigh.rst: PyEval_EvalFrame Doc/c-api/veryhigh.rst: PyEval_EvalFrameEx ---------- assignee: docs@python components: Documentation messages: 154877 nosy: baruch.sterin, docs@python priority: normal severity: normal status: open title: Documentation for some C APIs is missing clear specification of the type of reference they return type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14189> _______________________________________

9 9

[issue15533] subprocess.Popen(cwd) documentation
by Chris Jerdonek March 16, 2021

March 16, 2021

New submission from Chris Jerdonek: The sentence describing Popen()'s cwd argument in the subprocess documentation seems reversed to me: http://docs.python.org/dev/library/subprocess.html#subprocess.Popen It says, "If cwd is not None, the child’s current directory will be changed to cwd before it is executed. Note that this directory is not considered when searching the executable, so you can’t specify the program’s path relative to cwd." However, when cwd is not None, it seems like you *must* specify the program's path relative to cwd. For example, when running a script containing the following using `./python.exe` from a source checkout-- p = Popen(['./python.exe', '-V'], stdout=PIPE, stderr=PIPE, cwd='temp') you get an: "OSError: [Errno 2] No such file or directory." In contrast, when you *do* specify the program's path relative to cwd, it works-- p = Popen(['../python.exe', '-V'], stdout=PIPE, stderr=PIPE, cwd='temp') Issue 6374 seems to have made the same point in its second bullet, but the issue was closed without addressing that part of it. ---------- assignee: docs@python components: Documentation keywords: easy messages: 167194 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: subprocess.Popen(cwd) documentation versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15533> _______________________________________

11 51

[issue15097] Improving wording on the thread-safeness of import
by Merlijn van Deen March 9, 2021

March 9, 2021

New submission from Merlijn van Deen <valhallasw(a)gmail.com>: http://docs.python.org/library/threading.html#importing-in-threaded-code Currently, the documentation states "Firstly, other than in the main module, an import should not have the side effect of spawning a new thread and then waiting for that thread in any way. Failing to abide by this restriction can lead to a deadlock if the spawned thread directly or indirectly attempts to import a module." which, I think, fails to make the main point: a call to import acquires the import lock. A call to import from a second thread will thus block. As such, I would suggest rephrasing it to something like: "Firstly, an import acquires the import lock for that thread. Therefore, the import should not have the side effect of waiting for a different thread in any way, as this can lead to a deadlock if that thread directly or indirectly attempts to import a module." There are two additional points that might be interesting to note: (1) Any module can be imported. If the import causes a deadlock, that is a bad thing. Every module *will* be imported by tools such as nosetests. (1b) so: never, ever, have code that causes locks in a different thread in module level code witout 'if __name__=="__main__" ' blocks? (2) The lock is also acquired if a module has already been imported. For instance, in import sys # (1) def f(): import sys # (2) the import lock is acquired in (1) /and/ (2). Adding example code and/or a flow diagram might be a bit too much, but it does clarify how easy it is to make this mistake. See the attached for an example (both a simple example script, as well as a flow diagram explaining what happens). ---------- assignee: docs@python components: Documentation files: deadlock.py messages: 163068 nosy: docs@python, valhallasw priority: normal severity: normal status: open title: Improving wording on the thread-safeness of import type: enhancement Added file: http://bugs.python.org/file26037/deadlock.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15097> _______________________________________

3 6

[issue8557] subprocess portability issue
by Dave Abrahams March 5, 2021

March 5, 2021

New submission from Dave Abrahams <dave(a)boostpro.com>: On POSIX systems, the PATH environment variable is always used to look up directory-less executable names passed as the first argument to Popen(...), but on Windows, PATH is only considered when shell=True is also passed. Actually I think it may be slightly weirder than that when shell=False, because the following holds for me: C:\>rem ##### Prepare minimal PATH ##### C:\>set "PATH=C:\Python26\Scripts;C:\Python26;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem" C:\>rem ##### Prepare a minimal, clean environment ##### C:\>virtualenv --no-site-packages e:\zzz New python executable in e:\zzz\Scripts\python.exe Installing setuptools................done. C:\>rem ##### Show that shell=True makes the difference in determining whether PATH is respected ##### C:\>python Python 2.6.5 (r265:79096, Mar 19 2010, 18:02:59) [MSC v.1500 64 bit (AMD64)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> import subprocess >>> subprocess.Popen(['python', '-c', 'import sys; print sys.executable']) <subprocess.Popen object at 0x0000000001DBE080> >>> C:\Python26\python.exe >>> subprocess.Popen(['python', '-c', 'import sys; print sys.executable'], env={'PATH':r'e:\zzz\Scripts'}) <subprocess.Popen object at 0x0000000001F05A90> >>> C:\Python26\python.exe >>> subprocess.Popen(['python', '-c', 'import sys; print sys.executable'], env={'PATH':r'e:\zzz\Scripts'}, shell=True) <subprocess.Popen object at 0x0000000001F05B00> >>> e:\zzz\Scripts\python.exe That is, it looks like the environment at the time Python is invoked is what counts unless I pass shell=True. I don't even seem to be able to override this behavior by changing os.environ: you can clear() it and pass env={} and subprocess.Popen(['python']) still succeeds. This is a very important problem for portable code and one that took me hours to suss out. I think: a) the current behavior needs to be documented b) it needs to be fixed if possible c) otherwise, shell=True should be the default ---------- assignee: docs@python components: Documentation messages: 104422 nosy: dabrahams, docs@python priority: normal severity: normal status: open title: subprocess portability issue type: behavior versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8557> _______________________________________

8 23

[issue16272] C-API documentation clarification for tp_dictoffset
by Chris Colbert March 5, 2021

March 5, 2021

New submission from Chris Colbert: The documentation of the tp_dictoffset is a bit unclear when describing the responsibilities of a base type with a nonzero tp_dictoffset. http://docs.python.org/c-api/typeobj.html I feel there should some statement to the effect of: """ If a type defines a nonzero tp_dictoffset, that type is responsible for defining a `__dict__` slot as part of the tp_getset structures. Failure to do so will result in the dict being inaccesible from Python via `obj.__dict__` from instances of the type or subtypes. """ The reasoning is twofold: 1) `PyType_Ready` does not add the default getset members like `type_new` does. This prevents the instances of the type itself from retrieving `obj.__dict__` 2) `type_new` will provide the default `subtype_dict` getset member for subclasses, but this calls `get_builtin_base_with_dict` which will resolve to the most base type which is not heap allocated; in this case, the C type. Since this type has no `__dict__` getset member, the lookup fails. Adding a bit of verbage about this "gotcha" would likely save some headaches in the future. ---------- assignee: docs@python components: Documentation messages: 173222 nosy: Chris.Colbert, docs@python priority: normal severity: normal status: open title: C-API documentation clarification for tp_dictoffset versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16272> _______________________________________

6 7

[issue12594] Docs for py3k still refer to "MacPython 2.5 folder"
by Christoph Schindler March 4, 2021

March 4, 2021

New submission from Christoph Schindler <hop(a)30hopsmax.at>: In http://docs.python.org/py3k/using/mac.html#getting-and-installing-macpython and http://docs.python.org/py3k/using/mac.html#distributing-python-applications… . ---------- assignee: docs@python components: Documentation messages: 140744 nosy: docs@python, hop priority: normal severity: normal status: open title: Docs for py3k still refer to "MacPython 2.5 folder" versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12594> _______________________________________

7 11

[issue13368] Possible problem in documentation of module subprocess, method send_signal
by Eli Bendersky Feb. 24, 2021

Feb. 24, 2021

New submission from Eli Bendersky <eliben(a)gmail.com>: docs@ list report by Daniel Dieterle: in the documentation (http://docs.python.org/library/subprocess.html#subprocess.Popen.send_signal) is a bug. CTRL_C_EVENT can not be sent to processes started with a creationflags parameter which includes CREATE_NEW_PROCESS_GROUP. Why can be read in the msdn documentation http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155%28v=vs.85%… . A workaround using CTRL_C_EVENT nevertheless is described here: http://stackoverflow.com/questions/7085604/sending-c-to-python-subprocess-o… -- I do not know why the subprocess.CREATE_NEW_PROCESS_GROUP parameter was introduced. But it is useless for terminating a process with os.kill() in combination with signal.SIGTERM, which corresponds to a CTRL-C-EVENT. A CTRL-C-EVENT is only forwarded to the process if the process group is zero. Therefore the Note in the documentation on Popen.send_signal() is wrong. ---------- assignee: docs@python components: Documentation messages: 147272 nosy: docs@python, eli.bendersky priority: normal severity: normal status: open title: Possible problem in documentation of module subprocess, method send_signal versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13368> _______________________________________

4 6

[issue13433] String format documentation contains error regarding %g
by Christian Iversen Feb. 18, 2021

Feb. 18, 2021

New submission from Christian Iversen <ci(a)sikkerhed.org>: The documentation for string format options state that both %f, %g and %e default to 6 digits after the decimal point. In fact, %g always seems to use 5 digits by default: >>> "%g" % 2.1234567 '2.12346' >>> "%f" % 2.1234567 '2.123457' >>> "%e" % 2.1234567 '2.123457e+00' But something much more insidious is wrong, because even when explicitly told how many digits to have, %g is one off: >>> "%.6g" % 2.1234567 '2.12346' >>> "%.6f" % 2.1234567 '2.123457' >>> "%.6e" % 2.1234567 '2.123457e+00' This can't be right? ---------- assignee: docs@python components: Documentation messages: 147940 nosy: Christian.Iversen, docs@python priority: normal severity: normal status: open title: String format documentation contains error regarding %g type: behavior versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13433> _______________________________________

6 11

[issue8595] Unexpected default timeout in http-client-related libraries
by Julian Dec. 28, 2020

Dec. 28, 2020

New submission from Julian <python_org(a)somethinkodd.com>: Since Python 2.6, httplib has offered a timeout parameter for fetches. As the documentation explains, if this parameter is not provided, it uses the global default. What the document doesn't explain is httplib builds on top of the socket library. The socket library has a default timeout of None (i.e. forever). This may be an appropriate default for general sockets, but it is a poor default for httplib; typical http clients would use a timeout in the 2-10 second range. This problem is propagated up to urllib2, which sits on httplib, and further obscures that the default might be unsuitable. >From an inspection of the manuals, Python 3.0.1 suffers from the same problem except, the names have changed. urllib.response sits on http.client. I, for one, made a brutal mistake of assuming that the "global default" would be some reasonable default for fetching web pages; I didn't have any specific timeout in mind, and was happy for the library to take care of it. Several million successful http downloads later, my server application thread froze waiting forever when talking to a recalcitrant web-server. I imagine others have fallen for the same trap. While an ideal solution would be for httplib and http.client to use a more generally acceptable default, I can see it might be far too late to make such a change without breaking existing applications. Failing that, I would recommend that the documentation for httplib, urllib, urllib2, http.client and urllib.request (+ any other similar libraries sitting on socket? FTP, SMTP?) be changed to highlight that the default global timeout, sans deliberate override, is to wait a surprisingly long time. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 104763 nosy: docs@python, oddthinking priority: normal severity: normal status: open title: Unexpected default timeout in http-client-related libraries type: behavior versions: Python 2.6, Python 2.7, Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8595> _______________________________________

5 8

[issue8822] datetime naive and aware types should have a well-defined definition that can be cross-referenced
by anatoly techtonik Dec. 28, 2020

Dec. 28, 2020

New submission from anatoly techtonik <techtonik(a)gmail.com>: 'naive' and 'aware' are key datetime types - they need a proper definition and anchor for crossrefences. If you take a look at http://docs.python.org/library/datetime.html - the definition of distinction between them is too vague and this seeds of uncertainty grow through the rest of the doc. It is not said how to make non-naive object, how to detect if object of naive or aware. All this stuff is very important for troubleshooting datetims issues in Python projects. It needs a proper documentation. ---------- assignee: docs@python components: Documentation messages: 106524 nosy: docs@python, techtonik priority: normal severity: normal status: open title: datetime naive and aware types should have a well-defined definition that can be cross-referenced _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8822> _______________________________________

6 15

[issue14586] TypeError: truncate() takes no keyword arguments
by Guy Taylor Dec. 15, 2020

Dec. 15, 2020

New submission from Guy Taylor <thebigguy.co.uk(a)gmail.com>: The Python docs suggest that io.IOBase.truncate' should take a keyword argument of 'size'. However this causes a 'TypeError': TypeError: truncate() takes no keyword arguments Suggest that the docs are changed to 'truncate(size)' or CPython is changed to allow the keyword. http://docs.python.org/py3k/library/io.html?highlight=truncate#io.IOBase.tr… http://docs.python.org/library/io.html?highlight=truncate#io.IOBase.truncate ---------- assignee: docs@python components: Documentation, Interpreter Core files: test.py messages: 158308 nosy: TheBiggerGuy, docs@python priority: normal severity: normal status: open title: TypeError: truncate() takes no keyword arguments type: behavior versions: Python 2.7, Python 3.2 Added file: http://bugs.python.org/file25219/test.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14586> _______________________________________

6 15

[issue15104] abusive language in __name__ description
by anatoly techtonik Dec. 1, 2020

Dec. 1, 2020

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/__main__.html "It is this environment in which the idiomatic “conditional script” stanza causes a script to run" ?!? ---------- assignee: docs@python components: Documentation messages: 163140 nosy: docs@python, techtonik priority: normal severity: normal status: open title: abusive language in __name__ description _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

12 28

[issue13341] Incorrect documentation for "u" PyArg_Parse format unit
by Ilya Novoselov Nov. 30, 2020

Nov. 30, 2020

New submission from Ilya Novoselov <ilya.novoselov(a)gmail.com>: Documentation states that u format unit returns "buffer of 16-bit Unicode (UTF-16) data" while it returns pointer to internal buffer of unicode data, which is either UCS-16 or UCS-32 http://docs.python.org/c-api/arg.html ---------- assignee: docs@python components: Documentation, Unicode messages: 147002 nosy: Ilya.Novoselov, docs@python, ezio.melotti priority: normal severity: normal status: open title: Incorrect documentation for "u" PyArg_Parse format unit type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13341> _______________________________________

7 9

[issue13875] cmd: no user documentation
by anatoly techtonik Nov. 17, 2020

Nov. 17, 2020

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/cmd.html# Documentation for cmd module is poor to explain the value of this module to users. Intro is too abstract - phrase "simple framework for writing line-oriented command interpreters" doesn't mean much. Perhaps word "interactive" is missing? So, there is no part explaining the what cmd does exactly (intro fails) and no part explaining the main principle - How exactly does this framework allows to do this in a simple way? (I guess reference part under 'Cmd objects -> Cmd.cmdloop([intro]) -> p[4]` does that, but it is not the place you'd usually expect this info. At the very least what could be done is a link to Doug's tutorial http://www.doughellmann.com/PyMOTW/cmd/ ---------- assignee: docs@python components: Documentation messages: 152010 nosy: docs@python, techtonik priority: normal severity: normal status: open title: cmd: no user documentation _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13875> _______________________________________

4 6

[issue9538] Replace confusing pseudoname 'object' in special methods section.
by Terry J. Reedy Nov. 17, 2020

Nov. 17, 2020

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: In 3.3. Special method names, 'object' is used as a pseudo class name to prefix all the special method entries. This conflicts with the usual two Python meanings. 1. 'object' is the name of a specific class. So the entry for object.__getattribute__(self, name) says to avoid circularity by calling object.__getattribute__(self, name), which looks circular and requires a bit a mental work by the reader to properly understand. Ditto for object.__setattr__(self, name, value) calling object.__setattr__(self, name, value) 2. Non-specifically, 'object' is usually understood to mean any Python object, not just a class. But the signatures as written require that 'object' specifically be a class and 'object' does not convey that. So for both reasons, I propose that the pseudoname 'object' be replaces with 'class' or 'someclass' ---------- assignee: docs@python components: Documentation messages: 113194 nosy: docs@python, georg.brandl, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Replace confusing pseudoname 'object' in special methods section. versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9538> _______________________________________

5 8

[issue13561] os.listdir documentation should mention surrogateescape
by Michael Foord Nov. 16, 2020

Nov. 16, 2020

New submission from Michael Foord <michael(a)voidspace.org.uk>: Where os.listdir encounters undecodable bytes from the filesystem it uses the surrogateescape handler. As the resulting strings are invalid they can't be encoded without an errorhandler, and so can't be printed (for example). This should be documented. ---------- assignee: docs@python components: Documentation messages: 149070 nosy: docs@python, michael.foord priority: normal severity: normal stage: needs patch status: open title: os.listdir documentation should mention surrogateescape versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13561> _______________________________________

5 6

[issue14338] urllib2 HowTo for overriding post/3xx behavior.
by beeNuts Nov. 15, 2020

Nov. 15, 2020

New submission from beeNuts <jeff.adams(a)linux.com>: Issue #14144, with the title "urllib2 HTTPRedirectHandler not forwarding POST data in redirect" was recently closed with these comments: "This could be cookbook recipe style example, if it's utility value is high. I am closing this issue as I feel that the requirement may not be addressed by a change. If there is patch for HowTo, we can tackle that in another issue. Thank you for contribution." The decision that documents on this issue were preferable to a patch seems like a fair compromise, especially considering that the RFC is decidedly ambiguous.I was wondering if the HowTo would be forthcoming? It seems to me that the value/utility would certainly be high. I'd submit it myself but I'm so new to Python that I don't trust my ability to do it correctly. It's something I would find highly useful, though. ---------- assignee: docs@python components: Documentation messages: 156080 nosy: beerNuts, docs@python priority: normal severity: normal status: open title: urllib2 HowTo for overriding post/3xx behavior. versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14338> _______________________________________

4 4

[issue10709] Misc/AIX-NOTES needs updating
by Antoine Pitrou Nov. 11, 2020

Nov. 11, 2020

New submission from Antoine Pitrou <pitrou(a)free.fr>: Sébastien, would you like to provide an updated version of that file? The current contents look hopelessly outdated. ---------- assignee: docs@python components: Documentation messages: 124024 nosy: docs@python, pitrou, sable priority: normal severity: normal stage: needs patch status: open title: Misc/AIX-NOTES needs updating versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10709> _______________________________________

5 14

[issue15034] tutorial should use best practices in user defined execeptions section
by R. David Murray Nov. 10, 2020

Nov. 10, 2020

New submission from R. David Murray <rdmurray(a)bitdance.com>: And I wish I knew what those were. ---------- assignee: docs@python components: Documentation messages: 162513 nosy: docs@python, r.david.murray priority: normal severity: normal stage: needs patch status: open title: tutorial should use best practices in user defined execeptions section type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15034> _______________________________________

11 16

[issue10529] Write argparse i18n howto
by Éric Araujo Nov. 7, 2020

Nov. 7, 2020

New submission from Éric Araujo <merwok(a)netwok.org>: argparse helpfully makes its messages with gettext.gettext. The docs should explain how to benefit from that in one’s program. ---------- assignee: docs@python components: Documentation messages: 122358 nosy: bethard, docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: Write argparse i18n howto type: feature request versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10529> _______________________________________

5 5

[issue14003] __self__ on built-in functions is not as documented
by Роман Донченко Nov. 7, 2020

Nov. 7, 2020

New submission from Роман Донченко <DXDragon(a)yandex.ru>: The language reference says this in section 3.2: ~ Built-in functions A built-in function object is a wrapper around a C function. Examples of built-in functions are len() and math.sin() <...> Special read-only attributes: <...> __self__ is set to None (but see the next item) <...>. ~ That is not the case: ActivePython 3.2.2.3 (ActiveState Software Inc.) based on Python 3.2.2 (default, Sep 8 2011, 10:55:13) [MSC v.1500 64 bit (AMD64)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> len.__self__ <module 'builtins' (built-in)> >>> open.__self__ <module 'io' (built-in)> >>> import math >>> math.sin.__self__ <module 'math' (built-in)> ---------- assignee: docs@python components: Documentation messages: 153287 nosy: SpecLad, docs@python priority: normal severity: normal status: open title: __self__ on built-in functions is not as documented type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14003> _______________________________________

12 12

[issue15693] expose glossary link on hover
by Chris Jerdonek Nov. 6, 2020

Nov. 6, 2020

New submission from Chris Jerdonek: It would be nice if hovering over the right side of the header to a glossary entry would expose a link in the same way that it does for function definitions, etc. http://docs.python.org/dev/glossary.html#glossary Otherwise, there doesn't seem to be a convenient way to get a direct link to a glossary entry. I'm not sure if this issue should also be filed with Sphinx. ---------- assignee: docs@python components: Documentation messages: 168388 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: expose glossary link on hover type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15693> _______________________________________

7 15

[issue11176] give more meaningful argument names in argparse documentation
by Steven Bethard Nov. 6, 2020

Nov. 6, 2020

New submission from Steven Bethard <steven.bethard(a)gmail.com>: Suggestion from a personal email: I personally am not keen on the foo/bar/baz examples. I know that you're trying to be generic but IMO it would be much easier to understand if you used meaningful names. Also, I think that the very first example you give (which does use meaningful names:-) is too clever. I'd suggest using something simpler: in fact I'd use exactly the same example that optparse uses (--file && --quiet) since that is easy to understand and relate to straight away, and maybe add a --line option that takes a list of ints (ostensibly line numbers of lines to extract from the file) if you want to show that argparse leaves optparse in the dust. And you can always show how to get actual file objects later on. ---------- assignee: docs@python components: Documentation messages: 128302 nosy: bethard, docs@python priority: normal severity: normal stage: needs patch status: open title: give more meaningful argument names in argparse documentation type: feature request versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

13 23

[issue12436] Provide reference to detailed installation instructions
by Nick Coghlan Nov. 6, 2020

Nov. 6, 2020

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: The Boston Python Workshop folks have some detailed step-by-step instructions on getting Python up and running ([1]). Given that this can be a pain point for new users (primarily on Windows), it may be good to reference these instructions from the official docs. (Alternatively, we could use them as the basis for a "HOWTO" in the official docs and update release.py to adjust the relevant links. That's a lot more work than just adding a link, though) [1] http://openhatch.org/wiki/Boston_Python_Workshop_3/Friday ---------- assignee: docs@python components: Documentation messages: 139381 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Provide reference to detailed installation instructions _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12436> _______________________________________

10 28

[issue13122] Out of date links in the sidebar of the documentation index of versions 3.1 and 3.2
by Sven Marnach Nov. 6, 2020

Nov. 6, 2020

New submission from Sven Marnach <sven(a)marnach.net>: The sidebar on http://docs.python.org/release/3.1.3/ names 3.2 as the development version of Python, while the link points to 3.3. The sidebar on http://docs.python.org/py3k/ links to 3.1 as the "stable version" -- obviously a relict from the time when 3.2 was in development. (This could be fixed in Doc/tools/sphinxext/indexsidebar.html of the respective branches.) ---------- assignee: docs@python components: Documentation messages: 145084 nosy: docs@python, smarnach priority: normal severity: normal status: open title: Out of date links in the sidebar of the documentation index of versions 3.1 and 3.2 versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13122> _______________________________________

8 13

[issue11346] Generator object should be mentioned in gc module document
by Atsuo Ishimoto Nov. 6, 2020

Nov. 6, 2020

New submission from Atsuo Ishimoto <ishimoto(a)gembook.org>: In the gc.garbage of the library ref of gc module, ... this list contains only objects with __del__() methods. This is not true, since gc.garbage will contain generator object with try-finally block. ---------- assignee: docs@python components: Documentation messages: 129631 nosy: docs@python, ishimoto priority: normal severity: normal status: open title: Generator object should be mentioned in gc module document _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11346> _______________________________________

4 4

[issue14379] Several traceback docs improvements
by anatoly techtonik Nov. 4, 2020

Nov. 4, 2020

New submission from anatoly techtonik <techtonik(a)gmail.com>: Some notes about current `traceback` documentation: http://docs.python.org/library/traceback.html 1. It needs a mentioning that traceback module works with traceback objects and frame objects 2. Functions that work with frames should probably be grouped together 3. Docs for frame function should include info about where to get frames (e.g. http://docs.python.org/library/inspect.html#the-interpreter-stack) 4. There is no traceback object description, which should be at http://docs.python.org/library/sys.html#sys.exc_info ---------- assignee: docs@python components: Documentation messages: 156486 nosy: docs@python, techtonik priority: normal severity: normal status: open title: Several traceback docs improvements _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14379> _______________________________________

4 4

[issue9499] Python C/API Execution namespace undocumented. (patch included)
by Campbell Barton Nov. 1, 2020

Nov. 1, 2020

New submission from Campbell Barton <ideasman42(a)gmail.com>: Some parts of the python api expect __main__ module dictionary to be the namespace when executing a script, this is true when running a python script from the python binary but NOT true when running a compiled script from the C/API which can lead to bugs which are not easy to solve unless the C/API author knows this. ---------- assignee: docs@python components: Documentation files: doc_py3_main_mod.diff keywords: patch messages: 112706 nosy: docs@python, ideasman42 priority: normal severity: normal status: open title: Python C/API Execution namespace undocumented. (patch included) type: behavior versions: Python 3.2 Added file: http://bugs.python.org/file18357/doc_py3_main_mod.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9499> _______________________________________

3 4

[issue14219] start the Class tutorial in a more gentle manner
by Tshepang Lekhonkhobe Oct. 31, 2020

Oct. 31, 2020

New submission from Tshepang Lekhonkhobe <tshepang(a)gmail.com>: Looking at Doc/tutorial/classes, the section "Python Scopes and Namespaces" is full of heavy/deep information. I expect that people who would be able to properly digest that info are people who are already advanced at Python, and therefore maybe it should be moved to some cookbook (or language reference). I would prefer something gentler, since the tutorial is for Python newbies who aren't necessarily conversant with OO concepts. There can of course be links to heavier material for deeper understanding. ---------- assignee: docs@python components: Documentation messages: 155065 nosy: docs@python, tshepang priority: normal severity: normal status: open title: start the Class tutorial in a more gentle manner type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14219> _______________________________________

4 5

[issue10936] Simple CSS fix for left margin at docs.python.org
by Christopher Dunn Oct. 30, 2020

Oct. 30, 2020

New submission from Christopher Dunn <cdunn2001(a)gmail.com>: This is an easy one. When I zoom my browser in (with Ctrl+ or Apple+) the left-side navigation margin gets bigger and bigger, pushing the useful text off the screen. That has bothered me (and anyone else with 40+ year old eyes) ever since the switch to the newest doc format with Sphinx. There is no fix that will satisfy everyone. People with perfect vision might like to zoom out (with Ctrl- or Apple-), since the margin currently gets smaller and smaller. But we need a compromise. The relevant CSS, in default.css, is this: div.bodywrapper { margin: 0 0 0 230px; } If instead it were something like this: div.bodywrapper { margin: 0 0 0 10%; } then at least the navigation margin would stay the same size always. If you really want it to grow and shrink, then you need some sort of javascript control of its position. ---------- assignee: docs@python components: Documentation messages: 126477 nosy: cdunn2001, docs@python priority: normal severity: normal status: open title: Simple CSS fix for left margin at docs.python.org type: behavior versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10936> _______________________________________

8 16

[issue15029] Update Defining New Types chapter according to PEP 253
by Mateusz Loskot Oct. 27, 2020

Oct. 27, 2020

New submission from Mateusz Loskot <mateusz(a)loskot.net>: The chapter '2. Defining New Types" in the Python 3.2 documentation [1] does not cover all important elements, especially in the subsection 2.1.4. Subclassing other types. The accepted PEP 253 [2] provides much more detailed and thorough explanation for Python C API users willing to define and subclass new types, than the official manual. I'd like to suggest update of the manual with information enclosed in the PEP 253. In fact, the PEP's sections like * Preparing a type for subtyping * Creating a subtype of a built-in type in C could be copied with little editing, IMHO. The PEP 253 really seems to be a must-read document for Python C API users. [1] http://docs.python.org/release/3.2.2/extending/newtypes.html [2] http://www.python.org/dev/peps/pep-0253/ ---------- assignee: docs@python components: Documentation messages: 162480 nosy: docs@python, mloskot priority: normal severity: normal status: open title: Update Defining New Types chapter according to PEP 253 type: enhancement versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15029> _______________________________________

2 2

[issue15339] document the threading "facts of life" in Python
by Chris Jerdonek Oct. 26, 2020

Oct. 26, 2020

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: I think it would be helpful if the Python documentation included certain high-level information about multi-threading in Python. At minimum, I think it would help for the documentation to provide a definition that can be linked to of what it means when some part of the Python documentation says something is "thread-safe". In particular, such a definition could clarify that this is different from being atomic. This might best be addressed by an entry in the glossary for the term "thread-safe". Other documentation possibilities include stating what guarantees one should or should not expect regarding thread-safety, both within and across implementations, and providing centralized guidance on how to approach multi-threaded programming in Python. A HOWTO is one possibility for addressing these other possibilities. This issue stems from the discussion in issue 15329, which is more specific. ---------- assignee: docs@python components: Documentation messages: 165336 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: document the threading "facts of life" in Python _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15339> _______________________________________

8 8

[issue12832] The documentation for the print function should explain/point to how to control the sys.stdout encoding
by R. David Murray Oct. 25, 2020

Oct. 25, 2020

New submission from R. David Murray <rdmurray(a)bitdance.com>: A common problem encountered when using python3 is writing non-ascii to stdout. This will work fine if stdout is a terminal and the terminal encoding handles the characters, but will fail if stdout is later redirected to a pipe. The docs for sys.stdout and for print should contain or point to an explanation of why, and how to solve the problem (ie: how to set the encoding for sys.stdout/sys.stderr). Note that IMO it makes more sense for sys.stdout to default to the LOCALE encoding, but that should be a separate issue. ---------- assignee: docs@python components: Documentation messages: 142880 nosy: docs@python, r.david.murray priority: normal severity: normal status: open title: The documentation for the print function should explain/point to how to control the sys.stdout encoding versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12832> _______________________________________

4 7

[issue12174] Multiprocessing logging levels unclear
by JJeffries Oct. 22, 2020

Oct. 22, 2020

New submission from JJeffries <jamesjeffries1(a)gmail.com>: It is unclear without reference to the logging module where the multiprocessing logging levels fit in the normal logging provided by the logging module, even though it says above the table "The table below illustrates where theses fit in the normal level hierarchy. +----------------+----------------+ | Level | Numeric value | +================+================+ | ``SUBWARNING`` | 25 | +----------------+----------------+ | ``SUBDEBUG`` | 5 | +----------------+----------------+" I propose adding further values from the logging module for clarification. ---------- assignee: docs@python components: Documentation messages: 136839 nosy: JJeffries, docs@python priority: normal severity: normal status: open title: Multiprocessing logging levels unclear versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12174> _______________________________________

8 15

[issue13047] imp.find_module("") and imp.find_module(".")
by Arfrever Frehtes Taifersar Arahesis Oct. 22, 2020

Oct. 22, 2020

New submission from Arfrever Frehtes Taifersar Arahesis <Arfrever.FTA(a)GMail.Com>: It's undocumented that imp.find_module("") and imp.find_module(".") try to find __init__.py. There is also a small difference in behavior between them. sys.path by default contains "" as the first element, which is sufficient for imp.find_module("."), but not for imp.find_module(""): $ mkdir /tmp/imp_tests $ cd /tmp/imp_tests $ touch __init__.py $ python3.3 -c 'import imp, sys; print(repr(sys.path[0])); print(imp.find_module("."))' '' (None, '.', ('', '', 5)) $ python3.3 -c 'import imp, sys; print(repr(sys.path[0])); print(imp.find_module(""))' '' Traceback (most recent call last): File "<string>", line 1, in <module> ImportError: No module named '' If sys.path contains path (e.g. "." or absolute path) to directory with __init__.py file, then imp.find_module("") will succeed: $ PYTHONPATH="." python3.3 -c 'import imp, sys; print(repr(sys.path[0:2])); print(imp.find_module("."))' ['', '/tmp/imp_tests'] (None, '.', ('', '', 5)) $ PYTHONPATH="." python3.3 -c 'import imp, sys; print(repr(sys.path[0:2])); print(imp.find_module(""))' ['', '/tmp/imp_tests'] (None, '/tmp/imp_tests/', ('', '', 5)) $ python3.3 -c 'import imp, sys; sys.path.insert(1, "."); print(repr(sys.path[0:2])); print(imp.find_module("."))' ['', '.'] (None, '.', ('', '', 5)) $ python3.3 -c 'import imp, sys; sys.path.insert(1, "."); print(repr(sys.path[0:2])); print(imp.find_module(""))' ['', '.'] (None, './', ('', '', 5)) I think that imp.find_module(".") and imp.find_module("") should have the same behavior, and this behavior should be documented. ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 144531 nosy: Arfrever, docs@python priority: normal severity: normal status: open title: imp.find_module("") and imp.find_module(".") versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13047> _______________________________________

5 5

[issue14979] pdb: Link to source
by anatoly techtonik Oct. 22, 2020

Oct. 22, 2020

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/pdb.html#pdb.Pdb Documentation for pdb says: "The debugger is extensible — it is actually defined as the class Pdb. This is currently undocumented but easily understood by reading the source." There should a link to the source. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 162074 nosy: docs@python, techtonik priority: normal severity: normal status: open title: pdb: Link to source _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14979> _______________________________________

4 5

[issue13828] Further improve casefold documentation
by Jim Jewett Aug. 24, 2020

Aug. 24, 2020

New submission from Jim Jewett <jimjjewett(a)gmail.com>: > http://hg.python.org/cpython/rev/0b5ce36a7a24 > changeset: 74515:0b5ce36a7a24 > + Casefolding is similar to lowercasing but more aggressive because it is > + intended to remove all case distinctions in a string. For example, the German > + lowercase letter ``'ß'`` is equivalent to ``"ss"``. Since it is already > + lowercase, :meth:`lower` would do nothing to ``'ß'``; :meth:`casefold` > + converts it to ``"ss"``. Perhaps add the recommendation to canonicalize as well. A complete, but possibly too long, try is below: Casefolding is similar to lowercasing but more aggressive because it is intended to remove all case distinctions in a string. For example, the German lowercase letter ``'ß'`` is equivalent to ``"ss"``. Since it is already lowercase, :meth:`lower` would do nothing to ``'ß'``; :meth:`casefold` converts it to ``"ss"``. Note that most case-insensitive matches should also match compatibility equivalent characters. The casefolding algorithm is described in section 3.13 of the Unicode Standard. Per D146, a compatibility caseless match can be achieved by from unicodedata import normalize def caseless_compat(string): nfd_string = normalize("NFD", string) nfkd1_string = normalize("NFKD", nfd_string.casefold()) return normalize("NFKD", nfkd1_string.casefold()) ---------- assignee: docs@python components: Documentation messages: 151644 nosy: Jim.Jewett, benjamin.peterson, docs@python priority: normal severity: normal status: open title: Further improve casefold documentation versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13828> _______________________________________

7 10

[issue13649] termios.ICANON is not documented
by anatoly techtonik May 31, 2020

May 31, 2020

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/termios.html is missing documentation for ICANON flag used to put terminal to "raw" mode. It is also worth to place `termios` raw/canonical mode equivalent on `tty` pages, so that people porting C code to Python could understand the hidden magic. ---------- assignee: docs@python components: Documentation, IO, Library (Lib) messages: 150098 nosy: docs@python, techtonik priority: normal severity: normal status: open title: termios.ICANON is not documented versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13649> _______________________________________

3 3

[issue16700] Document that bytes OS API can returns unusable results on Windows
by Serhiy Storchaka May 31, 2020

May 31, 2020

New submission from Serhiy Storchaka: Some OS functions which returns bytes (os.environb, os.getenvb(), os.getcwdb(), os.listdir(), os.readlink(), os.walk(), os.path.abspath(), os.path.expanduser(), os.path.expandvars(), os.path.realpath() and may be other) can return unusable result on Windows (see for example issue13247 and issue16656). The documentation should contains strong warnings about this. ---------- assignee: docs@python components: Documentation, Windows messages: 177613 nosy: docs@python, serhiy.storchaka priority: normal severity: normal stage: needs patch status: open title: Document that bytes OS API can returns unusable results on Windows type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16700> _______________________________________

6 12

[issue9196] Improve docs for string interpolation "%s" re Unicode strings
by Craig McQueen May 31, 2020

May 31, 2020

New submission from Craig McQueen <python(a)craig.mcqueen.id.au>: I have just been trying to figure out how string interpolation works for "%s", when Unicode strings are involved. It seems it's a bit complicated, but the Python documentation doesn't really describe it. It just says %s "converts any Python object using str()". Here is what I have found (I think), and it could be worth improving the documentation of this somehow. Example 1: "%s" % test_object >From what I can tell, in this case: 1. test_object.__str__() is called. 2. If test_object.__str__() returns a string object, then that is substituted. 3. If test_object.__str__() returns a Unicode object (for some reason), then test_object.__unicode__() is called, then _that_ is substituted instead. The output string is turned into Unicode. This behaviour is surprising. [Note that the call to test_object.__str__() is not the same as str(test_object), because the former can return a Unicode object without causing an error, while the latter, if it gets a Unicode object, will then try to encode('ascii') to a string, possibly generating a UnicodeEncodeError exception.] Example 2: u"%s" % test_object In this case: 1. test_object.__unicode__() is called, if it exists, and the result is substituted. The output string is Unicode. 2. If test_object.__unicode__() doesn't exist, then test_object.__str__() is called instead, converted to Unicode, and substituted. The output string is Unicode. Example 3: "%s %s" % (u'unicode', test_object) In this case: 1. The first substitution causes the output string to be Unicode. 2. It seems that (1) causes the second substitution to follow the same rules as Example 2. This is a little surprising. ---------- assignee: docs@python components: Documentation messages: 109516 nosy: cmcqueen1975, docs@python priority: normal severity: normal status: open title: Improve docs for string interpolation "%s" re Unicode strings versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9196> _______________________________________

5 10

[issue15952] format(value) and value.__format__() behave differently with unicode format
by Chris Jerdonek May 31, 2020

May 31, 2020

New submission from Chris Jerdonek: format(value) and value.__format__() behave differently even though the documentation says otherwise: "Note: format(value, format_spec) merely calls value.__format__(format_spec)." (from http://docs.python.org/library/functions.html?#format ) The difference happens when the format string is unicode. For example: >>> format(10, u'n') u'10' >>> (10).__format__(u'n') # parentheses needed to prevent SyntaxError '10' So either the documentation should be changed, or the behavior should be changed to match. Related to this: neither the "Format Specification Mini-Language" documentation nor the string.Formatter docs seem to say anything about the effect that a unicode format string should have on the return value (in particular, should it cause the return value to be unicode or not): http://docs.python.org/library/string.html#formatspec http://docs.python.org/library/string.html#string-formatting See also issue 15276 (int formatting), issue 15951 (empty format string), and issue 7300 (unicode arguments). ---------- assignee: docs@python components: Documentation messages: 170575 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: format(value) and value.__format__() behave differently with unicode format type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15952> _______________________________________

5 8

[issue11425] Cleanup sample codes in tutorial.
by INADA Naoki May 13, 2020

May 13, 2020

New submission from INADA Naoki <songofacandy(a)gmail.com>: * Insert spaces around operators and after commas. * Split one liner blocks (ex. def foo(x, y): return x + y) to multi-line blocks. * Insert empty line after def block for scripts (not interactive mode). * Use new-style raise (s/ralse KeyboardInterrupt/raise KeyboardInterrupt()/) * Use x ** 3 instead of x * x * x. Attached patch is for Python 2.6. I'll make same changes for Python 3.1 if this patch is accepted. ---------- assignee: docs@python components: Documentation files: cleanup_tutorial_codes.patch keywords: patch messages: 130225 nosy: docs@python, naoki priority: normal severity: normal status: open title: Cleanup sample codes in tutorial. versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file21027/cleanup_tutorial_codes.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11425> _______________________________________

5 5

[issue8940] *HTTPServer need a summary page with API inheritance table
by anatoly techtonik April 26, 2020

April 26, 2020

New submission from anatoly techtonik <techtonik(a)gmail.com>: The abundance of methods and hierarchy depth of various servers from "Internet Protocols and Support" section makes it extremely hard to navigate information. You need a strong OOP background to be able to use this doc effectively, as examples are not intuitive otherwise. Usually you need a decent IDE (such as Eclipse) to get a picture of class hierarchy and a table of all available methods with a mark where they were inherited from. Such table (at least Class Hierarchy view screenshot from Eclipse) should be available in reference for descendant classes. ---------- assignee: docs@python components: Documentation messages: 107321 nosy: docs@python, techtonik priority: normal severity: normal status: open title: *HTTPServer need a summary page with API inheritance table versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8940> _______________________________________

6 7

[issue14418] Document differences in SocketServer between Python 2.6 and 2.7
by Geoffrey Bache April 26, 2020

April 26, 2020

New submission from Geoffrey Bache <gjb1002(a)users.sourceforge.net>: Here I'm referring to the section about RequestHandler objects under the SocketServer page. http://docs.python.org/release/2.7.2/library/socketserver.html#requesthandl… This appears to be the same in Python 2.6 and Python 2.7. But the objects don't behave the same, in two respects: 1) For finish() "If setup() or handle() raise an exception, this function will not be called." This is true in Python 2.6. It appears to no longer be true in Python 2.7, where finish() is called in a "finally" clause. 2) For handle(). "The default implementation does nothing". This is true up to a point, but using the default implementation has different effects. Specifically, if I try to read from a socket when the server has not written anything, I get an exception in Python 2.6 and an empty string in Python 2.7. Consider this code: ## server.py from SocketServer import TCPServer, StreamRequestHandler import sys, socket server = TCPServer((socket.gethostname(), 0), StreamRequestHandler) host, port = server.socket.getsockname() address = host + ":" + str(port) print "Started server at", address sys.stdout.flush() server.serve_forever() ## client.py import sys, socket servAddr = sys.argv[1] host, port = servAddr.split(":") serverAddress = (host, int(port)) sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) sock.connect(serverAddress) sock.sendall("Some Message") sock.shutdown(1) response = sock.makefile().read() print "Got reply:", response sock.close() and compare the following: $ python2.7 server.py & Started server at 127.0.1.1:42759 $ python2.7 client.py 127.0.1.1:42759 Got reply: $ python2.6 server.py & Started server at 127.0.1.1:42758 $ python client.py 127.0.1.1:42758 Traceback (most recent call last): File "client.py", line 12, in <module> response = sock.makefile().read() File "/usr/lib/python2.7/socket.py", line 351, in read data = self._sock.recv(rbufsize) socket.error: [Errno 104] Connection reset by peer (doesn't matter which Python runs the client in the last case) I am unsure whether this is a bug in Python 2.6, or really what the reasoning behind the behaviour difference is, but I think this change in behaviour is worth a small note in the documentation (how it will behave if you try to read when nothing has been written) ---------- assignee: docs@python components: Documentation messages: 156869 nosy: docs@python, gjb1002 priority: normal severity: normal status: open title: Document differences in SocketServer between Python 2.6 and 2.7 versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14418> _______________________________________

5 5

[issue14759] Berkeley DB License conditions are onerous (and poorly documented)
by Jeff Laing April 26, 2020

April 26, 2020

New submission from Jeff Laing <jefflaing(a)gmail.com>: As part of an audit of license compliance, I was looking at the terms in the LICENSE.txt that describe the Berkeley DB product. I had thought this would be under the standard Berkeley license, but Oracle have added their own zinger. * 3. Redistributions in any form must be accompanied by information on * how to obtain complete source code for the DB software and any * accompanying software that uses the DB software. The source code * must either be included in the distribution or be available for no * more than the cost of distribution plus a nominal fee, and must be * freely redistributable under reasonable conditions. So, my application, which embeds Python (rather than running it as python.exe) and includes the standard runtime library, must distribute my source code. This page: http://mail.python.org/pipermail/python-dev/2008-September/082316.html suggests that this is not the case for regular Python, but it makes no statement about "embedding". Sadly the Oracle page it links to suggesting this is not an issue, does not exist. The general "License" page on the Python websites makes no reference whatsoever to Berkeley DB license obligations. I note that there are other modules mentioned on the Licenses webpage that are not in the LICENSES.txt file, and vice versa. I have no idea whether this is deliberate, or an oversight. ---------- assignee: docs@python components: Documentation messages: 160238 nosy: Jeff.Laing, docs@python priority: normal severity: normal status: open title: Berkeley DB License conditions are onerous (and poorly documented) type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14759> _______________________________________

5 12

[issue13743] xml.dom.minidom.Document class is not documented
by Sandro Tosi April 12, 2020

April 12, 2020

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: Hello, following up http://mail.python.org/pipermail/docs/2012-January/007026.html I noticed the whole Document class (and relative methods) is not documented. Maybe it is a choice to not document it, or maybe it's just a missing doc, dunno, the's why I'm opening this :) ---------- assignee: docs@python components: Documentation messages: 150935 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: needs patch status: open title: xml.dom.minidom.Document class is not documented versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13743> _______________________________________

6 9

[issue15140] PEP 384 inconsistent with implementation
by Antoine Pitrou April 1, 2020

April 1, 2020

New submission from Antoine Pitrou <pitrou(a)free.fr>: In PEP 384, the PyType_Spec struct has a "const char *doc" that is not present in the implementation (Include/object.h). ---------- assignee: docs@python components: Documentation messages: 163449 nosy: docs@python, loewis, pitrou priority: normal severity: normal stage: needs patch status: open title: PEP 384 inconsistent with implementation type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15140> _______________________________________

4 3

[issue15436] __sizeof__ is not documeneted
by Serhiy Storchaka March 22, 2020

March 22, 2020

New submission from Serhiy Storchaka <storchaka(a)gmail.com>: __sizeof__ is not mentioned on page Doc/reference/datamodel.rst together with other special methods. There is no __sizeof__ in index. ---------- assignee: docs@python components: Documentation messages: 166245 nosy: docs@python, storchaka priority: normal severity: normal status: open title: __sizeof__ is not documeneted versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15436> _______________________________________

14 24

[issue13077] Unclear behavior of daemon threads on main thread exit
by etuardu March 9, 2020

March 9, 2020

New submission from etuardu <edonan(a)gmail.com>: The definition of daemon thread in the current documentation reads: «A thread can be flagged as a "daemon thread". The significance of this flag is that the entire Python program exits when only daemon threads are left. [...]» (http://docs.python.org/library/threading.html#thread-objects) I think it's not very clear from this that daemon threads themselves terminate when the program (main thread plus other non-daemon threads) terminates. I think this have to be said more explicitly. I'd propose a change with something like: «A thread can be flagged as a "daemon thread", which means it will get shut down when the overall program terminates. The entire Python program exits when only daemon threads are left.» ---------- assignee: docs@python components: Documentation messages: 144691 nosy: docs@python, etuardu priority: normal severity: normal status: open title: Unclear behavior of daemon threads on main thread exit type: behavior versions: 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/issue13077> _______________________________________

5 7

[issue8824] Improve documentation of exec
by Terry J. Reedy Feb. 28, 2020

Feb. 28, 2020

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: This doc improvement suggestion is inspired by #991196 (and subsequent duplicates) and the current discussion on py-dev in the thread 'variable name resolution in exec is incorrect' (which is not a correct claim). I believe there is consensus that the doc for exec needs improving. My suggestion (which others may amend) is that the following paragraph (from the 3.x builtin functions exec entry) "In all cases, if the optional parts are omitted, the code is executed in the current scope. If only globals is provided, it must be a dictionary, which will be used for both the global and the local variables. If globals and locals are given, they are used for the global and local variables, respectively. If provided, locals can be any mapping object." have these two sentences added: "If only globals is provided or if onedict is provided as both globals and locals, the code is executed in a new top-level scope. If different objects are given as globals and locals, the code is executed as if it were in a class statement in a new top-level scope." ---------- assignee: docs@python components: Documentation messages: 106552 nosy: docs@python, tjreedy priority: normal severity: normal status: open title: Improve documentation of exec versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8824> _______________________________________

6 19

[issue15474] Differentiate decorator and decorator factory in docs
by Éric Araujo Feb. 26, 2020

Feb. 26, 2020

New submission from Éric Araujo <merwok(a)netwok.org>: Some of the confusion encountered when writing decorators arise from the difference between a decorator (@something) and a decorator factory (@something(args)). It would help to adopt this clearer terminology in our docs: a decorator takes the decorated function as argument and does its business, a decorator factory takes some arguments and returns a decorator which wraps the decorated function. (I think it was Nick who suggested this in a recent-ish mailing list thread.) ---------- assignee: docs@python components: Documentation messages: 166600 nosy: docs@python, eric.araujo, ncoghlan priority: normal severity: normal status: open title: Differentiate decorator and decorator factory in docs versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15474> _______________________________________

8 14

[issue9056] Adding additional level of bookmarks and section numbers in python pdf documents.
by pengyu.ut Feb. 18, 2020

Feb. 18, 2020

New submission from pengyu.ut <pengyu.ut(a)gmail.com>: Current pdf version of python documents don't have bookmarks for sussubsection. For example, there is no bookmark for the following section in python_2.6.5_reference.pdf. Also the bookmarks don't have section numbers in them. I suggest to include the section numbers. Could these features be added in future release of python document. 3.4.1 Basic customization ---------- assignee: docs@python components: Documentation messages: 108334 nosy: docs@python, pengyu.ut priority: normal severity: normal status: open title: Adding additional level of bookmarks and section numbers in python pdf documents. versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9056> _______________________________________

7 9

[issue9305] Don't use east/west of UTC in date/time documentation
by Alexander Belopolsky Feb. 14, 2020

Feb. 14, 2020

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: I am opening this to supersede issue7229. See discussion following msg107148. In many places offsets representing the difference between local time and UTC are described as minutes or seconds east or west of UTC. This is not correct because UTC is not a place and minutes and seconds don't measure distance in this context. Replacing UTC with the Prime Meridian will not fix that because some regions in the western hemisphere use positive offsets from UTC. or example, Madrid is at 3° 42' West, but uses Central European Time which is UTC+1. I believe geographical references in the python documentation are irrelevant. What users are interested in is how to convert local time to UTC and UTC to local time rather than what is the sign of time.timezone in Madrid. I suggest the following wording for time.timezone description: time.timezone: The number of seconds one must add to the local time to arrive at UTC. Similarly, tzinfo.utcoffset() can be defined as "Returns timedelta one must add to UTC to arrive at local time." ---------- assignee: docs@python components: Documentation keywords: easy messages: 110774 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: Don't use east/west of UTC in date/time documentation type: feature request versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

15 30

[issue13826] Having a shlex example in the subprocess.Popen docs is confusing
by Julian Berman Feb. 10, 2020

Feb. 10, 2020

New submission from Julian Berman <Julian+Python.org(a)GrayVines.com>: The example at http://docs.python.org/dev/library/subprocess.html#popen-constructor seems a bit misplaced, as it seems to suggest that one should use the shlex module. Most of the other examples in the module seem to use a list to provide the args, so if there was a need to just point out that shlex could be used for a corner case perhaps it'd be better suited as a footnote or another subsection somewhere. ---------- assignee: docs@python components: Documentation messages: 151624 nosy: Julian, docs@python priority: normal severity: normal status: open title: Having a shlex example in the subprocess.Popen docs is confusing type: enhancement versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13826> _______________________________________

9 14

[issue16776] Document PyCFunction_New and PyCFunction_NewEx functions
by Andrew Svetlov Feb. 10, 2020

Feb. 10, 2020

New submission from Andrew Svetlov: c-api docs has no documentation for those public API functions. ---------- assignee: docs@python components: Documentation keywords: easy messages: 178115 nosy: asvetlov, docs@python priority: normal severity: normal status: open title: Document PyCFunction_New and PyCFunction_NewEx functions type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16776> _______________________________________

7 8

[issue15867] It's hard to decypher how to build off of the provided objects from the importlib docs
by Julian Berman Jan. 28, 2020

Jan. 28, 2020

New submission from Julian Berman: I find that the importlib documentation is a bit too low level. Import hooks are not that common, so requiring a bit of reading is OK with me, but I somewhat *understand* PEP 302, so I have a general idea of *what* I want to do and what kind of objects can accomplish that, and still find it hard to figure out how to take the pieces provided by importlib and use them to do what I want. If I provide a specific example, I want to create a path hook that "just" does the usual import behavior, but before executing the module, does some transformation on the source code, say. In trying to figure out the best way to do that I had a hard time using the docs to figure out which pieces I should assemble to do that. I'm going to just describe the rough series of steps I went through, and hopefully that will help give a picture of where in the docs I had trouble. `importlib.abc` has a few things that would appear to help. None of the things seem like an exact match, so immediately I'm confused -- after reading PEP 302 I'd have expected to need to find an object to implement one or both of `get_code` or `get_source` on, or one that has that implemented that I can subclass and extend. The closest thing there that I find is PyPycLoader, which seems to be saying it implements the standard import behavior, but the docs say its deprecated and to use SourceLoader. At this point, after checking out `SourceLoader` and seeing that it has me implementing two methods whose purpose I don't quite understand, even after reading the short descriptions of them, at least not in the context of what I want to do, I begin to suspect that what I really want is to combine SourceLoader with some things from the `imp` module, or maybe `importlib.__import__`, but am left wondering again how much I need to implement before I just can use that. I then notice `importlib.util.module_for_loader`, and add that to the simple loader I've written which I'm still waiting to plug `imp` into, before realizing that that decorator eats the `fullname` attribute and *only* passes along the module, which confuses me, since now I don't know how to retrieve the source for the module object that I'm being passed -- so I save the path name in `__init__` for the class, and assume that's what I should be doing, despite not seeing an example doing that. Assuming that's even correct as-is, it took me quite a bit to put those pieces together. So I apologize for rambling -- I think essentially what'd improve things is providing more examples, or perhaps a HOWTO entry, that targeted assembling the pieces provided in the module into a few clear, complete examples of finders, loaders and importers. ---------- assignee: docs@python components: Documentation messages: 169901 nosy: Julian, docs@python priority: normal severity: normal status: open title: It's hard to decypher how to build off of the provided objects from the importlib docs versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15867> _______________________________________

8 11

[issue15243] Misleading documentation for __prepare__
by William Schwartz Jan. 25, 2020

Jan. 25, 2020

New submission from William Schwartz <wkschwartz(a)gmail.com>: Section 3.3.3.2. "Preparing the class namespace" of the documentation (http://docs.python.org/dev/reference/datamodel.html#preparing-the-class-nam…) states that "If the metaclass has a __prepare__ attribute, it is called as ``namespace = metaclass.__prepare__(name, bases, **kwds)``...." This isn't quite true. By just defining a ``__prepare__`` method in a metaclass, the interpreter calls it as it would a static method -- there is no implicit first argument referring to ``metaclass`` as the documentation implies. The documentation should be amended to say that users can decorate ``__prepare__`` as a class method to get ``metaclass`` passed in as the implicit first argument. ---------- assignee: docs@python components: Documentation, Tests messages: 164606 nosy: William.Schwartz, docs@python priority: normal severity: normal status: open title: Misleading documentation for __prepare__ type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________

11 22

[issue11553] Docs for: import, packages, site.py, .pth files
by Graham Wideman Jan. 24, 2020

Jan. 24, 2020

New submission from Graham Wideman <initcontact(a)grahamwideman.com>: The overall scope of this issue is that current Python documentation gives vague, sometimes incorrect, information about the set of Python features involved in modularizing functionality. This issue presents an obstacle to programmers making smooth transitions from a single module, to collections of modules and packages, then on to neatly organized common packages shared between projects. The problem affects documentation of: import and from...import statements ------------------------------------ The Language Reference is way too complicated for the mainstream case. Exactly what variants of arguments are possible, and what are their effects? What are the interactions with package features, such as whether or not modules have been explicitly imported into package __init_.py? sys.path --------- Typical consituents; range of alternatives for adding more dirs Module site.py -------------- Multiple serious errors in the file docstring, relating to site-packages directories and .pth files .pth files ----------- Incorrectly described in site.py, and then vaguely described in other docs. Are .pth files processed everywhere on sys.path? Can they be interative? (No to both). package structure ----------------- Details of package structure have evidently changed over Python versions. Current docs are unclear on points such as: -- is __init__.py needed on subpackage directories? -- the __all__ variable: Does it act generally to limit visibility of a module or package's attributes, or does pertain only to the 'from...import *' statement? Details: ========= Language Reference ------------------- http://docs.python.org/py3k/reference/simple_stmts.html#the-import-statement The description of the import statement is extensive, but dauntingly complicated for the reader trying to understand the mainstream case of simply importing modules or packages that are on sys.path. This is because the algorithm for finding modules tries numerous esoteric strategies before falling back on the plain-old-file-system method. (Even now that I have a good understanding of the plain-old-file variations of import, I reread this and find it hard to comprehend, and disorganized and incomplete in presenting the available variations of the statement.) Grammar issue: the grammar shown for the import statement shows: relative_module ::= "."* module | "."+ ... which implies that relative module could have zero leading dots. I believe an actual relative path is required to have at least one dot (PEP 328). Evidently, in this grammar, 'relative_module' really means "relative or absolute path to module or package", so it would be quite helpful to change to: relative_path ::= "."+ module | "."+ from_path ::= (relative_path | module) etc. (Really 'module' is not quite right here either since it's used to mean module-or-package.) site.py: -------- Module site.py implements the site-package related features. The docstring has multiple problems with consequences in other docs. 1. Does not mention user-specific site-package directories (implemented by addusersitepackages() ) 2. Seriously misleading discussion of .pth files. In the docstring the example shows using pth files, called "package configuration files" in their comments, to point to actual package directories bar and foo located within the site-packages directory. This is an absolutely incorrect use of pth files: If foo and bar are packages in .../site-packages/, they do not need to be pointed to, they are already on sys.path. If the package dirs ARE pointed to by foo.pth and bar.pth, the modules inside them will be exposed directly to sys.path, possibly precipitating name collisions. Further, programmers following this example will create packages in which import statements will appear to magically perform relative imports without leading dots, leading to confusion over how the import statement is supposed to work. It may be that this discussion is held over from a time when "package" perhaps meant "Just a Bunch of Files in a Directory"? 3. The docstring (or other docs) should make clear that .pth files are ONLY processed within site-package directories (ie: only by site.py). 4. Bug: Minor: In addsitepackages(), the library directory for Windows (the else clause) is shown as lower-case 'lib' instead of 'Lib'. This has some possibility of causing problems when running from a case-sensitive server. In any case, if read as documentation it is misleading. Tutorial --------- 6. Modules: http://docs.python.org/py3k/tutorial/modules.html 1. Discussion (6.1.2. The Module Search Path) is good as far as it goes, but it doesn't mention the site-package directories. 2. Section 6.4. Packages: Discussion of __init__.py does describe the purpose of these files. However, the discussion in relation to subpackages should mention that for subdirectories to be accessible they must in fact be made into subpackages. I.e.: there is not form of import that can reach into a subdir of a package *unless* it's flagged as a subpackage using __init__.py. I have read elsewhere that there were some versions of Python where __init__.py was not needed on subdirs within a package. 3. Section 6.4. Packages: The discussion of __all__ should note that it works *only* in conjunction with 'from...import *', and is not a general mechanism for limiting visibility of attributes. Attributes not in the __all__ list are still accessible using other forms of import. 4. Section 6.4. Packages: "Note that when using from package import item" and following. Draws a contrast between: from package import item vs import item.subitem.subsubitem However, this muddles the roles of the arguments to import, and notably uses 'item' in two different ways. Instead the discussion can be presented as a comparison of: from PackageOrModule import ModuleOrAttribute vs import PackageOrModule ... where it can be pointed out that the PackageOrModule 'dotted path' argument follows the *same* rules in both cases (except for relative paths). The *salient* contrast is that only the 'from' form has a *second* argument which can be an attribute. 5. Footnote: (somewhat unrelated, but...) says "the execution of a module-level function enters the function name in the module’s global symbol table." This is surely incorrect -- it is the execution of the function's *def* that enters the function name in the symbol table. Standard Library Reference --------------------------- 1) 27.13. site — Site-specific configuration hook http://docs.python.org/py3k/library/site.html This is documentation for site.py, and is a page that might well come up in a search for '.pth'. 1a) This page may simply be importing the docstring from site.py? In any case it repeats the ommissions and errors noted above for site.py. 2) 27.1. sys — System-specific parameters and functions http://docs.python.org/py3k/library/sys.html Documentation for sys.path. OK as far as it goes, but: 2a) Could helpfully point to a discussion of the typical items to be found in sys.path under normal circumstances 2b) It does point to the site.py module documentation as the authoritative info on using .pth files (which is seriously flawed as noted above). 3) 29.3. pkgutil — Package extension utility. http://docs.python.org/py3k/library/pkgutil.html 3a) The info for pkgutil.extend_path() describes how .pkg files are similar to .pth files, and their entries should point to package directories. As I noted above, so far as I can see, package directories should be within a directory on sys,path, but should not themselves be included in the path, otherwise it breaks their capability to work properly as packages. 'Installing Python Modules' document: -------------------------------------- http://docs.python.org/py3k/install/index.html This may well be consulted for info on how to organize source files, though it is basically the doc for Distutils. 1. Main problem is that it seems quite out-of-date; "Windows has no concept of a user’s home directory, " and so on. 2. 'How installation works' > table. For Windows suggests 'prefix' (default: C:\Python) as an installation directory. This is indeed one of the possible 'site-package' directories, but surely it is deprecated in favor of C:\Python\Lib\site-packages, which this section does not mention. 3. Does not mention user-specific site-package directories. 4. 'Modifying Python's Search Path' > "The most convenient way is to add a path configuration file to a directory that’s already on Python’s path". This is incorrect. (a) .pth files are only processed in site-package directories. (b) Clarifying an additional point of confusion -- as a consequence of (a) .pth files cannot be chained. 5. Points to docs for site.py... with it's flaws noted above. PEP 302 New Import Hooks ------------------------ Given the vagueness elsewhere in the docs, one might go hunting for ground truth in the PEPs. One must allow for PEPs having been superceeded, but nonetheless, outdated info that is now wrong is an additional stumbling block for learners. 1. Section 'Specification part 1: The importer Protocol'. Discussion says that in an import statement, a path (with no leading '.') is first treated as relative. This is now incorrect (as spelled out in PEP 328.) It would be helpful to insert a note in PEP 302 pointing out that the later revision invalidates this passage. ---------- assignee: docs@python components: Documentation messages: 130964 nosy: docs@python, gwideman priority: normal severity: normal status: open title: Docs for: import, packages, site.py, .pth files type: behavior versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11553> _______________________________________

6 14

[issue15718] Possible OverflowError in __len__ method undocumented (when called via len() function)
by Rostyslav Dzinko Jan. 10, 2020

Jan. 10, 2020

New submission from Rostyslav Dzinko: I've encountered that OverflowError which can happen in __len__ method is still undocumented, though one issue on this problem: http://bugs.python.org/issue12159 ended up with "need to be documented" comment. Link to documentation: http://docs.python.org/reference/datamodel.html#object.__len__ I think it must be clarified that __len__ return value is constrained to upper boundary (Py_ssize_t c type) when you plan to call it via len() built-in function. ---------- assignee: docs@python components: Documentation messages: 168439 nosy: Rostyslav.Dzinko, docs@python priority: normal severity: normal status: open title: Possible OverflowError in __len__ method undocumented (when called via len() function) versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15718> _______________________________________

7 18

[issue13562] Notes about module load path
by Nam Nguyen Oct. 22, 2019

Oct. 22, 2019

New submission from Nam Nguyen <bitsink(a)gmail.com>: A doc patch to remind Python embedder to set sys.path prior to Py_Initialize. This is to ensure a controlled module load path to work around these issues: http://bugs.python.org/issue12989 http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983 ---------- assignee: docs@python components: Documentation files: module.load.path.diff keywords: patch messages: 149071 nosy: Nam.Nguyen, docs@python priority: normal severity: normal status: open title: Notes about module load path type: feature request versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file23888/module.load.path.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13562> _______________________________________

4 6

[issue13474] Mention of "-m" Flag Missing From Doc on Execution Model
by Eric Snow Sept. 12, 2019

Sept. 12, 2019

New submission from Eric Snow <ericsnowcurrently(a)gmail.com>: The doc on code execution[1] leaves out mention of the -m flag. Seems like it belongs there too. [1] Doc/reference/executionmodel.rst ---------- assignee: docs@python components: Documentation messages: 148288 nosy: docs@python, eric.snow priority: normal severity: normal status: open title: Mention of "-m" Flag Missing From Doc on Execution Model versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13474> _______________________________________

8 10

[issue9938] Documentation for argparse interactive use
by Jay T Sept. 12, 2019

Sept. 12, 2019

New submission from Jay T <jaytula(a)gmail.com>: I want to create a custom interactive shell where I continually do parse_args. Like the following: parser = argparse.ArgumentParser() command = raw_input() while(True): args = parser.parse_args(shlex.split(command)) # Do some magic stuff command = raw_input() The problem is that if I give it invalid input, it errors and exits with a help message. I learned from argparse-users group that you can override the exit method like the following: class MyParser(ArgumentParser): def exit(self, status=0, message=None): # do whatever you want here I would be nice to have this usage documented perhaps along with best practices for doing help messages in this scenario. ---------- assignee: docs@python components: Documentation messages: 117287 nosy: docs@python, jayt priority: normal severity: normal status: open title: Documentation for argparse interactive use type: feature request versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9938> _______________________________________

16 28

[issue16438] Numeric operator predecence confusing
by Yongzhi Pan Sept. 11, 2019

Sept. 11, 2019

New submission from Yongzhi Pan: http://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-comp… "All numeric types (except complex) support the following operations, sorted by ascending priority." It list '-' after '+', '/' after '*'. That is to mean '-' has higher precedence than '+'. That is wrong, and is contradicting with here: http://docs.python.org/3/reference/expressions.html#summary This should be made clear. ---------- assignee: docs@python components: Documentation messages: 175163 nosy: docs@python, fossilet priority: normal severity: normal status: open title: Numeric operator predecence confusing versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16438> _______________________________________

13 23

[issue12077] Harmonizing descriptor protocol documentation
by Davide Rizzo Aug. 29, 2019

Aug. 29, 2019

New submission from Davide Rizzo <sorcio(a)gmail.com>: There are three sources of information for the descriptor protocol: - Data model reference (Doc/reference/datamodel.rst) - Descriptor HowTo guide (Doc/howto/descriptor.rst) - PEP 252 A developer who already knows descriptor tipically reads the first one: object.__get__(self, instance, owner) "... owner is always the owner class ..." Reading a bit further there are the ways a descriptor can be called, and the "direct call" is x.__get__(a). That is, without the third argument (owner) specified. The how-to definition is slightly different: descr.__get__(self, obj, type=None) --> value Here the arguments have different names ("type" shadowing the type bultin) and it seems to be implied that the third argument is optional. The ClassMethod example at the end of the document seems to confirm this: def __get__(self, obj, klass=None): (though another example doesn't). And the method contains an explicit check on klass being None. Also it could be confusing that through the examples in the same document many different names are used for the same argument (type, objtype, klass), and all different than the name used in the reference. Lastly the PEP is more explicit: __get__(): a function callable with one or two arguments. [...] When X is None, the optional second argument, T, should be meta-object. [...] When both X and T are specified ... One more quirk: the reference explains the distinction between data and non-data descriptors, though says nothing about __set__ raising AttributeError for read-only data descriptors. My proposal: - use the same names for __get__ arguments throughout the documentation (both the reference and the tutorial), e.g. __get__(self, instance, owner) - decide whether the third argument should be optional, or state the common usage in the reference, and fix accordingly the examples in the howto - explain data, non-data and read-only descriptors in the __set__ reference, or more simply, how the defintion of __set__ affects these things. ---------- assignee: docs@python components: Documentation messages: 135974 nosy: davide.rizzo, docs@python priority: normal severity: normal status: open title: Harmonizing descriptor protocol documentation versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________

9 17

[issue15542] Documentation incorrectly suggests __init__ called after direct __new__ call
by Aaron Staley Aug. 26, 2019

Aug. 26, 2019

New submission from Aaron Staley: The documentation for __new__ at http://docs.python.org/reference/datamodel.html#object.__new__ is: """ object.__new__(cls[, ...]) Called to create a new instance of class cls. __new__() is a static method (special-cased so you need not declare it as such) that takes the class of which an instance was requested as its first argument. The remaining arguments are those passed to the object constructor expression (the call to the class). The return value of __new__() should be the new object instance (usually an instance of cls). Typical implementations create a new instance of the class by invoking the superclass’s __new__() method using super(currentclass, cls).__new__(cls[, ...]) with appropriate arguments and then modifying the newly-created instance as necessary before returning it. If __new__() returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to __new__(). If __new__() does not return an instance of cls, then the new instance’s __init__() method will not be invoked. __new__() is intended mainly to allow subclasses of immutable types (like int, str, or tuple) to customize instance creation. It is also commonly overridden in custom metaclasses in order to customize class creation. """ The problem is in this line: "If __new__() returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to __new__()." This is only true in the context of a constructor. In particular, directly calling cls.__new__(cls) will NOT call __init__. If I define a class: class C(object): def __new__(*args, **kwargs): print 'new', args, kwargs return object.__new__(*args,**kwargs) def __init__(self): print 'init' C() will result in __new__ and __init__ being both executed, but C.__new__(C) will only create the instance of C; it will not call __init__! The original documentation described in http://bugs.python.org/issue1123716 was more correct: "__new__ must return an object... If you return an existing object, the constructor call will still call its __init__ method unless the object is an instance of a different class..." That is __init__ is only being called in the context of an external constructor call. Proposed phrasing: "If __new__() is invoked during object construction (cls()) and it returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to the object constructor." ---------- assignee: docs@python components: Documentation messages: 167267 nosy: Aaron.Staley, docs@python priority: normal severity: normal status: open title: Documentation incorrectly suggests __init__ called after direct __new__ call versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15542> _______________________________________

6 9

[issue14112] tutorial intro talks of "shallow copy" concept without explanation
by Tshepang Lekhonkhobe Aug. 24, 2019

Aug. 24, 2019

New submission from Tshepang Lekhonkhobe <tshepang(a)gmail.com>: Relevant line: http://hg.python.org/cpython/file/e2eccc906354/Doc/tutorial/introduction.rs… When the concept is introduced, it appears like there's an assumption that the reader would know what it means. I'm curious if it's that common a term that it should be taken for granted, or if it deserves a definition. ---------- assignee: docs@python components: Documentation messages: 154151 nosy: docs@python, tshepang priority: normal severity: normal status: open title: tutorial intro talks of "shallow copy" concept without explanation versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

10 22

[issue12634] Random Remarks in class documentation
by Ashutosh Swain Aug. 22, 2019

Aug. 22, 2019

New submission from Ashutosh Swain <ats.engg(a)gmail.com>: URL: http://docs.python.org/tutorial/classes.html section: 9.4 Random Remarks The first sentense is bit confusing: "Data attributes override method attributes with the same name" Is it possible to change the sentense something like this: "Data attributes set through instance override method attributes with the same name" ---------- assignee: docs@python components: Documentation messages: 141073 nosy: ats.engg, docs@python priority: normal severity: normal status: open title: Random Remarks in class documentation type: feature request versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12634> _______________________________________

9 18

[issue14050] Tutorial, list.sort() and items comparability
by Sandro Tosi Aug. 22, 2019

Aug. 22, 2019

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: I'm providing patches for what reported at http://mail.python.org/pipermail/docs/2012-February/007481.html . I'm not sure on wording or even if we want them in the tutorial section, but I think it would be nice to have it documented nonetheless. ---------- assignee: docs@python components: Documentation files: list_sort-py27.diff keywords: patch messages: 153648 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: patch review status: open title: Tutorial, list.sort() and items comparability versions: Python 2.7, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file24557/list_sort-py27.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14050> _______________________________________

9 20

[issue16697] argparse kwarg 'choices' documentation
by wim glenn Aug. 17, 2019

Aug. 17, 2019

New submission from wim glenn: Any object that supports the in operator can be passed as the choices value, so dict objects, set objects, custom containers, etc. are all supported. (from http://docs.python.org/dev/library/argparse.html#choices ) Actual behaviour is contradicted by the docs - it seems the container must additionally be iterable. When using a custom container, argparse b0rks on trying to iterate through choices. Using a metavar prevents this, but it still breaks on cases where the element is not in the container. More details here: http://stackoverflow.com/questions/13833566/python-argparse-choices-from-an… ---------- assignee: docs@python components: Documentation messages: 177599 nosy: docs@python, wim.glenn priority: normal severity: normal status: open title: argparse kwarg 'choices' documentation type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16697> _______________________________________

3 3

[issue11165] Document PyEval_Call* functions
by Nick Coghlan Aug. 8, 2019

Aug. 8, 2019

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: There are currently undocumented PyEval_Call* equivalents to a number of the PyObject_Call* functions. Since there are resources out there on the web that direct people to use the currently undocumented PyEval functions, it would be good to document those properly, and recommend people typically use the PyObject_Call* variants instead (as the latter include all the stack and interpreter state integrity protection code, while the PyEval variants assume that has all already been handled). ---------- assignee: docs@python components: Documentation keywords: easy messages: 128248 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Document PyEval_Call* functions versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11165> _______________________________________

9 12

[issue13127] xml.dom.Attr.name is not labeled as read-only
by Dillon Amburgey July 13, 2019

July 13, 2019

New submission from Dillon Amburgey <dillona(a)dillona.com>: http://docs.python.org/library/xml.dom.html#dom-attr-objects does not label the name attribute as read-only (like localName) even though it is. ---------- assignee: docs@python components: Documentation messages: 145155 nosy: dillona, docs@python priority: normal severity: normal status: open title: xml.dom.Attr.name is not labeled as read-only _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13127> _______________________________________

8 10

[issue12217] Cross-link docs for faulthandler, traceback and pdb
by Éric Araujo July 13, 2019

July 13, 2019

New submission from Éric Araujo <merwok(a)netwok.org>: haypo suggested linking between traceback.print_tb and faulthandler.dump_traceback(). See also links between pdb and faulthandler could also be nice, if they explain briefly how the modules differ. ---------- assignee: docs@python components: Documentation keywords: easy messages: 137298 nosy: docs@python, eric.araujo, haypo priority: normal severity: normal stage: needs patch status: open title: Cross-link docs for faulthandler, traceback and pdb versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12217> _______________________________________

4 5

[issue15629] Run doctests in Doc/*.rst as part of regrtest
by Chris Jerdonek June 24, 2019

June 24, 2019

New submission from Chris Jerdonek: This issue is to start running (at least some of) the doctests in the Doc/ folder's *.rst files as part of regrtest. We will need a whitelist mechanism to tell regrtest which files to process since currently many doctests are not runnable (e.g. some kind of "doctest-safe" marker that can go in a file as suggested by Nick). See also the discussion thread started here: http://mail.python.org/pipermail/python-dev/2012-August/121304.html ---------- assignee: docs@python components: Documentation messages: 168036 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: Run doctests in Doc/*.rst as part of regrtest type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15629> _______________________________________

15 41

[issue13286] PEP 3151 breaks backward compatibility: it should be documented
by STINNER Victor May 13, 2019

May 13, 2019

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: The following example works on Python 2.7 and 3.2, but fails on Python 3.3: ----------- import errno import os try: os.rmdir("testdir") except: pass os.mkdir("testdir") try: try: os.mkdir("testdir") except IOError as exc: # If can't get proper access, then just forget about writing # the data. if exc.errno == errno.EACCES: pass else: raise except OSError as exc: # Probably another Python process already created the dir. if exc.errno == errno.EEXIST: pass else: raise except Exception: print("PEP 3151 broke backward compatibility on such pattern!") ----------- I noticed the problem while reading the changeset e4d44c2e8e81. ---------- assignee: docs@python components: Documentation messages: 146562 nosy: docs@python, flox, haypo, pitrou priority: normal severity: normal status: open title: PEP 3151 breaks backward compatibility: it should be documented versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13286> _______________________________________

5 8

[issue10536] Enhancements to gettext docs
by Éric Araujo May 9, 2019

May 9, 2019

New submission from Éric Araujo <merwok(a)netwok.org>: A patch made for #2504 revealed a bug in gettext.rst, and I’ve found a number of other things to change in the file. This is the first patch of a series of two or three. Barry, as the original author of the module and doc, I’d like your opinion on points 3, a, and b particularly. Patch is also uploaded to Rietveld for greater convenience: http://codereview.appspot.com/3333042/ (upload.py rocks) Summary: 1) Markup: Use modern class/method directives combo (yay DRY). Mark up variable parts in :file: constructs (e.g. :file:`{domain}.mo` will cause the HTML output to use var to indicate replaceable text). Also change some ``gettext`` to :program:`gettext` for consistency. 2) Fix a typo in lngettext doc (originally included in patch by Franz Glasner for #2504). 3) I had started to remove information about private attributes (_info, _charset), advertising public getter methods instead. Then I read the description of NullTranslations and realized the information was needed for subclasses. I’ve reverted my removals, but I still think the private attributes should be listed in a specific section for people writing subclasses and not in the rest of the text. If you’re okay, I’ll make a second patch. 4) Assorted wording changes, missing periods and hyphens, and other very small touch-ups: Turned a broken bare link into a working link with nice text; used the with statement in an example (we all love the with statement!); used two spaces after periods throughout (hello Fred Drake). Final note: lines have not been rewrapped, for diff clarity. When I commit part or all of this patch, I’ll make another commit to rewrap. Not addressed: a) The current docs is currently POSIX-specific. b) The docs take great care to explain that Unicode strings will be returned in different places, but this should not be so accented in 3.x docs IMO. I would just put a note somewhere near the top that all strings are str and remove the redundant sentences. Following that line of thought, I could group all l*gettext variants at the end of the list of methods, explaining that regular usage should just be happy with str objects and that l*gettext are available if people really want bytes. c) The file uses “built-in namespace” and “builtins namespace”, sometimes in neighbor paragraphs. :mod:`builtins` is not used, even in explanations of the install function/method. I don’t know if I should change that. d) Some capitalization patterns look strange to me: I have seen “I18N” and “L10N” in upper case nowhere else. Similarly, lower-case “id” looks stranger than “ID”. The latter is used for example in official GNU gettext docs. Am I going into foolish consistency territory or not? Thanks in advance for reviews and opinions. ---------- assignee: eric.araujo components: Documentation files: gettext-docs-1.diff keywords: needs review, patch messages: 122420 nosy: barry, docs@python, eric.araujo priority: normal severity: normal stage: patch review status: open title: Enhancements to gettext docs versions: Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file19819/gettext-docs-1.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10536> _______________________________________

8 17

[issue12188] PEP 7, C style: add ++ policy and explanation
by Terry J. Reedy May 8, 2019

May 8, 2019

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: In response to a discussion of a patch removing 'useless' post-increments, (which issue has apparently come up before) Guido posted "> Sorry to butt in here, but I agree with Eric that it was better > before. There is a common idiom, *pointer++ =<something>, and > whenever you see that you know that you are appending something to an > output buffer. Perhaps the most important idea here is that this > maintains the *invariant* "pointer points just after the last thing in > the buffer". Always maintaining the invariant is better than trying to > micro-optimize things so as to avoid updating dead values. The > compiler is better at that." A condensed version of the above added to PEP 7 would help new developers see the usage as local idiom rather than style bug. ---------- assignee: docs@python components: Documentation messages: 136991 nosy: docs@python, terry.reedy priority: normal severity: normal status: open title: PEP 7, C style: add ++ policy and explanation _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12188> _______________________________________

7 11

[issue11001] Various obvious errors in cookies documentation
by Luke Plant May 7, 2019

May 7, 2019

New submission from Luke Plant <L.Plant.98(a)cantab.net>: Docs for SimpleCookie, BaseCookie.value_encode and BaseCookie.value_decode are obviously incorrect. Attempt at patch attached. The error has existed in every Python version I've seen, I've tagged the ones I believe can receive fixes, sorry if I've made a mistake. Thanks. ---------- assignee: docs@python components: Documentation files: http_cookies_doc_corrections.diff keywords: patch messages: 126962 nosy: docs@python, spookylukey priority: normal severity: normal status: open title: Various obvious errors in cookies documentation versions: Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file20507/http_cookies_doc_corrections.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11001> _______________________________________

8 12

[issue10789] Lock.acquire documentation is misleading
by Jyrki Pulliainen April 26, 2019

April 26, 2019

New submission from Jyrki Pulliainen <jyrki(a)dywypi.org>: In threading module, the Lock.acquire documentation is misleading. The signature suggests that the blocking can be given as a keyword argument but that would lead to an TypeError, as thread.lock.acquire does not accept keyword arguments. The signature in documentation should be formatted as in thread.lock.acquire. ---------- assignee: docs@python components: Documentation messages: 124861 nosy: Jyrki.Pulliainen, docs@python priority: normal severity: normal status: open title: Lock.acquire documentation is misleading versions: Python 2.7, Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10789> _______________________________________

6 9

[issue10048] urllib.request documentation confusing
by Antoine Pitrou April 26, 2019

April 26, 2019

New submission from Antoine Pitrou <pitrou(a)free.fr>: The urllib.request documentation intermingles old 2.x urllib (FancyURLopener, etc.) with urllib2-inherited (*Handler, build_opener, etc.) primitives without making any distinction. This makes it rather confusing for the reader to figure out which ones to use. Ideally, the use of the old primitives should also be discouraged. ---------- assignee: docs@python components: Documentation messages: 118179 nosy: docs@python, orsenthil, pitrou priority: normal severity: normal stage: needs patch status: open title: urllib.request documentation confusing versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10048> _______________________________________

4 5

[issue16663] Poor documentation for METH_KEYWORDS
by r3m0t April 26, 2019

April 26, 2019

New submission from r3m0t: http://docs.python.org/3.3/c-api/structures.html#METH_KEYWORDS "Methods with these flags must be of type PyCFunctionWithKeywords. The function expects three parameters: self, args, and a dictionary of all the keyword arguments. The flag is typically combined with METH_VARARGS, and the parameters are typically processed using PyArg_ParseTupleAndKeywords()." The documentation doesn't mention the args/dictionary arguments will be NULL when there are no positional/keyword arguments. It might also be worth mentioning the arguments are in effect "borrowed" references. ---------- assignee: docs@python components: Documentation messages: 177341 nosy: docs@python, r3m0t priority: normal severity: normal status: open title: Poor documentation for METH_KEYWORDS versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16663> _______________________________________

2 2

[issue16652] socket.getfqdn docs are not explicit enough about the algorithm.
by R. David Murray April 26, 2019

April 26, 2019

New submission from R. David Murray: >From the docs it isn't quite clear if getfqnd() does the equivalent of: gethostbyaddr('127.0.0.1') or gethostbyaddr(gethostbyname(gethostname())) It matters which it is, when debugging a host's name configuration and DNS server problems. ---------- assignee: docs@python components: Documentation messages: 177236 nosy: docs@python, r.david.murray priority: normal severity: normal status: open title: socket.getfqdn docs are not explicit enough about the algorithm. type: behavior versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16652> _______________________________________

2 2

[issue16242] Pickle and __getattr__
by Joseph Fall April 26, 2019

April 26, 2019

New submission from Joseph Fall: This report is to re-raise an old issue from 2009: http://bugs.python.org/issue5370 Although that issue is marked as "fixed", I disagree that it was ever "fixed", and spent an evil day tracking it down. Use Case: - take two 3rd party packages: django and django-crispy-forms - django, deep in its inner-workings, uses Pickle - django-cripsy-forms implements the _getattr__ method in one of it's classes - when you put the two together such that django pickles a form, the python interpreter goes into a tailspin in very sinister and hard-to-track-down ways (different behaviour in 2.5, 2.6, 2.7, as noted in issue5370, which includes a simple test case) The "resolution" for issue5370 was to add some documentation to Pickle. But I would argue this is insufficient - the implementer of django-crispy-forms would have no reason to ever look at the Pickle docs, and so is very likely to implement this bug (which s/he did). Perhaps, if this issue cannot be resolved in code, as suggested by gagenellina back in 2009, at least some documentation could be added to __getattr__ (and others) warning that these methods could potentially be called before __init__ (similar to the documentation added to Pickle)? I'd be happy to draft a small bit of documentation for this, although if someone can think of a way to simply resolve this in Pickle so it does not cause the issue in the first place, that seems to me ideal. A test case is included with issue5370 ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 172993 nosy: docs@python, powderflask priority: normal severity: normal status: open title: Pickle and __getattr__ type: behavior versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16242> _______________________________________

2 2

[issue12957] mmap.resize changes memory address of mmap'd region
by Michael Schurter April 26, 2019

April 26, 2019

New submission from Michael Schurter <m(a)schmichael.com>: Since mmap.resize uses MREMAP_MAYMOVE on Linux, it would be nice to warn users that pointers into their memory mapped regions will be invalid after resizes. Linux's manpage offers the following explanation: "If the mapping is relocated, then absolute pointers into the old mapping location become invalid (offsets relative to the starting address of the mapping should be employed)." Since the only way I know of to use pointers into mmaps from pure Python is to use ctypes.<type>.from_buffer(<mmap>), perhaps clarification would be better in the ctypes docs. ---------- assignee: docs@python components: Documentation files: killctypes.py messages: 143845 nosy: docs@python, schmichael priority: normal severity: normal status: open title: mmap.resize changes memory address of mmap'd region type: feature request versions: Python 2.7 Added file: http://bugs.python.org/file23126/killctypes.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12957> _______________________________________

4 4

[issue14945] Setup & Usage documentation for selected stdlib modules
by Nick Coghlan April 26, 2019

April 26, 2019

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: Some stdlib modules have officially documented and supported behaviour when executed via -m. These should be referenced from the Setup & Usage documentation at http://docs.python.org/dev/using/index.html Current candidates: python -m unittest python -m timeit ---------- assignee: docs@python components: Documentation messages: 161832 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Setup & Usage documentation for selected stdlib modules type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14945> _______________________________________

6 11

[issue13282] the table of contents in epub file is too long
by wrobell April 11, 2019

April 11, 2019

New submission from wrobell <wrobell(a)pld-linux.org>: the table of contents in python documentation epub file is very very long. it takes several long minutes to jump from first page to a part containing language reference toc. imho it would be great if first page of epub file contained pointers to tutorial, lang ref, mod ref without detailed table of contents as it is at docs.python.org. ---------- assignee: docs@python components: Documentation messages: 146548 nosy: docs@python, wrobell priority: normal severity: normal status: open title: the table of contents in epub file is too long versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13282> _______________________________________

4 4

[issue13850] Summary tables for argparse add_argument options
by Nick Coghlan March 23, 2019

March 23, 2019

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: With the current argparse docs, it's very hard to get a quick reminder of how to spell the various parameters for add_argument, and just what they do. This issue suggests adding a "Quick Reference" section for add_argument, with the following elements: 1. Summary table with a one line description of each parameter 2. Summary table with a one line description of each alternative for the "action" parameter (including noting which other parameters are potentially relevant, such as 'choices' and 'metavar' for 'store' and 'const' for 'store_const') 3. Summary table with a one line description of each alternative for the "nargs" parameter ---------- assignee: docs@python components: Documentation messages: 151880 nosy: bethard, docs@python, ncoghlan priority: normal severity: normal status: open title: Summary tables for argparse add_argument options versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13850> _______________________________________

12 27

[issue14944] Setup & Usage documentation for pydoc
by Nick Coghlan March 20, 2019

March 20, 2019

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: pydoc is installed as a script by Python. It should be documented under http://docs.python.org/dev/using/index.html. ---------- assignee: docs@python components: Documentation messages: 161831 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Setup & Usage documentation for pydoc type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14944> _______________________________________

7 13

[issue13231] sys.settrace - document 'some other code blocks' for 'call' event type
by anatoly techtonik March 15, 2019

March 15, 2019

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/sys.html#sys.settrace While writing settrace function you need to know what kind of data is expected and how to get more information about it. Current documentation for sys.settrace doesn't give too much answers. To improve that situation at least with 'call' event: 1. Link 'frame' to the middle of table on inspect module page [1] 2. List all possible 'code blocks' for 'call' event (I know there is module in addition to function) 3. Provide example how to extract popular data for corresponding 'code block' (name for functions, name for modules, name for classes/methods, relative file path, line no, how to detect labmbda function) in a safe manner (inspect page contains some FUD about memory usage) 1. http://docs.python.org/library/inspect#types-and-members ---------- assignee: docs@python components: Documentation messages: 146009 nosy: docs@python, techtonik priority: normal severity: normal status: open title: sys.settrace - document 'some other code blocks' for 'call' event type _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13231> _______________________________________

2 2

[issue13277] tzinfo subclasses information
by Senthil Kumaran March 15, 2019

March 15, 2019

New submission from Senthil Kumaran <senthil(a)uthcode.com>: This was in the docs mailing list, not translated to bug report Paul Koning wrote: Section 8.1.6 of the library manual talks about utcoffset(dt)-dst(dt) as the "standard offset" and says that this should not depend on the date or +time but only on the location. This is not true as there cases were certain locations changed the time offsets as per their convenience. It is either a doc fix to remove that sentence if the datetime.astimezone does not depend upon utcoffset(dt)-dst(dt), or if it does, then it is a code fix. ---------- assignee: docs@python messages: 146501 nosy: docs@python, orsenthil priority: normal severity: normal stage: needs patch status: open title: tzinfo subclasses information type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13277> _______________________________________

5 5

[issue13074] Improve documentation of locale encoding functions
by Geoffrey Bache March 15, 2019

March 15, 2019

New submission from Geoffrey Bache <gjb1002(a)users.sourceforge.net>: The locale module provides locale.getdefaultlocale and locale.getpreferredencoding. The encodings returned by each are generally subtly different ('ISO8859-1' vs 'ISO-8859-1'), but the difference between these methods is not explained. A comment by Martin von Löwis from 2003 in http://bugs.python.org/issue813449 indicates that "getdefaultlocale should not be used in new code", if this is really the case then this should be in the docs. Anyone reading the docs from the top will currently encounter getdefaultlocale first and believe that this is the way to get the encoding. ---------- assignee: docs@python components: Documentation messages: 144677 nosy: docs@python, gjb1002 priority: normal severity: normal status: open title: Improve documentation of locale encoding functions versions: 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/issue13074> _______________________________________

5 5

[issue11776] types.MethodType() params and usage is not documented
by anatoly techtonik Feb. 24, 2019

Feb. 24, 2019

New submission from anatoly techtonik <techtonik(a)gmail.com>: types.MethodType(function, instance) is used as a replacement for new.instancemethod(function, instance, class), but this usage is not documented. ---------- assignee: docs@python components: Documentation messages: 133089 nosy: docs@python, techtonik priority: normal severity: normal status: open title: types.MethodType() params and usage is not documented versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________

13 31

[issue13456] Providing a custom HTTPResponse class to HTTPConnection
by R. David Murray Feb. 24, 2019

Feb. 24, 2019

New submission from R. David Murray <rdmurray(a)bitdance.com>: The doc string for HTTPConnection.getresponse mentions (in broken English) that the instance's response_class attribute determines what class gets instantiated for a response. The docs do not mention this attribute, nor any other way to control what class is used. Since this attribute already exists and is mentioned in the doc string, can we consider this a doc error and just document it? ---------- assignee: docs@python components: Documentation messages: 148136 nosy: docs@python, orsenthil, r.david.murray priority: normal severity: normal status: open title: Providing a custom HTTPResponse class to HTTPConnection versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13456> _______________________________________

5 5

[issue11352] Buf in cgi module doc
by Pierre Quentel Feb. 24, 2019

Feb. 24, 2019

New submission from Pierre Quentel <pierre.quentel(a)gmail.com>: Hi, I wrote a patch for the cgi module in version 3.2rc1 (#4953). Small changes should be done to the documentation of this module to reflect the changes in the module API : - in section "20.2.2. Using the cgi module" original text : "If a field represents an uploaded file, accessing the value via the value attribute or the getvalue() method reads the entire file in memory as a string. This may not be what you want. You can test for an uploaded file by testing either the filename attribute or the file attribute. You can then read the data at leisure from the file attribute:" proposed new text (for files, value is bytes, not string, and the read() method on file also returns bytes) : "If a field represents an uploaded file, accessing the value via the value attribute or the getvalue() method reads the entire file in memory as bytes. This may not be what you want. You can test for an uploaded file by testing either the filename attribute or the file attribute. You can then read the data at leisure from the file attribute (the read() and readline() methods will return bytes) :" - version 3.2 introduced a parameter "encoding" for the FieldStorage constructor, used to decode the bytes received on the HTTP connection for fields other than files. This encoding must the one defined in the HTML document holding the form submitted to the CGI script ; it is usually defined by a meta tag : <meta http-equiv="Content-type" content="text/html;charset=latin-1"> or by the Content-Type header for this document I'm not sure where this should be mentioned in the module documentation. Maybe in "20.2.9. Common problems and solutions" for the moment. But there are plans (#11066) to introduce another interface to change the encoding of sys.stdout in the CGI script itself, so another option would be to open a specific section about encodings Hope it's clear enough Pierre ---------- assignee: docs@python components: Documentation messages: 129691 nosy: docs@python, quentel priority: normal severity: normal status: open title: Buf in cgi module doc type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________

14 27

[issue15457] consistent treatment of generator terminology
by Chris Jerdonek Jan. 4, 2019

Jan. 4, 2019

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: The documentation on generators (outside of PEP 255) does not currently educate the reader on the more specific "generator function" and "generator iterator" terminology, or at least not in any consistent or systematic way. For example, the glossary includes only a single entry for "generator," and that entry does not mention the two more specific forms. I think it would help for general discourse purposes if this distinction were made clearer, while still continuing to allow for the use of the generic word "generator" when the context makes it clear. There are also cases where index entries can be improved in this regard, and where references to the section containing details about generators can still be added. I am in the process of completing a proposed patch. ---------- assignee: docs@python components: Documentation keywords: easy messages: 166474 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: consistent treatment of generator terminology versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15457> _______________________________________

4 12

[issue9842] Document ... used in recursive repr of containers
by Éric Araujo Nov. 20, 2018

Nov. 20, 2018

New submission from Éric Araujo <merwok(a)netwok.org>: Built-in containers like dict use an ellipsis to represent a recursive item. In the symbols index, “...” only links to the secondary prompt; I think it should also link to a paragraph explaining the display of recursive containers. ---------- assignee: docs@python components: Documentation keywords: easy messages: 116256 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: Document ... used in recursive repr of containers versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9842> _______________________________________

8 17

[issue14911] generator.throw() documentation inaccurate
by Kristján Valur Jónsson Oct. 17, 2018

Oct. 17, 2018

New submission from Kristján Valur Jónsson <kristjan(a)ccpgames.com>: the documentation for generator.throw() does not mention the fact that it has the same semantics for the three arguments as a "raise" expression has. The first two arguments can be: throw(exc_type, None) throw(exc_type, value) throw(exc_type, exc_instance) throw(exc_instance, None) ---------- assignee: docs@python components: Documentation messages: 161565 nosy: docs@python, kristjan.jonsson priority: normal severity: normal status: open title: generator.throw() documentation inaccurate versions: 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/issue14911> _______________________________________

5 12

[issue11233] clarifying Availability: Unix
by Sandro Tosi Oct. 15, 2018

Oct. 15, 2018

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: Hi, following up http://mail.python.org/pipermail/docs/2011-February/003083.html we have a chat on #python-dev on the topic, the situation is - all started with os.lchmod() and as.lchflags() methods not available on a Debian system - that's because POSIX does not require those functions and then Linux systems don't provide them - so we then thought about clarifying, only for those 2 methods, that they might not be available with a format like "availability: some unix systems" - then we noticed that on top of os doc there's a notice "An “Availability: Unix” note means that this function is commonly found on Unix systems. It does not make any claims about its existence on a specific operating system." and so we thought about linking every 'Availability: Unix' to that note - or transform that not in a footnote and link every 'Availability: Unix' for functions that might not be present to that footnote. It's enough for the conversation dump: ideas/suggestions? :) ---------- assignee: docs@python components: Documentation messages: 128746 nosy: docs@python, sandro.tosi priority: normal severity: normal status: open title: clarifying Availability: Unix _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________

11 25

[issue15258] argparse documentation: Improve optparse section regarding allow_interspersed_args
by Nefarious CodeMonkey, Jr. Aug. 14, 2018

Aug. 14, 2018

New submission from Nefarious CodeMonkey, Jr. <nejucomo(a)users.sourceforge.net>: It was not obvious from the documentation on argparse how to emulate the optparse.OptionParser.allow_interspersed_args feature. Please add something like the following to the section titled "Upgrading optparse code" (see: http://docs.python.org/library/argparse.html#upgrading-optparse-code ) """ * If the optparse code sets allow_interspersed_args to False, then add an argparse positional argument with nargs=argparse.REMAINDER """ ---------- assignee: docs@python components: Documentation messages: 164702 nosy: docs@python, nejucomo priority: normal severity: normal status: open title: argparse documentation: Improve optparse section regarding allow_interspersed_args type: enhancement versions: 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/issue15258> _______________________________________

5 4

[issue13574] refresh example in doc for Extending and Embedding
by Florent Xicluna Aug. 4, 2018

Aug. 4, 2018

New submission from Florent Xicluna <florent.xicluna(a)gmail.com>: The example uses PyInstanceObject which is Python 2 only (old-style classes). http://docs.python.org/dev/extending/newtypes.html#weak-reference-support ---------- assignee: docs@python components: Documentation, Extension Modules messages: 149183 nosy: docs@python, flox priority: normal severity: normal stage: needs patch status: open title: refresh example in doc for Extending and Embedding type: behavior versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13574> _______________________________________

6 5

[issue12743] C API marshalling doc contains XXX
by JJeffries July 26, 2018

July 26, 2018

New submission from JJeffries <jamesjeffries1(a)gmail.com>: The Python C API manual page for data marshaling contains the following paragraph. XXX What about error detection? It appears that reading past the end of the file will always result in a negative numeric value (where that’s relevant), but it’s not clear that negative values won’t be handled properly when there’s no error. What’s the right way to tell? Should only non-negative values be written using these routines? I suggest that the XXX should be removed as it is unclear why it's there. Patch to follow in the next couple of days if others agree. ---------- assignee: docs@python components: Documentation messages: 141959 nosy: JJeffries, docs@python priority: normal severity: normal status: open title: C API marshalling doc contains XXX _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12743> _______________________________________

7 13

[issue13525] Tutorial: Example of Source Code Encoding triggers error
by Nicolas Goutte May 9, 2018

May 9, 2018

New submission from Nicolas Goutte <nicolas.goutte(a)extragroup.de>: Current Behaviour The tutorial of Python 3.2.x has an example to set an encoding in a source file: http://docs.python.org/py3k/tutorial/interpreter.html#source-code-encoding It explains to set the following line at the start of the source code: # -*- coding: cp-1252 -*- However when done exactly so, Python raises the following exception: SyntaxError: encoding problem: with BOM The problem seems to be that Python knows Windows codepage 1252 as windows-1252 (its IANA charset name, see http://www.iana.org/assignments/charset-reg/windows-1252 ) or alternatively as cp1252 (without dash) but not as cp-1252 (with dash). As this is an example in the tutorial is particularly problematic, as users might not understand how to do it correctly. This is still the case in the tutorial of Python 3.3 alpha: http://docs.python.org/dev/tutorial/interpreter.html#source-code-encoding Expected Behaviour The tutorial should give a correct example, for example with: # -*- coding: windows-1252 -*- Alternatively a totally other example as for Python 2.7 would be nice too: http://docs.python.org/tutorial/interpreter.html#source-code-encoding Notes: I have tested this with following Python implementations: - Python 3.2.1 (openSUSE 12.1) on Linux - Python 3.2.2 on Windows 7 SP1 64 Bits - Python 3.2.2 on MacOS 10.5.8 (Always on the command line; I have not tested in IDLE.) ---------- assignee: docs@python components: Documentation files: cp_1252broken.py messages: 148798 nosy: docs@python, nicolasg priority: normal severity: normal status: open title: Tutorial: Example of Source Code Encoding triggers error versions: Python 3.2 Added file: http://bugs.python.org/file23840/cp_1252broken.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13525> _______________________________________

5 14

[issue13677] correct docstring for builtin compile
by Jim Jewett March 22, 2018

March 22, 2018

New submission from Jim Jewett <jimjjewett(a)gmail.com>: The current docstring for compile suggests that the flags are strictly for selecting future statements. These are not the only flags. It also suggests that the source must be source code and the result will be bytecode, which isn't quite true. I suggest changing: "The flags argument, if present, controls which future statements influence the compilation of the code." to: "The flags argument, if present, largely controls which future statements influence the compilation of the code. (Additional flags are documented in the AST module.)" ---------- assignee: docs@python components: Documentation files: bltinmodule.c.patch keywords: patch messages: 150337 nosy: Jim.Jewett, docs@python priority: normal severity: normal status: open title: correct docstring for builtin compile type: behavior Added file: http://bugs.python.org/file24105/bltinmodule.c.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13677> _______________________________________

4 6

[issue11015] Bring test.support docs up to date
by Nick Coghlan Feb. 11, 2018

Feb. 11, 2018

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: The test.support docs are there to help CPython devs with writing good unit tests more easily. There are a few additions we've made in recent years that haven't made it into the .rst file, so it is easy to miss useful tools if you don't go looking through the module source code. There are some other helper modules (such as test.script_helper) that could also stand to be made easier to find. Fixing this is just a matter of doing a pass through test.support and the test directory looking for things that might be worth mentioning in the test package docs. ---------- assignee: docs@python keywords: easy messages: 127086 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Bring test.support docs up to date type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11015> _______________________________________

11 36

[issue8722] Documentation for __getattr__
by Paul Davis Feb. 4, 2018

Feb. 4, 2018

New submission from Paul Davis <paul.joseph.davis(a)gmail.com>: The docs for __getattr__ in the object model section could be more specific on the behavior when a @property raises an AttributeError and there is a custom __getattr__ defined. Specifically, it wasn't exactly clear that __getattr__ would be invoked after a @property was found and evaluated. The attached script demonstrates the issue on OS X 10.6, Python 2.6.1 I'm thinking something along the lines of: If the attribute search encounters an AttributeError (perhaps due to a @property raising the error) the search is considered a failure and __getattr__ is invoked. ---------- assignee: docs@python components: Documentation files: example.py messages: 105790 nosy: Paul.Davis, docs@python priority: normal severity: normal status: open title: Documentation for __getattr__ type: feature request versions: Python 2.6 Added file: http://bugs.python.org/file17349/example.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8722> _______________________________________

8 23

[issue11023] pep 227 missing text
by Alan Isaac Jan. 25, 2018

Jan. 25, 2018

New submission from Alan Isaac <alan.isaac(a)gmail.com>: In PEP 227 missing text is marked with XXX. Most of this is just calls for examples and elaboration. However under the Implementation section XXX marks a substantive question about the documentation. Fixing this may be low priority, but a tracker search suggested it is currently not even being tracked ... ---------- assignee: docs@python components: Documentation messages: 127184 nosy: aisaac, docs@python priority: normal severity: normal status: open title: pep 227 missing text type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11023> _______________________________________

4 3

[issue12706] timeout sentinel in ftplib and poplib
by Senthil Kumaran Jan. 24, 2018

Jan. 24, 2018

New submission from Senthil Kumaran <senthil(a)uthcode.com>: - ftplib and poplib, has them as timeout=None, while they default to socket._GLOBAL_DEFAULT_TIMEOUT object. This is wrong; someone may pass None thinking it will trigger the default behaviour, and have nasty surprises. ---------- assignee: docs@python messages: 141740 nosy: docs@python, orsenthil priority: normal severity: normal stage: needs patch status: open title: timeout sentinel in ftplib and poplib type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12706> _______________________________________

5 7

[issue15221] os.path.is*() may return False if path can't be accessed
by Giampaolo Rodola' Jan. 14, 2018

Jan. 14, 2018

New submission from Giampaolo Rodola' <g.rodola(a)gmail.com>: It seems a doc fix is the best way to go, in which case I leave this one to a native English speaker: http://mail.python.org/pipermail/python-dev/2012-June/120788.html Alternatively a new 'strict' parameter has been proposed as a workaround: http://mail.python.org/pipermail/python-dev/2012-June/120800.html ---------- assignee: docs@python components: Documentation messages: 164307 nosy: christian.heimes, docs@python, eric.araujo, ezio.melotti, georg.brandl, giampaolo.rodola, ncoghlan priority: normal severity: normal status: open title: os.path.is*() may return False if path can't be accessed versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15221> _______________________________________

7 9

[issue11260] smtpd-as-a-script feature should be documented and should use argparse
by Xavier Morel Jan. 9, 2018

Jan. 9, 2018

New submission from Xavier Morel <xavier.morel(a)masklinn.net>: argparse has been merged to the standard library in 3.2, and (tell me if I'm wrong) would therefore be the "best-practices" way to parse command-line arguments. Numerous stdlib modules can be used as scripts, but they tend to have ad-hoc documentation (if they are at all documented) and arguments parsing (using any of the 4 available methods in Python: straight from sys.argv, getopt, optparse and argparse). I picked smtpd as a first shot since it does something useful (SMTP proxy) and has a pretty good (if ad-hoc) command-line documentation. smtpd is currently using getopt for its options parsing and the argument parsing is very cleanly factored: the port only had to replace the implementation of the `parseargs` function (and add and remove some helpers). * The port keeps the existing arguments semantics (including the mandatory host:port syntax for the local and remote specs if overridden) * The port tries to maintain the old error messages, but due to the way argparse works (or the way I used it for the specs) the parity is not perfect when providing incorrect specs * The CLI help uses argparse's formatting, and the documentation for the local and remote specs was set on these arguments rather than as an epilog. The version string was also removed from the help screen * Because they are set by argparse's arguments validation, the status codes on incorrect arguments are slightly different: - running smtpd.py as a regular user without the `--nosetuid` flag still exits with status 1 - providing incorrect spec formats (missing or non-int port) or providing too many positional arguments (3 or more) now exits with status 2 (formerly 1) ---------- assignee: docs@python components: Documentation, Library (Lib) files: smtpd-to-argparse.diff keywords: patch messages: 128917 nosy: barry, docs@python, xmorel priority: normal severity: normal status: open title: smtpd-as-a-script feature should be documented and should use argparse versions: Python 3.3 Added file: http://bugs.python.org/file20812/smtpd-to-argparse.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11260> _______________________________________

8 18

[issue14124] _pickle.c comment/documentation improvement
by Merlijn van Deen Nov. 9, 2017

Nov. 9, 2017

New submission from Merlijn van Deen <valhallasw(a)gmail.com>: As suggested by loewis in msg154233, I created some documentation to help people get started with _pickle.c. ---------- assignee: docs@python components: Documentation, Extension Modules files: _pickle_c_doc.diff keywords: patch messages: 154284 nosy: docs@python, valhallasw priority: normal severity: normal status: open title: _pickle.c comment/documentation improvement type: enhancement versions: Python 3.3 Added file: http://bugs.python.org/file24641/_pickle_c_doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14124> _______________________________________

3 4

[issue11253] autodocument first appearance of ctypes.wintypes constants
by anatoly techtonik Nov. 8, 2017

Nov. 8, 2017

New submission from anatoly techtonik <techtonik(a)gmail.com>: I've just noticed that my application is incompatible with Python 2.5, because ctypes.wintypes is missing SHORT constants. However, I can't find the information when these symbols were introduced first. To prevent such confusion in future it would be nice to extract symbol information for each Python release and automatically include the version of the first appearance in documentation. ---------- assignee: docs@python components: Documentation messages: 128893 nosy: docs@python, techtonik priority: normal severity: normal status: open title: autodocument first appearance of ctypes.wintypes constants versions: Python 2.5, Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11253> _______________________________________

6 7

[issue15472] Itertools doc summary table misdocuments some arguments
by Éric Araujo Sept. 15, 2017

Sept. 15, 2017

New submission from Éric Araujo <merwok(a)netwok.org>: In the tables near the top of http://docs.python.org/library/itertools , some functions like cycle have an example that uses “seq”, which is interpreted as “sequence” but the functions do work with any iterable. ---------- assignee: docs@python components: Documentation messages: 166594 nosy: docs@python, eric.araujo, rhettinger priority: normal severity: normal status: open title: Itertools doc summary table misdocuments some arguments versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15472> _______________________________________

4 7

[issue15427] Describe use of args parameter of argparse.ArgumentParser.parse_args
by Steven Bethard Sept. 9, 2017

Sept. 9, 2017

New submission from Steven Bethard <steven.bethard(a)gmail.com>: >From http://bugs.python.org/issue14191#msg155202: ArgumentParser.parse_args(args=None, namespace=None) ... However, nowhere is the args= parameter explained. One example is given at the end of 15.4.4.6 showing the use of args= which apparently accepts a list of parameters, similar to the positional list of parameters that are used in all the other examples. It might be nice to clarify that. ---------- assignee: docs@python components: Documentation messages: 166174 nosy: bethard, docs@python priority: normal severity: normal status: open title: Describe use of args parameter of argparse.ArgumentParser.parse_args type: behavior versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15427> _______________________________________

5 10

[issue12067] Doc: remove errors about mixed-type comparisons.
by Terry J. Reedy Aug. 24, 2017

Aug. 24, 2017

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: Current 3.2 doc, 5.9. Comparisons, has this paragraph about mixed-type comparisons. "The operators <, >, ==, >=, <=, and != compare the values of two objects. The objects need not have the same type. If both are numbers, they are converted to a common type. Otherwise, the == and != operators *always* consider objects of different types to be unequal, while the <, >, >= and <= operators raise a TypeError when comparing objects of different types that do not implement these operators for the given pair of types. You can control comparison behavior of objects of non-built-in types by defining rich comparison methods like __gt__(), described in section Basic customization." Sentence 3: "If both are numbers, they are converted to a common type." I suspect it would be more true to say 'common internal type' as I would not think it a language requirement to produce Python objects. In any case, I think it is only true for built-in number types, and I do not see that qualification anywhere previously. That aside, it does not appear to be true for Decimals and Fractions in 2.7.1. Sentence 4: first clause is only true for built-in types. That qualification is not obvious to everyone, as evidenced by a current python-list sub thread. For 2.7, which has a different continuation, I suggest adding 'built-in' before 'objects of'. For 3.2/3, I suggest deleting '*always*' and adding a comma after 'TypeError' so that the 'when' condition applies to equality comparisons also. After discussion about same-type comparisons, there is another paragraph about mixed-type comparison: "Comparison of objects of the differing types depends on whether either of the types provide explicit support for the comparison. Most numeric types can be compared with one another, but comparisons of float and Decimal are not supported to avoid the inevitable confusion arising from representation issues such as float('1.1') being inexactly represented and therefore not exactly equal to Decimal('1.1') which is. When cross-type comparison is not supported, the comparison method returns NotImplemented. This can create the illusion of non-transitivity between supported cross-type comparisons and unsupported comparisons. For example, Decimal(2) == 2 and 2 == float(2) but Decimal(2) != float(2)." I suggest deleting this entirely. The first sentence and first clause of the second repeat what was said above. The rest is obsolete as float/decimal comparisons *are* implemented in 2.7.1 and 3.2.0. ---------- assignee: docs@python components: Documentation keywords: easy messages: 135873 nosy: docs@python, rhettinger, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Doc: remove errors about mixed-type comparisons. versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12067> _______________________________________

15 71

[issue12887] Documenting all SO_* constants in socket module
by Sandro Tosi Aug. 22, 2017

Aug. 22, 2017

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: spinning off msg142613 - it would be interesting to have in the socket module documentation also an explanation of all the several SO_ flags available; even a compact table could be ok; or even a link to a remote reference for them. ---------- assignee: docs@python components: Documentation messages: 143428 nosy: docs@python, eric.araujo, ezio.melotti, sandro.tosi priority: normal severity: normal stage: needs patch status: open title: Documenting all SO_* constants in socket module versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12887> _______________________________________

5 5

[issue14345] Document socket.SOL_SOCKET
by anatoly techtonik Aug. 10, 2017

Aug. 10, 2017

New submission from anatoly techtonik <techtonik(a)gmail.com>: socket.get/setsockopt() docs can be improved by providing description for SOL_SOCKET constant, and link to source code for other level constants and socket level options. ---------- assignee: docs@python components: Documentation messages: 156140 nosy: docs@python, techtonik priority: normal severity: normal status: open title: Document socket.SOL_SOCKET _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14345> _______________________________________

3 3

[issue11230] "Full unicode import system" not in 3.2
by John July 18, 2017

July 18, 2017

New submission from John <jh45dev(a)gmail.com>: A few months ago I read that in 3.2 it will be possible to import modules that are located on paths containing any unicode character. (more precisely, with chars not in the local code page) After an hour or two trying to get this to work in 3.2rc3, I went looking for clues, and found these 2 messages in which Victor Stinner says this feature is delayed until Python 3.3: http://bugs.python.org/issue3080#msg126514 http://bugs.python.org/issue10828#msg125787 Could you please make it clear in documentation and web pages, that this feature is not working yet. The Python 3.2 download page includes this: "countless fixes regarding bytes/string issues; among them full support for a bytes environment (filenames, environment variables)" and I guessed this must cover importing from any unicode path, as there was no mention that such importing had been abandoned for this version. -- jh ---------- assignee: docs@python components: Documentation messages: 128711 nosy: docs@python, jh45 priority: normal severity: normal status: open title: "Full unicode import system" not in 3.2 versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11230> _______________________________________

7 11

[issue15360] Behavior of assigning to __dict__ is not documented
by Davide Rizzo July 13, 2017

July 13, 2017

New submission from Davide Rizzo <sorcio(a)gmail.com>: The documentation (at least the obvious places, see Doc/reference/datamodel.rst) says classes and class instances have the '__dict__' attribute, but nothing is said about what happens when assigning to it (like obj.__dict__ = something). As far as I understand that's undefined behavior and other implementations may not work the same as CPython (and CPython itself behaves differently between versions). I'd submit a documentation patch if I knew how to specify this matter. Maybe just say the behavior is not defined? ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 165538 nosy: davide.rizzo, docs@python priority: normal severity: normal status: open title: Behavior of assigning to __dict__ is not documented versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15360> _______________________________________

8 8

[issue10438] list an example for calling static methods from WITHIN classes
by Ian July 12, 2017

July 12, 2017

New submission from Ian <ifreecarve(a)gmail.com>: Concerning this section of the docs: http://docs.python.org/library/functions.html#staticmethod There is no example for calling a static method from another static method within the same class. As I discovered later, it's simple: C.f() -- from inside the class or outside it. A total newbie will accept this and move on... but in other programming languages, it's frowned upon to the class name from within the class. For example, in PHP you use the "self::" prefix and Java you don't need a prefix at all. So, even though I had it right the first time, it didn't SEEM right... so I went on a wild goose chase, for nothing. Googling "java call static method" will get you java documentation that lists both cases, as does "c++ call static method" and "php call static method". I feel that by adding "Note: you must also use the C.f() syntax when calling from within the class", the documentation will be more complete. ---------- assignee: docs@python components: Documentation messages: 121314 nosy: docs@python, ifreecarve priority: normal severity: normal status: open title: list an example for calling static methods from WITHIN classes type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10438> _______________________________________

7 19

[issue11681] -b option undocumented
by Éric Araujo May 13, 2017

May 13, 2017

New submission from Éric Araujo <merwok(a)netwok.org>: Python 2 has a -b command-line option which is undocumented. It is used by the warnings machinery to decide to warn about (-b) or raise an error (-bb) if someone uses str(bytes) or str(buffer) (explanation courtesy of grep and Python/pythonrun.c). ---------- assignee: docs@python components: Documentation keywords: easy messages: 132195 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: -b option undocumented versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11681> _______________________________________

11 22

[issue15346] Tkinter dnd has no documentation
by Daniel Swanson April 30, 2017

April 30, 2017

New submission from Daniel Swanson <popcorn.tomato.dude(a)gmail.com>: The title should be self explanatory. I needed Drag-and-drop for a project I was working on, (maybe I shouldn't be refering to it in the past tense as I haven't started yet) so I checked the documentation for tkinter and found: 3.3.0 b1 tkinter.dnd Drag-and-drop support for tkinter. This is experimental and should become deprecated when it is replaced with the Tk DND. 3.2.2 (and .2.3) tkinter.dnd Drag-and-drop support for tkinter. This is experimental and should become deprecated when it is replaced with the Tk DND. 2.7.3 Tkdnd Drag-and-drop support for Tkinter. This is experimental and should become deprecated when it is replaced with the Tk DND. I think that tkinter.dnd needs some documentation, whether or not it is replaced with Tk DND. ---------- assignee: docs@python components: Documentation messages: 165392 nosy: docs@python, weirdink13 priority: normal severity: normal status: open title: Tkinter dnd has no documentation versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15346> _______________________________________

4 10

[issue15369] pybench and test.pystone poorly documented
by Florent Xicluna March 31, 2017

March 31, 2017

New submission from Florent Xicluna <florent.xicluna(a)gmail.com>: The benchmarking tools "pystones" and "pybench" which are shipped with the Python standard distribution are not documented. The only information is in the what's-new for Python 2.5: http://docs.python.org/dev/whatsnew/2.5.html?highlight=pybench#new-improved… IMHO, they should be mentioned somewhere in the HOWTOs, the FAQ or the standard library documentation ("Development Tools" or "Debugging and Profiling") ---------- assignee: docs@python components: Benchmarks, Documentation messages: 165603 nosy: docs@python, flox priority: normal severity: normal status: open title: pybench and test.pystone poorly documented type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15369> _______________________________________

7 17

[issue16011] "in" should be consistent with return value of __contains__
by Neal Parikh March 29, 2017

March 29, 2017

New submission from Neal Parikh: The Python 2.7.3 documentation says the following about defining __contains__: "Called to implement membership test operators. Should return true if item is in self, false otherwise. For mapping objects, this should consider the keys of the mapping rather than the values or the key-item pairs." This suggests that while you should return True/False, you don't need to. Also, the documentation doesn't say that if you return a value other than True or False, it will silently coerce other values to be True or False when you use "in". For example: >>> class Foo(object): ... def __contains__(self, item): return 42 ... >>> foo = Foo() >>> 3 in foo True >>> foo.__contains__(3) 42 When __contains__ is defined, "in" should return whatever __contains__ returns, even if this value is neither True nor False. That would be consistent with, for example, the comparison operators: You can return anything from __lt__ and "x < 4" will correctly pass along that value regardless of what it is. ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 171085 nosy: docs@python, nparikh priority: normal severity: normal status: open title: "in" should be consistent with return value of __contains__ type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16011> _______________________________________

10 25

[issue15657] Error in Python 3 docs for PyMethodDef
by Sandro Tosi Feb. 22, 2017

Feb. 22, 2017

New submission from Sandro Tosi: Hello, it has been reported at http://mail.python.org/pipermail/docs/2012-April/008215.html but given it raises some question whether it's a bug in the doc or in the code, i'd rather report the issue here and hear what other think: >>> In the Python 3.2.2 documentation (and earlier Python 3 versions), in the Python/C API Reference Manual, chapter Object Implementation Support, the documentation for PyMethodDef says: The ml_flags field is a bitfield which can include the following flags. The individual flags indicate either a calling convention or a binding convention. Of the calling convention flags, only METH_VARARGS and METH_KEYWORDS can be combined (but note that METH_KEYWORDS alone is equivalent to METH_VARARGS | METH_KEYWORDS). The bit in the parenthetical is incorrect. If you take a look at PyCFunction_Call in Objects/methodobject.c, you will find a switch for METH_VARARGS | METH_KEYWORDS, but no switch for METH_KEYWORDS. Hence, using METH_KEYWORDS will land you with a SystemError that complains about METH_OLDARGS. This is either a bug in the documentation, or a bug in Python. In this case, since the code has persisted through three major revisions of Python 3, I suggest that the bug _is_ in the documentation (whether it should be or not), since changing the code for this at this late date means a programmer has to use METH_VARARGS | METH_KEYWORDS anyway for compatibility. It may be work pointing out specifically in the documentation that just using METH_KEYWORDS will not work. <<< ---------- assignee: docs@python components: Documentation messages: 168226 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: patch review status: open title: Error in Python 3 docs for PyMethodDef versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________

12 18

[issue10938] Undocumented option for datetime.strftime: %s
by Humberto Diogenes Feb. 22, 2017

Feb. 22, 2017

New submission from Humberto Diogenes <humberto(a)digi.com.br>: On some systems, datetime.strftime() accepts a %s format string that returns epoch / UNIX timestamp, but this behavior is not documented at http://docs.python.org/library/datetime.html Python 2.7 (r27:82508, Jul 3 2010, 21:12:11) [GCC 4.0.1 (Apple Inc. build 5493)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import datetime >>> datetime.datetime.now().strftime('%s') '1295376929' ---------- assignee: docs@python components: Documentation messages: 126481 nosy: docs@python, hdiogenes priority: normal severity: normal status: open title: Undocumented option for datetime.strftime: %s versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10938> _______________________________________

7 9

[issue11924] Pickle and copyreg modules doesn't document the interface
by Jesús Cea Avión Feb. 18, 2017

Feb. 18, 2017

New submission from Jesús Cea Avión <jcea(a)jcea.es>: Python 3.2 here. "copyreg" module documentation says "See the pickle module for more details on the interface expected of function and constructor.", but I don't see any useful "copyreg" reference in pickle documentation. Some examples would be useful here, too. ---------- assignee: docs@python messages: 134416 nosy: docs@python, jcea priority: normal severity: normal status: open title: Pickle and copyreg modules doesn't document the interface versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11924> _______________________________________

5 6

[issue11173] Undocumented public APIs in Python 3.2
by Marc-Andre Lemburg Feb. 14, 2017

Feb. 14, 2017

New submission from Marc-Andre Lemburg <mal(a)egenix.com>: Mark Shannon on python-dev: The following API functions were removed from 3.1.3: PyAST_Compile PyCObject_AsVoidPtr PyCObject_FromVoidPtr PyCObject_FromVoidPtrAndDesc PyCObject_GetDesc PyCObject_Import PyCObject_SetVoidPtr PyCode_CheckLineNumber Py_CompileStringFlags PyEval_CallObject PyOS_ascii_atof PyOS_ascii_formatd PyOS_ascii_strtod PyThread_exit_prog PyThread__PyThread_exit_prog PyThread__PyThread_exit_thread PyUnicode_SetDefaultEncoding And the following were added to 3.2, of which only 2 are documented: PyArg_ValidateKeywordArguments PyAST_CompileEx Py_CompileString Py_CompileStringExFlags PyErr_NewExceptionWithDoc (documented) PyErr_SyntaxLocationEx PyErr_WarnFormat PyFrame_GetLineNumber PyImport_ExecCodeModuleWithPathnames PyImport_GetMagicTag PyLong_AsLongLongAndOverflow (documented) PyModule_GetFilenameObject Py_SetPath PyStructSequence_GetItem PyStructSequence_NewType PyStructSequence_SetItem PySys_AddWarnOptionUnicode PySys_AddXOption PySys_FormatStderr PySys_FormatStdout PySys_GetXOptions PyThread_acquire_lock_timed PyType_FromSpec PyUnicode_AsUnicodeCopy PyUnicode_AsWideCharString PyUnicode_EncodeFSDefault PyUnicode_FSDecoder Py_UNICODE_strcat Py_UNICODE_strncmp Py_UNICODE_strrchr PyUnicode_TransformDecimalToASCII For added confusion PySys_SetArgvEx is documented as new in 3.2, but exists in 3.1.3 Note that this only include functions. The API also includes a number of macros such as Py_False and Py_RETURN_FALSE, types , and data like PyBool_Type. ---------- assignee: docs@python components: Documentation messages: 128294 nosy: docs@python, lemburg priority: normal severity: normal status: open title: Undocumented public APIs in Python 3.2 versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11173> _______________________________________

5 7

[issue11726] linecache becomes specific to Python scripts in Python 3
by STINNER Victor Feb. 9, 2017

Feb. 9, 2017

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: linecache document doesn't tell that the module reads the #coding:xxx cookie to get the encoding of the Python file. linecache reads this cookie since 41665 (May 09 2007). "The linecache module allows one to get any line from any file, ..." => "any file"! And the example uses /etc/passwd which is not a Python file. Not only it reads the #coding:xxx cookie, but updatecache() tries also a PEP 302 loader to read the file. linecache should be marked as very specific to Python scripts, or it should be patched to become more generic (don't read the cookie / use loader by default). Note: the locale encoding may change between to calls to the linecache module. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 132641 nosy: docs@python, haypo priority: normal severity: normal status: open title: linecache becomes specific to Python scripts in Python 3 versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11726> _______________________________________

8 16

[issue13196] subprocess: undocumented if shell=True is necessary to find executable in Windows PATH
by anatoly techtonik Feb. 3, 2017

Feb. 3, 2017

New submission from anatoly techtonik <techtonik(a)gmail.com>: The reason I ask is this changeset - http://code.google.com/p/spyderlib/source/detail?spec=svne5d86b685619a470d5… - seems like without shell=True, subprocess.Popen is unable to find Mercurial executable in PATH. ---------- assignee: docs@python components: Documentation messages: 145664 nosy: docs@python, techtonik priority: normal severity: normal status: open title: subprocess: undocumented if shell=True is necessary to find executable in Windows PATH _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13196> _______________________________________

5 6

[issue11670] configparser read_file now iterates over f, docs still say it calls readline
by Larry Hastings Jan. 29, 2017

Jan. 29, 2017

New submission from Larry Hastings <larry(a)hastings.org>: The documentation for configparser.RawConfigParser.read_file() states: "Read and parse configuration data from the file or file-like object in f (only the readline() method is used)." This was true in Python 3.1 and before. However in 3.2 the implementation of read_file changed. It no longer calls readline(). Instead, it iterates over the file object. Whoever made this change neglected to * fix the docs, or apparently * tell anybody. I've got the commit bit, so I'd be happy to fix this. I'd like to add it to the What's New In Python 3.2 as well; there's a section about configparser changes that would be perfect. Is it permissible to change the What's New document ex post facto like this? (Adding rhettinger so he can answer this.) ---------- assignee: docs@python components: Documentation messages: 132075 nosy: docs@python, larry, rhettinger priority: low severity: normal stage: needs patch status: open title: configparser read_file now iterates over f, docs still say it calls readline type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11670> _______________________________________

5 9

[issue15997] NotImplemented needs to be documented
by Max Jan. 21, 2017

Jan. 21, 2017

New submission from Max: Quoting from http://docs.python.org/reference/datamodel.html#the-standard-type-hierarchy: NotImplemented This type has a single value. There is a single object with this value. This object is accessed through the built-in name NotImplemented. Numeric methods and rich comparison methods may return this value if they do not implement the operation for the operands provided. (The interpreter will then try the reflected operation, or some other fallback, depending on the operator.) Its truth value is true. This is not a sufficient description of NotImplemented behavior. What does it mean "reflected operation" (I assume it is other.__eq__(self), but it needs to be clarified), and what does it mean "or some other fallback" (wouldn't developers need to know?). It also doesn't state what happens if the reflected operation or the fallback again return NotImplemented. The rest of the documentation doesn't seem to talk about this either, despite several mentions of NotImplemented, with references to other sections. This is particularly serious problem because Python's behavior changed in this respect not that long ago. ---------- assignee: docs@python components: Documentation messages: 170860 nosy: docs@python, max priority: normal severity: normal status: open title: NotImplemented needs to be documented type: enhancement versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15997> _______________________________________

6 9

[issue15527] Double parents in functions references
by Serhiy Storchaka Jan. 14, 2017

Jan. 14, 2017

New submission from Serhiy Storchaka: :c:func:`PyMem_Malloc(n)` on Doc/c-api/memory.rst:109 rendered in HTML as <tt class="xref c c-func docutils literal"><span class="pre">PyMem_Malloc(1)()</span></tt> (note double parents). There are many other examples on this and other pages. The issue is actual for all modern versions of Python. ---------- assignee: docs@python components: Documentation messages: 167137 nosy: docs@python, storchaka priority: normal severity: normal status: open title: Double parents in functions references versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15527> _______________________________________

6 22

[issue16026] csv.DictReader argument names documented incorrectly
by Peter Eisentraut Jan. 6, 2017

Jan. 6, 2017

New submission from Peter Eisentraut: The documentation for the csv.DictReader constructor is .. class:: DictReader(csvfile, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds) but the implementation is def __init__(self, f, fieldnames=None, restkey=None, restval=None, dialect="excel", *args, **kwds): The name of the first argument is documented incorrectly, leading to surprise errors when attempting to use key word arguments. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 171161 nosy: docs@python, petere priority: normal severity: normal status: open title: csv.DictReader argument names documented incorrectly type: behavior versions: 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/issue16026> _______________________________________

9 15

[issue15013] smtplib: add low-level APIs to doc?
by Sandro Tosi Oct. 13, 2016

Oct. 13, 2016

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: In the smtplib doc I read: Low-level methods corresponding to the standard SMTP/ESMTP commands HELP, RSET, NOOP, MAIL, RCPT, and DATA are also supported. Normally these do not need to be called directly, so they are not documented here. For details, consult the module code. Well, I think the documentation should include also those low-level apis (maybe in a separate subsection). >From my POV, smtplib should implement the protocol, and give the programmers the tools to use the protocol as they prefers, and as a plus some companion methods to easy the most common operations. I'm in need to use the low-level apis, and not finding them in the doc is a disservice to me (with my user hat on ;)) and just say "go read the source" is kinda rude and unexpected. What do you think? ---------- assignee: docs@python components: Documentation messages: 162395 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: needs patch status: open title: smtplib: add low-level APIs to doc? versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15013> _______________________________________

4 4

[issue10415] readline.insert_text documentation incomplete
by Justin Lebar Sept. 30, 2016

Sept. 30, 2016

New submission from Justin Lebar <justin.lebar(a)gmail.com>: The readline documentation currently says: > readline.insert_text(string) > Insert text into the command line. But as far as I can tell, readline.insert_text() does something only when called from startup_hook or pre_input_hook. Here's an example of someone using the module in a way that works: http://swapoff.org/svn/cly/tags/0.7/cly/interactive.py ---------- assignee: docs@python components: Documentation messages: 121178 nosy: Justin.Lebar, docs@python priority: normal severity: normal status: open title: readline.insert_text documentation incomplete versions: Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10415> _______________________________________

6 7

[issue15941] Time module: effect of time.timezone change
by Terry J. Reedy Sept. 15, 2016

Sept. 15, 2016

New submission from Terry J. Reedy: "time.timezone The offset of the local (non-DST) timezone, in seconds west of UTC (negative in most of Western Europe, positive in the US, zero in the UK)." Quite aside from #9305 (UTC is not a place), this does not specify the effect of setting this attribute. It does not change the output of localtime, asctime, or ctime (on Windows). Does is affect anything else? strftime? If setting it has no effect, the doc should say so. (And then perhaps it should be made read-only in the future, as setting it expecting an effect would be a bug.) ---------- assignee: docs@python components: Documentation messages: 170450 nosy: belopolsky, docs@python, haypo, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Time module: effect of time.timezone change versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15941> _______________________________________

2 5

[issue12946] PyModule_GetDict() claims it can never fail, but it can
by Stefan Behnel Aug. 19, 2016

Aug. 19, 2016

New submission from Stefan Behnel <scoder(a)users.sourceforge.net>: As is obvious from the code, PyModule_GetDict() can fail if being passed a non-module object, and when the (unlikely) dict creation at the end fails. The documentation of the C-API function should be fixed to reflect that, i.e. it should state that NULL is returned in the case of an error. PyObject * PyModule_GetDict(PyObject *m) { PyObject *d; if (!PyModule_Check(m)) { PyErr_BadInternalCall(); return NULL; } d = ((PyModuleObject *)m) -> md_dict; if (d == NULL) ((PyModuleObject *)m) -> md_dict = d = PyDict_New(); return d; } ---------- assignee: docs@python components: Documentation messages: 143764 nosy: docs@python, scoder priority: normal severity: normal status: open title: PyModule_GetDict() claims it can never fail, but it can type: behavior versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12946> _______________________________________

7 11

[issue15639] csv.Error description is incorrectly broad
by Xavier Morel Aug. 5, 2016

Aug. 5, 2016

New submission from Xavier Morel: In both Python 2.7 and Python 3.x, csv.Error is documented as: Raised by any of the functions when an error is detected. As far as I can tell from using the module and looking at the code, this is completely incorrect. There is actually a single instance of csv.Error being used: the instantiation of csv.Dialect (which converts TypeError raised from _csv._Dialect() into csv.Error, a comment notes that this is "for compatibility with py 2.3"). And the only way to hit that code paths seems to be subclassing `Dialect` and putting incorrect values in the various attributes (providing them to `csv.reader` raises a TypeError). I believe the documentation to csv.Error should be changed to: 1. Mark it as effectively deprecated 2. Indicate that the only situation in which it it may be raised is when initializing a subclass of csv.Dialect ---------- assignee: docs@python components: Documentation messages: 168096 nosy: docs@python, xmorel priority: normal severity: normal status: open title: csv.Error description is incorrectly broad versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15639> _______________________________________

2 2

[issue14594] document imp.load_dynamic()
by Stefan Behnel Aug. 5, 2016

Aug. 5, 2016

New submission from Stefan Behnel <scoder(a)users.sourceforge.net>: The imp.load_dynamic() function is used by third party code (e.g. Cython's pyximport) but is not currently documented. http://docs.python.org/dev/library/imp.html The latest changes to the import mechanism suggest that it should better be documented to give a hint that users can rely on it. ---------- assignee: docs@python components: Documentation messages: 158412 nosy: docs@python, scoder priority: normal severity: normal status: open title: document imp.load_dynamic() type: behavior versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14594> _______________________________________

6 6

[issue13402] Document absoluteness of sys.executable
by Éric Araujo July 11, 2016

July 11, 2016

New submission from Éric Araujo <merwok(a)netwok.org>: I wanted to know if sys.executable was always an absolute path but the doc does not talk about that. (My use case is that I’d like to reload a process and I wonder if I can call os.execve or if I need to use os.execvpe.) ---------- assignee: docs@python components: Documentation messages: 147609 nosy: docs@python, eric.araujo priority: normal severity: normal status: open title: Document absoluteness of sys.executable versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13402> _______________________________________

11 21

[issue15476] Add "code object" to glossary
by Chris Jerdonek June 9, 2016

June 9, 2016

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: This issue is to add "code object" to the documentation glossary, as discussed in issue 15457 regarding the documentation around generators. This can be a minimal entry that links to the details here, for example-- http://docs.python.org/reference/datamodel.html#the-standard-type-hierarchy specifically: http://docs.python.org/dev/reference/datamodel.html#index-52 ---------- assignee: docs@python components: Documentation keywords: easy messages: 166633 nosy: cjerdonek, docs@python, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Add "code object" to glossary type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15476> _______________________________________

8 19

[issue13784] Documentation of xml.sax.xmlreader: Locator.getLineNumber() and Locator.getColumnNumber()
by patrick vrijlandt June 2, 2016

June 2, 2016

New submission from patrick vrijlandt <patrick.vrijlandt(a)gmail.com>: Problem: Locator methods return the location where the event starts, not where it ends. Locator line numbers start at 1, Locator column numbers can be 0. Proposal: Adapt documentation. >From the docs: Instances of Locator provide these methods: Locator.getColumnNumber() Return the column number where the current event ends. Locator.getLineNumber() Return the line number where the current event ends My Test: import xml.sax data = b"""<main> <sub attr="1" id="name" > <subsub /> </sub> </main>""" class MyHandler(xml.sax.handler.ContentHandler): def startElement(self, name, attrs): if name == "sub": print("open", name, self._locator.getLineNumber(), self._locator.getColumnNumber()) def endElement(self, name): if name == "sub": print("close", name, self._locator.getLineNumber(), self._locator.getColumnNumber()) xml.sax.parseString(data, MyHandler()) Output: open sub 2 4 close sub 7 4 ---------- assignee: docs@python components: Documentation, XML messages: 151247 nosy: docs@python, patrick.vrijlandt priority: normal severity: normal status: open title: Documentation of xml.sax.xmlreader: Locator.getLineNumber() and Locator.getColumnNumber() type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13784> _______________________________________

5 4

[issue12243] getpass.getuser works on OSX
by Bryce Verdier June 1, 2016

June 1, 2016

New submission from Bryce Verdier <bryceverdier(a)gmail.com>: In the docs for getpass: http://docs.python.org/release/2.6.6/library/getpass.html (as an example). It hints that getuser() doesn't work on OSX. I tried this out and it works fine for python 2.6 on 10.6. I have included a patch for this. I believe the cleanest way to handle this is to remove the "Availability" entry as it's no longer necessary. ---------- assignee: docs@python components: Documentation files: getuser.patch keywords: patch messages: 137483 nosy: docs@python, louiscipher priority: normal severity: normal status: open title: getpass.getuser works on OSX versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 Added file: http://bugs.python.org/file22222/getuser.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12243> _______________________________________

7 12

[issue9911] doc copyedits
by DSM May 25, 2016

May 25, 2016

New submission from DSM <dsm001(a)users.sourceforge.net>: Various typo fixes for the docs. As usual, I left historical documents alone (except for 3.1 whatsnew: fixed the spelling of Jack Diederich's name). Fixing ~30 means I probably introduced ~3 problems of my own, but that should still be a net win.. Patch against py3k r84944. ---------- assignee: docs@python components: Documentation files: typos.patch keywords: patch messages: 117052 nosy: docs@python, dsm001 priority: normal severity: normal status: open title: doc copyedits versions: Python 3.3 Added file: http://bugs.python.org/file18947/typos.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9911> _______________________________________

3 2

[issue16509] sqlite3 docs do not explain check_same_thread
by Daniel Micay May 25, 2016

May 25, 2016

New submission from Daniel Micay: The sqlite3 documentation now includes a Multithreading section explaining issues with older sqlite versions, but still doesn't directly cover disabling check_same_thread beyond listing it as a possible parameter. As far as I can tell, reusing sqlite connections in different threads (such as from a pool) is safe, as long as no attempt is made to use them from multiple threads with no locking. ---------- assignee: docs@python components: Documentation messages: 175946 nosy: docs@python, strcat priority: normal severity: normal status: open title: sqlite3 docs do not explain check_same_thread type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16509> _______________________________________

6 7

[issue11643] Use |version| instead of X.Y in the doc
by Éric Araujo May 7, 2016

May 7, 2016

New submission from Éric Araujo <merwok(a)netwok.org>: Some files like site.rst use “X.Y” to refer to the Python version, but Sphinx helpfully provides a |version| construct that can be replaced by the current version at build time. ---------- assignee: docs@python components: Documentation keywords: easy messages: 131816 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: Use |version| instead of X.Y in the doc versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11643> _______________________________________

8 15

[issue9014] Incorrect documentation of the PyObject_HEAD macro
by Renato Cunha April 19, 2016

April 19, 2016

New submission from Renato Cunha <renato(a)renatocunha.com>: PyObject_HEAD's documentation in py3k (http://docs.python.org/dev/py3k/c-api/structures.html#PyObject_HEAD) uses the same content used in the python 2.x's docs which is wrong, as there were some API changes. PyObject_HEAD is actually defined as #define PyObject_HEAD PyObject ob_base; with PyObject defined as typedef struct _object { _PyObject_HEAD_EXTRA Py_ssize_t ob_refcnt; struct _typeobject *ob_type; } PyObject; (The PyTRACE_REFS discussion is still valid, though.) Additionally, it'd be nice to mention that the Py_REFCNT(ob) and Py_TYPE(ob) macros should be used to access the PyObject members. ---------- assignee: docs@python components: Documentation messages: 107953 nosy: docs@python, trovao priority: normal severity: normal status: open title: Incorrect documentation of the PyObject_HEAD macro type: behavior versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9014> _______________________________________

7 9

[issue15984] Wrong documentation for PyUnicode_FromObject()
by Serhiy Storchaka April 14, 2016

April 14, 2016

New submission from Serhiy Storchaka: In the documentation it is written that PyUnicode_FromObject() is a shortcut for PyUnicode_FromEncodedObject(). But PyUnicode_FromObject() is not call PyUnicode_FromEncodedObject() direct nor indirect. PyUnicode_FromObject() works only with unicode and unicode subclass objects, PyUnicode_FromEncodedObject() is not works with unicode objects. ---------- assignee: docs@python components: Documentation messages: 170821 nosy: docs@python, storchaka priority: normal severity: normal status: open title: Wrong documentation for PyUnicode_FromObject() versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15984> _______________________________________

11 26

[issue14456] Relation between threads and signals unclear
by Sven Marnach April 10, 2016

April 10, 2016

New submission from Sven Marnach <sven(a)marnach.net>: The documentation of the 'signal' module states on the one hand [T]he main thread will be the only one to receive signals (this is enforced by the Python signal module, even if the underlying thread implementation supports sending signals to individual threads). On the other hand, it provides the function 'pthread_kill()': Send the signal signum to the thread thread_id, another thread in the same process as the caller. The signal is asynchronously directed to thread. These two passages are in contradiction to each other. The documentation also states that only the main thread can set signal handlers -- if this is true, it is utterly unclear how sending signals to other threads is useful. Probably the documentation wasn't fully updated when the above function was introduced. ---------- assignee: docs@python components: Documentation messages: 157156 nosy: docs@python, smarnach priority: normal severity: normal status: open title: Relation between threads and signals unclear versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14456> _______________________________________

4 6

[issue10289] Document magic methods called by built-in functions
by Éric Araujo April 9, 2016

April 9, 2016

New submission from Éric Araujo <merwok(a)netwok.org>: At the top of Doc/library/functions.rst, which documents built-in functions like abs, getattr or hash, a comment reads “document all delegations to __special__ methods”. Some functions are already good: enumerate for instance does link to the definition of iterator and hints about the __next__ method, format points to __format__, etc. They can serve as example for how to add links (in plain text and in the global index). ---------- assignee: docs@python components: Documentation messages: 120189 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: Document magic methods called by built-in functions versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10289> _______________________________________

10 14

[issue15117] Please document top-level sqlite3 module variables
by wchlm March 27, 2016

March 27, 2016

New submission from wchlm <shenkin(a)gmail.com>: sqlite3 top-level variables, such as version, sqlite_version, version_info, and sqlite_version_info are all useful for Python users of the module -- even essential at times. Yet there is no mention of them in the Py 2.7.3 documentation. dir(sqlite3) reveals a longer list. It would be good if someone with a deeper knowledge of the module could assemble a list of useful items and add them to the sqlite3 documentation. ---------- assignee: docs@python components: Documentation messages: 163285 nosy: docs@python, shenkin priority: normal severity: normal status: open title: Please document top-level sqlite3 module variables versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15117> _______________________________________

4 3

[issue13354] tcpserver should document non-threaded long-living connections
by Bas Wijnen Feb. 20, 2016

Feb. 20, 2016

New submission from Bas Wijnen <wijnen(a)debian.org>: http://docs.python.org/py3k/library/socketserver.html says: The solution is to create a separate process or thread to handle each request; the ForkingMixIn and ThreadingMixIn mix-in classes can be used to support asynchronous behaviour. There is another way, which doesn't bring multi-threading hell over you: keep a copy of the file descriptor and use it when events occur. I recall that this suggestion used to be in the documentation as well, but I can't find it anymore. It would be good to add this suggestion to the documentation. However, there is a thing you must know before you can use this approach: tcpserver calls shutdown() on the socket when handle() returns. This means that the network connection is closed. Even dup2() doesn't keep it open (it lets you keep a file descriptor, but it returns EOF). The solution for this is to override shutdown_request of your handler to only call close_request (or not call anything at all) for sockets which must remain open. That way, as long as there is a reference to the socket, the network connection will not be shut down. Optionally the socket can be shutdown() explicitly when you're done with the connection. Something like the paragraph above would be useful in the documentation IMO. ---------- assignee: docs@python components: Documentation messages: 147147 nosy: docs@python, shevek priority: normal severity: normal status: open title: tcpserver should document non-threaded long-living connections type: feature request versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13354> _______________________________________

3 7

[issue15608] Improve socketserver doc
by Terry J. Reedy Feb. 18, 2016

Feb. 18, 2016

New submission from Terry J. Reedy: On Windows, 3.3 socketserver defines 12 classes in 3 categories: servers, server mixins, and handlers. (At least, these are the one listed with dir(socketserver). Only BaseServer is indexed. I think all should be. There are also a couple of text issues. BaseServer - indexed, doc is 20.19.2. Server Objects TCPServer - mentioned in diagram and text of 20.19.1 UDPServer - ditto (I presume *nix version have unixxxx classes also) ForkingMixIn - text of 20.19.1 ThreadingMixIn - ditto ForkingTCPServer ForkingUDPServer ThreadingTCPServer ThreadingUDPServer Text says "Forking and threading versions of each type of server can be created using the ForkingMixIn and ThreadingMixIn mix-in classes. For instance, a threading UDP server class is created as follows: class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass The mix-in class must come first, since it overrides a method defined in UDPServer." "can be" means to me that user must create these. I am guessing that pre-defining them was added later. So text should change to 'have been'. The pre-created combinations should be listed. The last sentence could then say "Thhe mix-in class comes first since it overrides...". --- BaseRequestHandler This is documented in 20.19.2 RequestHandler Objects. But instead of starting with something like class socketserver.BaseRequestHandler This is the superclass of all RequestHandler objects. It defines the interface, given below, but does not implement most of the methods, which is done in subclasses. A new instance of the subclass is created for each request. analogous to the initial entry in 20.19.1, 20.19.2 starts with "The request handler class must define a new handle() method, and can override any of the following methods. A new instance is created for each request. I suggest that this be replaced with a standard class entry like the one above. If done, I resume the "RequestHandler" method prefix should be "BaseRequestHandler". StreamRequestHandler - these two are described in a paragraph DatagramRequestHandler - after the handle method entry --- In summary: 1. index all classes to point to locations indicated above. 2. state that mixin combinations are pre-defined. 3. give BaseRequestHandler a proper entry. 4. revise above as needed for *nix. 5. optionally adjust as needed for 2.7. ---------- assignee: docs@python components: Documentation messages: 167825 nosy: docs@python, terry.reedy priority: normal severity: normal status: open title: Improve socketserver doc versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15608> _______________________________________

4 8

[issue8810] TZ offset description is unclear in docs
by Alexander Belopolsky Feb. 7, 2016

Feb. 7, 2016

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: >From <http://docs.python.org/dev/py3k/library/datetime.html#datetime.tzinfo.utcof…>: """ tzinfo.utcoffset(self, dt) Return offset of local time from UTC, in minutes east of UTC. """ This suggests that the return value is an integer representing the number of minutes. It is later explained that in fact "the value returned must be a timedelta object specifying a whole number of minutes", but many users won't read past the first sentence. I suggest s/in minutes east of UTC/as a timedelta object/. I think "east of UTC" is redundant given the next sentence, "If local time is west of UTC, this should be negative", but that can also be reworded for clarity as "The offset for timezones west of UTC is negative, and for those east of UTC is positive." ---------- assignee: docs@python components: Documentation keywords: easy messages: 106371 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: TZ offset description is unclear in docs versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8810> _______________________________________

6 19

[issue16731] xxlimited/xxmodule docstrings ambiguous
by Daniel Shahaf Jan. 28, 2016

Jan. 28, 2016

New submission from Daniel Shahaf: Tweak the docstrings of xxmodule and xxlimited to clarify the difference between them (as derived from setup.py). While at it also add a defensive coding guard to xxlimited to ensure it remains Py_LIMITED_API-safe. ---------- assignee: docs@python components: Documentation, Extension Modules files: xxdocstrings.diff keywords: patch messages: 177774 nosy: danielsh, docs@python priority: normal severity: normal status: open title: xxlimited/xxmodule docstrings ambiguous versions: Python 3.4 Added file: http://bugs.python.org/file28367/xxdocstrings.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16731> _______________________________________

5 7

[issue16544] Add external link to ast docs
by Andrew Svetlov Jan. 6, 2016

Jan. 6, 2016

New submission from Andrew Svetlov: http://greentreesnakes.readthedocs.org/en/latest/index.html is excellent and comprehensive documentation for ast tree structures. It would be nice to incorporate that docs into stdlib documentation, but adding *see also* section is good enoigh as first step. ---------- assignee: docs@python components: Documentation keywords: easy messages: 176239 nosy: asvetlov, docs@python priority: normal severity: normal stage: needs patch status: open title: Add external link to ast docs versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________

7 11

[issue12484] The Py_InitModule functions no longer exist, but remain in the docs
by Alejandro Santos Dec. 27, 2015

Dec. 27, 2015

New submission from Alejandro Santos <alejolp(a)alejolp.com>: While the "Py_InitModule" does not exists on Py3k it is still mentioned on the docs: http://docs.python.org/py3k/extending/extending.html#keyword-parameters-for… http://docs.python.org/py3k/extending/windows.html#a-cookbook-approach http://docs.python.org/py3k/faq/extending.html#what-does-systemerror-pyimpo… ---------- assignee: docs@python components: Documentation messages: 139728 nosy: alejolp, docs@python priority: normal severity: normal status: open title: The Py_InitModule functions no longer exist, but remain in the docs versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12484> _______________________________________

8 16

[issue10942] xml.etree.ElementTree.tostring returns type bytes, expected type str
by J_Tom_Moon_79 Nov. 26, 2015

Nov. 26, 2015

New submission from J_Tom_Moon_79 <jtm.moon.forum.user+python(a)gmail.com>: method xml.etree.ElementTree.tostring from module returns type bytes. The documentation reads """Returns an encoded string containing the XML data.""" (from http://docs.python.org/py3k/library/xml.etree.elementtree.html#xml.etree.El… as of 2011-01-18) ======================================================= Here is a test program: ------------------------------------------------------- #!/usr/bin/python # created for python 3.1 import sys print(sys.version) # for help verifying version tested from xml.etree import ElementTree sampleinput = """<?xml version="1.0"?><Hello></Hello>""" xmlobj = ElementTree.fromstring(sampleinput) type(xmlobj) xmlstr = ElementTree.tostring(xmlobj,'utf-8') print("xmlstr value is '", xmlstr, "'", sep="") print("xmlstr type is '", type(xmlstr), "'", sep="") ------------------------------------------------------- test program output: ------------------------------------------------------- 3.1.3 (r313:86834, Nov 27 2010, 18:30:53) [MSC v.1500 32 bit (Intel)] xmlstr value is 'b'<Hello />'' xmlstr type is '<class 'bytes'>' ======================================================= This cheap "fix" for this bug may be simply be a change in documentation. However, a method called "tostring" really should return something nearer to the built-in str. ---------- assignee: docs@python components: Documentation, XML messages: 126506 nosy: JTMoon79, docs@python priority: normal severity: normal status: open title: xml.etree.ElementTree.tostring returns type bytes, expected type str type: behavior versions: Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10942> _______________________________________

4 5

[issue13275] Recommend xml.etree for XML processing
by Alexey Shamrin Nov. 26, 2015

Nov. 26, 2015

New submission from Alexey Shamrin <shamrin(a)gmail.com>: There are many libraries in Python stdlib [1] xml.dom xml.dom.minidom xml.dom.pulldom xml.sax xml.etree Tutorial mentions xml.dom and xml.sax. [2] In my experience xml.etree is the best library to quickly load some xml and mess with it. It would be nice to recommend people xml.etree in the tutorial [2] and in the beginning of section 19, "Structured Markup Processing Tools". [1] [1]: http://docs.python.org/library/markup.html [2]: http://docs.python.org/tutorial/stdlib.html#batteries-included ---------- assignee: docs@python components: Documentation messages: 146484 nosy: ash, docs@python priority: normal severity: normal status: open title: Recommend xml.etree for XML processing _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13275> _______________________________________

8 11

[issue12300] Document pydoc.help
by Éric Araujo Nov. 3, 2015

Nov. 3, 2015

New submission from Éric Araujo <merwok(a)netwok.org>: The only public function in pydoc is help, and it’s not listed in the module docs. The existing doc in library/functions could be moved to library/pydoc. See also #12299. ---------- assignee: docs@python components: Documentation messages: 138002 nosy: docs@python, eric.araujo priority: normal severity: normal status: open title: Document pydoc.help versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12300> _______________________________________

3 4

[issue16785] Document the fact that constructing OSError with erron returns subclass if possible
by Andrew Svetlov Oct. 26, 2015

Oct. 26, 2015

New submission from Andrew Svetlov: I mean adding examples for constructions like this: >>> OSError(errno.ENOENT, 'error msg') FileNotFoundError(2, 'error msg') ---------- assignee: docs@python components: Documentation keywords: easy messages: 178204 nosy: asvetlov, docs@python priority: normal severity: normal status: open title: Document the fact that constructing OSError with erron returns subclass if possible versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16785> _______________________________________

3 3

[issue13195] subprocess: args with shell=True is not documented on Windows
by anatoly techtonik Oct. 18, 2015

Oct. 18, 2015

New submission from anatoly techtonik <techtonik(a)gmail.com>: For UNIX, it is said that if shell=False then you need to pass `args` as a list (if you want to pass any parameters to executable). Is that true for Windows (and perhaps other platforms) as well? Again, for UNIX it is said that with shell=True, and args is a list - every item except the first one is an argument to the shell itself. Is it the same on Windows? It would be better to just give advice in `shell` parameter description to "pass args as a list with shell=False or else you'll lose params in Unix. If shell=True you need to pass args as a string, because list is needed only if you need to pass arguments to shell itself." ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 145662 nosy: docs@python, techtonik priority: normal severity: normal status: open title: subprocess: args with shell=True is not documented on Windows _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13195> _______________________________________

5 9

[issue8952] Doc/c-api/arg.rst: fix documentation of number formats
by STINNER Victor Oct. 14, 2015

Oct. 14, 2015

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: The documentation of PyArg_Parse*() number formats specify that only int / float / complex are accepted, whereas any int / float / complex compatible object is accepted. "compatible" means that it has an __int__() / __float__() / __complex__() method, or nb_int / nb_float of Py_TYPE(obj)->tp_as_number->nb_int is defined (tp_as_number has no nb_complex). I suppose that the following paragraph is also outdated: "It is possible to pass "long" integers (integers whose value exceeds the platform's :const:`LONG_MAX`) however no proper range checking is done --- the most significant bits are silently truncated when the receiving field is too small to receive the value (actually, the semantics are inherited from downcasts in C --- your mileage may vary)." Moreover, "without overflow checking" should be explained (Mark told me that the number is truncated to a power of 2). ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 107379 nosy: docs@python, haypo, mark.dickinson priority: normal severity: normal status: open title: Doc/c-api/arg.rst: fix documentation of number formats versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8952> _______________________________________

3 6

[issue16701] Docs missing the behavior of += (in-place add) for lists.
by Ashwini Chaudhary Oct. 3, 2015

Oct. 3, 2015

New submission from Ashwini Chaudhary: I think the python docs are missing the behavior of += for lists. It actually calls list.extend() but can't find that anywhere in docs expect in source code, http://hg.python.org/cpython/file/2d2d4807a3ed/Objects/listobject.c#l892. ---------- assignee: docs@python components: Documentation messages: 177627 nosy: docs@python, montysinngh priority: normal severity: normal status: open title: Docs missing the behavior of += (in-place add) for lists. type: enhancement versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16701> _______________________________________

8 24

[issue16554] The description of the argument of MAKE_FUNCTION and MAKE_CLOSURE is incorrect
by Daniel Urban Aug. 13, 2015

Aug. 13, 2015

New submission from Daniel Urban: The description of the argument of the MAKE_FUNCTION and MAKE_CLOSURE opcodes in the documentation of the dis module is incorrect. Patch attached. ---------- assignee: docs@python components: Documentation files: make_function_closure.patch keywords: needs review, patch messages: 176390 nosy: daniel.urban, docs@python priority: normal severity: normal stage: patch review status: open title: The description of the argument of MAKE_FUNCTION and MAKE_CLOSURE is incorrect versions: Python 3.3, Python 3.4 Added file: http://bugs.python.org/file28125/make_function_closure.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16554> _______________________________________

4 4

[issue16508] include the "object" type in the lists of documented types
by Chris Jerdonek July 30, 2015

July 30, 2015

New submission from Chris Jerdonek: This issue is to add the "object" type to the list of types documented in the language reference's standard type hierarchy and the library reference's list of built-in types: http://docs.python.org/dev/reference/datamodel.html#the-standard-type-hiera… http://docs.python.org/dev/library/stdtypes.html#other-built-in-types The constructor is documented here: http://docs.python.org/dev/library/functions.html#object In the documentation, it might also be worth stating explicitly which of the special methods the object type defines: http://docs.python.org/dev/reference/datamodel.html#special-method-names For example, object.__str__ is defined, but object.__bytes__ is not. By doing this, users will know which special methods user-defined classes will automatically inherit. ---------- assignee: docs@python components: Documentation messages: 175938 nosy: chris.jerdonek, docs@python, eric.araujo, ezio.melotti, georg.brandl priority: normal severity: normal status: open title: include the "object" type in the lists of documented types type: enhancement versions: Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16508> _______________________________________

8 10

[issue13124] Add "Running a Build Slave" page to the devguide
by Eric Snow July 21, 2015

July 21, 2015

New submission from Eric Snow <ericsnowcurrently(a)gmail.com>: Here's a patch to add a page to the devguide on running a build slave. I copied pretty liberally from the wiki (http://wiki.python.org/moin/BuildBot). That page may or may not be up to date (I don't know), so the bulk of this new page may also be out of date... The current devguide buildbots page is oriented toward the use of buildbots in the dev process. In contrast, this new page is all about running one. I figured it is yet another easy way that people can contribute to Python. I didn't stick in the windows-specific buildbot info (http://wiki.python.org/moin/BuildbotOnWindows), but did link to the wiki page. I did include the info, as far as I understood it, from a recent python-dev thread (http://mail.python.org/pipermail/python-dev/2011-October/113935.html). I added a link to the devguide index page, but it may need to be shifted to the right spot (maybe right after "Running & Writing Tests"). I also renamed buildbots.rst to continuous_integration.rst (and updated reference accordingly). I want to be sure attribution is appropriate, regarding the text pulled from the wiki page and from the python-dev thread. Is linking to the thread sufficient? This is a rough stab (especially with the inclusion of the still-ongoing python-dev thread); but hopefully this gets a ball rolling and doesn't take much work to polish. :) ---------- assignee: docs@python components: Devguide, Documentation files: buildslaves.diff keywords: patch messages: 145120 nosy: brett.cannon, docs@python, eric.snow priority: normal severity: normal status: open title: Add "Running a Build Slave" page to the devguide type: feature request versions: Python 3.3 Added file: http://bugs.python.org/file23338/buildslaves.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13124> _______________________________________

8 21

[issue12920] Inspect.getsource fails to get source of local classes
by Popa Claudiu June 23, 2015

June 23, 2015

New submission from Popa Claudiu <pcmanticore(a)gmail.com>: inspect.getsource called with a class defined in the same file fails with TypeError: <module '__main__' (built-in)> is a built-in class, although the documentation says that: "The argument may be a module, class, method, function, traceback, frame, or code object. The source code is returned as a single string." I think that should be specified in documentation that this function works only for objects living in a module. ---------- assignee: docs@python components: Documentation messages: 143645 nosy: Popa.Claudiu, docs@python priority: normal severity: normal status: open title: Inspect.getsource fails to get source of local classes type: behavior versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12920> _______________________________________

5 8

[issue13213] generator.throw() behavior
by Petri Lehtinen June 20, 2015

June 20, 2015

New submission from Petri Lehtinen <petri(a)digip.org>: The documentation of generator.throw() gives this signature: generator.throw(type[, value[, traceback]]) Looking at the code, it accepts the following arguments: g.throw(ExcType) --> raise ExcType() g.throw(ExcType, None) --> raise ExcType() g.throw(ExcType, None, tb) --> raise ExcType().with_traceback(tb) g.throw(ExcType, instace_of_ExcType) --> raise instance_of_ExcType g.throw(ExcType, instace_of_ExcType, tb) --> raise instance_of_ExcType.with_traceback(tb) g.throw(ExcType, other_value) --> raise ExcType(other_value) g.throw(ExcType, other_value, tb) --> raise ExcType(other_value).with_traceback(tb) Up to this point, I think everything is in line with the documentation. But it also accepts the following (now that issue 13188 is fixed): g.throw(exc_instance) --> raise exc_instance (preserving the traceback of exc_instance) g.throw(exc_instance, None) --> raise exc_instance (preserving the traceback of exc_instance) g.throw(exc_instance, None, tb) --> raise exc_instance.with_traceback(tb) It does not accept these, throwing a TypeError: g.throw(exc_instance, some_value_other_than_None) g.throw(exc_instance, some_value_other_than_None, tb) g.throw(exc_instance, tb) The documentation is really unclear on throwing existing exception instances with (exc_instance) or (exc_instance, None), and that calling with (type, value) or (type, value, tb) will create a new exception if not isinstance(value, type). ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 145848 nosy: docs@python, ezio.melotti, ncoghlan, petri.lehtinen, pitrou priority: normal severity: normal status: open title: generator.throw() behavior type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13213> _______________________________________

4 3

[issue10170] Relationship between turtle speed setting and actual speed is not documented
by Alexander Belopolsky May 17, 2015

May 17, 2015

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: As Terry J. Reedy mentioned in his comment on issue 7061, turtle documentation is lacking information on how speed "codes" 0-10 translate into actual turtle speed. Attached script measures the speed of the two primitive operations that form the basis of turtle functionality at various speed settings. The results below show highly irregular pattern. The columns are: the speed code, time to draw a 200 unit line, time to complete a 360 degrees turn and the ratio of the two times. 0: 0.01 0.01 0.83 1: 1.04 2.05 0.51 2: 0.49 1.06 0.46 3: 0.30 0.72 0.42 4: 0.23 0.54 0.44 5: 0.17 0.44 0.38 6: 0.13 0.39 0.35 7: 0.08 0.32 0.26 8: 0.08 0.28 0.30 9: 0.10 0.27 0.37 10: 0.08 0.23 0.36 >From the source code, it appears that the on-screen speed is controlled by the number of animation steps while each step takes approximately time controlled by the "delay" setting that defaults to 10 milliseconds. The number of steps is determined by somewhat peculiar computations. For a rotation by angle of a degrees at speed setting s, the number of steps is n = 2 + int(a / (3 * s)) and for drawing a line of length d, n = 1 + int(d / (3 * 1.1**s * s)) I am not sure what was the reason for these choices, but I think it would be better if numeric speed code had a more direct relationship to the apparent speed. ---------- assignee: docs@python components: Demos and Tools, Documentation messages: 119334 nosy: belopolsky, docs@python, eric.araujo, georg.brandl, gregorlingl, terry.reedy priority: normal severity: normal status: open title: Relationship between turtle speed setting and actual speed is not documented versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10170> _______________________________________

3 3

[issue15329] clarify which deque methods are thread-safe
by Chris Jerdonek April 25, 2015

April 25, 2015

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: I think it would help to clarify which collections.deque methods are thread-safe: http://docs.python.org/dev/library/collections.html?highlight=deque#collect… Currently, the documentation says that "Deques support thread-safe, memory efficient appends and pops from either side...," but it isn't obvious if this is meant to apply to all methods, or just the methods named append*() and pop*(). For example, is rotate() thread-safe? The illustration given of d.appendleft(d.pop()) seems like it could be interleaved. ---------- assignee: docs@python components: Documentation keywords: easy messages: 165275 nosy: cjerdonek, docs@python, rhettinger priority: normal severity: normal status: open title: clarify which deque methods are thread-safe versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15329> _______________________________________

6 10

[issue16574] clarify policy on updates to final peps
by Chris Jerdonek April 21, 2015

April 21, 2015

New submission from Chris Jerdonek: This issue is to clarify the policy in PEP 1 regarding non-substantive changes to PEPs in the Final state (minor clarifications, rephrasings, etc). Currently, PEP 1 says, "In general, Standards track PEPs are no longer modified after they have reached the Final state." (from http://www.python.org/dev/peps/pep-0001/#pep-maintenance ) However, others have pointed out that minor clarifications and rephrasings are in fact allowed: http://bugs.python.org/issue15990#msg176575 The updated wording should also state the policy or process regarding such changes (who is allowed to make them and whether and from whom approval is needed to make such changes, etc). ---------- assignee: docs@python components: Documentation messages: 176598 nosy: barry, chris.jerdonek, docs@python, eric.araujo, ezio.melotti, goodger, ncoghlan priority: normal severity: normal status: open title: clarify policy on updates to final peps type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________

11 21

[issue15183] it should be made clear that the statement in the --setup option and the setup kw arg aren't included in the count
by Tshepang Lekhonkhobe April 21, 2015

April 21, 2015

New submission from Tshepang Lekhonkhobe <tshepang(a)gmail.com>: I looked at 'python -m time -h' and the timeit doc, and it was not clear to me (after a quick read) that the statement(s) inside --setup option and setup keyword argument weren't included in the speed test. I had to check for myself by writing code. ---------- assignee: docs@python components: Documentation messages: 163999 nosy: docs@python, tshepang priority: normal severity: normal status: open title: it should be made clear that the statement in the --setup option and the setup kw arg aren't included in the count versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15183> _______________________________________

4 4

[issue13386] Document documentation conventions for optional args
by Ezio Melotti April 19, 2015

April 19, 2015

New submission from Ezio Melotti <ezio.melotti(a)gmail.com>: AFAIU the conventions for optional argument in the doc are as follow: If a function has optional arguments and it accepts keyword arguments, the "func(arg=default)" notation should be used, for example: str.splitlines(keepends=False) If a function has optional arguments but it doesn't accept keyword arguments, the "func([arg1])" notation is used instead. This should apply only to some C functions, for example: str.strip([chars]) The notation "func([arg=default])" should never be used, and "func([arg])" should be used only when keyword args are not accepted. These rules apply to both Python 2 and Python 3. A thing that is still not clear is what to do in case the default value is a placeholder (like object(), None, -1) and the actual value is then computed in the function. ---------- assignee: docs@python components: Documentation messages: 147469 nosy: docs@python, eli.bendersky, eric.araujo, ezio.melotti, georg.brandl priority: normal severity: normal stage: needs patch status: open title: Document documentation conventions for optional args versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13386> _______________________________________

10 29

[issue15566] tarfile.TarInfo.frombuf documentation is out of date
by Sebastian Ramacher April 18, 2015

April 18, 2015

New submission from Sebastian Ramacher: tarfile.TarInfo.frombuf has gained two more parameters: encoding and errors. The documentation of frombuf claims that the only parameter is buf, which is not true anymore. ---------- assignee: docs@python components: Documentation messages: 167553 nosy: docs@python, sebastinas priority: normal severity: normal status: open title: tarfile.TarInfo.frombuf documentation is out of date versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15566> _______________________________________

6 5

[issue12652] Move documentation of test.support into the devguide
by Eli Bendersky April 14, 2015

April 14, 2015

New submission from Eli Bendersky <eliben(a)gmail.com>: First step in transition: Attaching a patch to devguide's runtests.rst to incorporate existing test.support documentation from 3.3 head, with some small markup changes suitable for the devguide. ---------- components: Devguide files: devguide_test_support.1.patch keywords: patch messages: 141337 nosy: brett.cannon, docs@python, eli.bendersky, ncoghlan priority: low severity: normal stage: patch review status: open title: Move documentation of test.support into the devguide type: behavior Added file: http://bugs.python.org/file22790/devguide_test_support.1.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12652> _______________________________________

10 12

[issue12955] urllib2.build_opener().open() is not friendly to "with ... as:"
by Valery Khamenya April 12, 2015

April 12, 2015

New submission from Valery Khamenya <khamenya(a)gmail.com>: The following intuitive construction with urllib2.build_opener().open() as: ... leads to AttributeError: addinfourl instance has no attribute '__exit__' http://docs.python.org/library/urllib2.html says almost nothing about concept of closing. Could it be possible to add a canonical "with ... as:" example for urllib2.build_opener() ? Thanks, Valery ---------- assignee: docs@python components: Documentation, IO, Library (Lib) messages: 143836 nosy: Valery.Khamenya, docs@python priority: normal severity: normal status: open title: urllib2.build_opener().open() is not friendly to "with ... as:" type: resource usage versions: 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/issue12955> _______________________________________

9 17

[issue11468] Improve unittest basic example in the doc
by Ezio Melotti March 24, 2015

March 24, 2015

New submission from Ezio Melotti <ezio.melotti(a)gmail.com>: The current example[0] uses assertTrue(element in self.seq) but it would be better to use assertIn instead. The whole example could be changed to something simpler that uses only the assertTrue/assertEqual/assertRaises methods correctly, e.g.: import unittest class TestStringMethods(unittest.TestCase): def test_upper(self): self.assertEqual('foo'.upper(), 'FOO') def test_isupper(self): self.assertTrue('FOO'.isupper()) self.assertFalse('Foo'.isupper()) def test_split(self): s = 'hello world' self.assertEqual(s.split(), ['hello', 'world']) # check that s.split fails when the separator is not a string with self.assertRaises(TypeError): s.split(2) if __name__ == '__main__': unittest.main() [0]: http://docs.python.org/py3k/library/unittest.html#basic-example ---------- assignee: docs@python components: Documentation keywords: easy messages: 130598 nosy: docs@python, eric.araujo, ezio.melotti, michael.foord, ncoghlan, rhettinger priority: low severity: normal stage: needs patch status: open title: Improve unittest basic example in the doc type: feature request versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________

9 19

[issue12155] queue example doesn't stop worker threads
by STINNER Victor March 18, 2015

March 18, 2015

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: The queue doc contains the following example: ------------------ def worker(): while True: item = q.get() do_work(item) q.task_done() q = Queue() for i in range(num_worker_threads): t = Thread(target=worker) t.daemon = True t.start() for item in source(): q.put(item) q.join() # block until all tasks are done ------------------ http://docs.python.org/library/queue.html It doesn't define do_work(), num_worker_threads or do_work(), but my concern is that it doesn't stop worker threads. I consider "t.daemon = True" as an hack to not care about stopping threads. The example should pass a special value to each worker to stop it. For example: <worker> while True: job = queue.get() if job is None: break audio.play(*job) queue.task_done() Main thread: ... threads = [] for i in range(num_worker_threads): t = Thread(target=worker) threads.append(t) t.start() ... for i in range(num_worker_threads): queue.put(None) queue.join() for thread in threads: thread.join() ---------- assignee: docs@python components: Documentation messages: 136601 nosy: docs@python, haypo, pitrou priority: normal severity: normal status: open title: queue example doesn't stop worker threads versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12155> _______________________________________

5 7

[issue9119] Python download page needs to mention crypto code in Windows installer
by Marc-Andre Lemburg Feb. 20, 2015

Feb. 20, 2015

New submission from Marc-Andre Lemburg <mal(a)egenix.com>: This needs to be done to protect our users (importing crypto code or using it may be illegal in their home country, see http://rechten.uvt.nl/koops/cryptolaw/ for a survey) and to satisfy an attribution requirement in the OpenSSL license and code base: """ This product includes cryptographic software written by Eric Young (eay(a)cryptsoft.com). This product includes software written by Tim Hudson (tjh(a)cryptsoft.com). This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/) """ ---------- assignee: docs@python components: Build, Documentation messages: 108929 nosy: docs@python, lemburg priority: normal severity: normal status: open title: Python download page needs to mention crypto code in Windows installer versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9119> _______________________________________

10 23

[issue9913] Misc/SpecialBuilds.txt is out of date
by Alexander Belopolsky Feb. 18, 2015

Feb. 18, 2015

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: It looks like Misc/SpecialBuilds.txt has not been updated since 2.4. This file is referenced from C-API documentation [1], but is not accessible as a hyperlink. Some of the recommendations in this file are out of date, in particular those that recommend setting make variables where a configure switch is available. I believe it would be best to retire Misc/SpecialBuilds.txt and move still relevant sections to proper .rst files. [1] http://docs.python.org/dev/py3k/c-api/intro.html#debugging-builds ---------- assignee: docs@python components: Documentation messages: 117076 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: Misc/SpecialBuilds.txt is out of date versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9913> _______________________________________

3 3

[issue14512] Pydocs module docs server not working on Windows.
by Terry J. Reedy Feb. 15, 2015

Feb. 15, 2015

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: 3.2.3rc2 and 3.3.0a2, freshly downloaded and installed, Win7, 64 bit Start Menue/Pythonxx/Module Docs Brings up tkinter pydoc box. [open browser] brings up *empty* localhost:7464 window. Search 'tkinter' and double-click tkinter entry or select and [go to selected] opens empty localhost:7464/tkinter.html window. This worked sometime last year on earlier 3.2, maybe on xp box. I thought there might be an issue already, but I searched for 'pydoc' and 'modole docs' and found nothing. ---------- assignee: docs@python components: Documentation, Installation, Library (Lib) messages: 157606 nosy: docs@python, georg.brandl, loewis, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Pydocs module docs server not working on Windows. type: behavior versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14512> _______________________________________

6 10

[issue12954] Multiprocessing logging under Windows
by paul j3 Feb. 10, 2015

Feb. 10, 2015

New submission from paul j3 <ajipanca(a)gmail.com>: The Windows programming guidelines for the multiprocessing module documentation should include a warning that any logging initialization should be protected by the 'if __name__' block. Otherwise you will get duplicate logging entries for the child processes. This is because the multiprocessing.forking.prepare() function explicitly calls log_to_stderr(), and may implicitly do so again when it imports the parent module, resulting in duplicate logging handlers. ---------- assignee: docs@python components: Documentation messages: 143815 nosy: docs@python, paul.j3 priority: normal severity: normal status: open title: Multiprocessing logging under Windows _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12954> _______________________________________

4 9

[issue9536] defaultdict doc makes incorrect reference to __missing__ method
by John Posner Dec. 12, 2014

Dec. 12, 2014

New submission from John Posner <jjposner(a)optimum.net>: The documentation for collections.defaultdict is confusing with respect to the __missing__ method. The fact is that a programmer using defaultdict does not need to know anything about __missing__. The attached patch contains a rewrite of the entire section (but not the "defaultdict Examples" section, which is fine. ---------- assignee: docs@python components: Documentation files: defaultdict.patch keywords: patch messages: 113105 nosy: docs@python, jjposner priority: normal severity: normal status: open title: defaultdict doc makes incorrect reference to __missing__ method versions: Python 2.7 Added file: http://bugs.python.org/file18417/defaultdict.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9536> _______________________________________

7 11

[issue16518] add "buffer protocol" to glossary
by Chris Jerdonek Oct. 31, 2014

Oct. 31, 2014

New submission from Chris Jerdonek: This issue is to add "buffer protocol" (or perhaps "buffer object") to the glossary. The concept is currently described here: http://docs.python.org/dev/c-api/buffer.html#buffer-protocol Éric initially suggested doing this in the comments to issue 13538. Such a glossary entry would be useful because the buffer protocol (or buffer object) should likely be cited, for example, wherever a function accepts a bytes object, bytearray object, or any object that supports the buffer protocol. The str() constructor is one example where this is done: http://hg.python.org/cpython/file/59acd5cac8b5/Doc/library/functions.rst#l1… "Buffer object" might be the more useful term to add to the glossary because it would help to have a briefer way of saying "any object that supports the buffer protocol." (I'm assuming this is what "buffer object" actually means.) The patch for this issue should also do a comprehensive review of occurrences of buffer object/protocol throughout the docs and add or update links and index entries where appropriate. ---------- assignee: docs@python components: Documentation messages: 176042 nosy: chris.jerdonek, docs@python, eric.araujo, ezio.melotti, pitrou priority: normal severity: normal status: open title: add "buffer protocol" to glossary type: enhancement versions: Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16518> _______________________________________

11 35

[issue13918] locale.atof documentation is missing func argument
by Cédric Krier Oct. 23, 2014

Oct. 23, 2014

New submission from Cédric Krier <cedric.krier(a)b2ck.com>: atof has a func argument used to instantiate the result but it is missing in the documentation. ---------- assignee: docs@python components: Documentation messages: 152430 nosy: ced, docs@python priority: normal severity: normal status: open title: locale.atof documentation is missing func argument type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13918> _______________________________________

8 26

[issue13769] json.dump(ensure_ascii=False) return str instead of unicode
by Марк Коренберг Oct. 23, 2014

Oct. 23, 2014

New submission from Марк Коренберг <socketpair(a)gmail.com>: $ ipython In [1]: type(json.dumps({'a':'b'}, ensure_ascii=False)) Out[1]: <type 'str'> In [2]: type(json.dumps({'a':u'b'}, ensure_ascii=False)) Out[2]: <type 'unicode'> ----------------------- Documentation: If ensure_ascii is False, then the return value will be a unicode instance. -------------------------------- Not applicable to python3 ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 151066 nosy: docs@python, mmarkk priority: normal severity: normal status: open title: json.dump(ensure_ascii=False) return str instead of unicode type: behavior versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13769> _______________________________________

7 13

[issue15204] Deprecate the 'U' open mode
by Serhiy Storchaka Oct. 19, 2014

Oct. 19, 2014

New submission from Serhiy Storchaka <storchaka(a)gmail.com>: Since Python 2.3 many open functions supports "Universal line mode" (PEP 278). Since 3.0 (and 2.6) PEP 3116 suggests better alternative -- io.TextWrapper. Now support for the 'U' mode in the different open functions is heterogeneous. Some functions simply ignore the 'U' mode (but accept it), others perceive it as a synonym for text-mode, others just pass it on lower lever, other attempt to implement it, but the implementation is obtained imperfect and contradictory (as in ZipExtFile). The documentation for built-in open does not advise the use of the 'U' mode. The 'U' mode support cumbersome. I propose to deprecate the 'U' mode. If someone wanted to work with the universal line support, he'll surely need to work with encodings too, and io.TextWrapper provides is better choise. The deprecation plan for the 'U' mode of open functions might be as follow: 3.3. Deprecating the 'U' mode in docs for all opens (building open, io.open, codecs.open, gzip.open, ZipFile.open, etc). Add suggestion about io.TextWrapper. 3.4. Raise a warning on use of the 'U' mode. 3.5. Raise an exception on use of the 'U' mode. 3.6 (or 4.0?). Remove the 'U' mode processing code. As the first stage involves only the changes to the documentation, I hope deprecation can starts in 3.3. ---------- assignee: docs@python components: Documentation, IO, Library (Lib) messages: 164142 nosy: docs@python, storchaka priority: normal severity: normal status: open title: Deprecate the 'U' open mode type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15204> _______________________________________

14 34

[issue12965] longobject: documentation improvements
by Stefan Krah Oct. 14, 2014

Oct. 14, 2014

New submission from Stefan Krah <stefan-usenet(a)bytereef.org>: I think the integer objects documentation could be clearer on a couple of points: - Despite being listed under "Concrete Objects Layer", some functions implicitly accept anything with an __int__() method. Currently only the PyLong_AsLong() documentation states this explicitly. The patch clearly distinguishes between functions that duck type and functions that don't. - The patch replaces "is greater than *_MAX" instances with "out of bounds" to include the other error condition "is less than *_MIN". Additionally, the patch fixes comments in longobject.c that don't state the duck typing behavior. ---------- assignee: docs@python components: Documentation files: longobject-doc.diff keywords: patch messages: 143922 nosy: docs@python, mark.dickinson, skrah priority: normal severity: normal stage: patch review status: open title: longobject: documentation improvements type: feature request versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file23133/longobject-doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12965> _______________________________________

3 11

[issue15414] os.path.join behavior on Windows (ntpath.join) is unexpected and not well documented
by R. David Murray Oct. 10, 2014

Oct. 10, 2014

New submission from R. David Murray <rdmurray(a)bitdance.com>: In looking at another os.path.join documentation issue I tried the Windows join to see if it matched the docs, and found that it was very unclear. I searched the tracker and found Issue 1669539, which contains much relevant discussion but also much discussion of possible enhancements. So I'm opening a new issue *just* about what I see as the current bugs in the os.path.join docs and ntpath.join implementation. I'm not qualified to fix this, not being a Windows user, but it is clear to me that the documentation of os.path.join for Windows is unclear (it does not indicate what is considered an absolute path on Windows) and wrong (\foo will *not* restart the path if it is the second element and follows a drive specification, but it does any other time), and that the current behavior may have a bug if, as seems to be implied by the issue 1669539 discussion, something that looks like a drive specification in the middle of a path is invalid on Windows. If this last is not a bug, it should be mentioned in the documentation, since the actual behavior is counter-intuitive. ---------- assignee: docs@python components: Documentation, Windows keywords: easy messages: 166065 nosy: brian.curtin, christian.heimes, docs@python, eckhardt, ezio.melotti, jorend, mhammond, r.david.murray, terry.reedy, tim.golden priority: normal severity: normal status: open title: os.path.join behavior on Windows (ntpath.join) is unexpected and not well documented type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15414> _______________________________________

8 12

[issue10583] Encoding issue with chm help in 2.7.1
by flashk Oct. 6, 2014

Oct. 6, 2014

New submission from flashk <flashk(a)gmail.com>: I just updated to Python 2.7.1 and noticed a small issue with the chm help file. The search results tab displays incorrect characters for various topic titles. It seems to be an encoding issue. For example, searching for 'json' yields the following results: - 18.2 json â€” JSON encoder and decoder - Whatâ€™s New in Python 2.6 I noticed this issue on Windows XP 32-bit and Windows 7 64-bit. This issue does not exist with the 2.7 chm file. ---------- assignee: docs@python components: Documentation, Windows messages: 122857 nosy: docs@python, flashk priority: normal severity: normal status: open title: Encoding issue with chm help in 2.7.1 type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10583> _______________________________________

7 11

[issue16155] Some minor doc fixes in Doc/faq
by Ravi Sinha Oct. 6, 2014

Oct. 6, 2014

New submission from Ravi Sinha: - help(fn) which in the REPL leads to a new pager/ display - seems to be difficult to test with doctest - it does not seem to pick the whitespace in the docs and does not match - Doc/faq/general.rst - os.path.isdir returns True or False, not 0 or 1 as in the docs, but I didn't know if I should change that - Doc/faq/windows.rst ---------- assignee: docs@python components: Documentation files: doc_faq.patch keywords: patch messages: 172254 nosy: Ravi.Sinha, chris.jerdonek, docs@python, r.david.murray, terry.reedy priority: normal severity: normal status: open title: Some minor doc fixes in Doc/faq type: enhancement versions: Python 3.4 Added file: http://bugs.python.org/file27463/doc_faq.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________

8 12

[issue12148] Clarify "or-ing together" doctest option flags
by ekorn Oct. 6, 2014

Oct. 6, 2014

New submission from ekorn <jonovik(a)gmail.com>: Combining multiple option flags to doctest.testmod(optionflags=...) requires the bitwise or operator |, not plain "or". I therefore suggest rewording "or-ing together individual option flags." to "or-ing together individual option flags, using the 'bitwise or' operator |.", perhaps with a link to http://docs.python.org/reference/expressions.html#binary-bitwise-operations. Example: """ Doctest option flags must be or-ed together with '|', not 'or'. >>> print "A B C" A B... """ import doctest print "Combining option flags using bitwise '|'..." doctest.testmod(optionflags=doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS) print "Combining option flags using logical 'or'..." doctest.testmod(optionflags=doctest.NORMALIZE_WHITESPACE or doctest.ELLIPSIS) ---------- assignee: docs@python components: Documentation messages: 136509 nosy: docs@python, ekorn priority: normal severity: normal status: open title: Clarify "or-ing together" doctest option flags versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12148> _______________________________________

6 8

[issue13101] Module Doc viewer closes when browser window closes on Windows 8
by Brian Curtin Oct. 6, 2014

Oct. 6, 2014

New submission from Brian Curtin <brian(a)python.org>: Reported by Ryan Wells (v-rywel(a)microsoft.com) of Microsoft, in reference to a problem with the Module Doc viewer on Windows 8 when using Internet Explorer 10. This was reported on 3.2.2, but it's likely the same on 2.7. Reference #: 70652 Description of the Problem: The application Python Module Doc is automatically closed when Internet Explorer 10 is closed. Steps to Reproduce: 1. Install Windows Developer Preview 2. Install Python 3.2.2 3. Launch Module Doc. Start Menu -> All Program -> Python -> Manual Docs 4. Click on the button open browser 5. It should open the site http://localhost:7464/ In Internet Explorer 10 and the contents should be displayed 6. Should be able to view list of Modules, Scripts, DLLs, and Libraries etc. 7. Close Internet Explorer Expected Result: Internet Explorer 10 should only get closed and we should be able to work with the application Module Doc. Actual Result: The application Module Doc is closed with Internet Explorer 10. Developer Notes: There is likely a difference in return values between IE8 and IE9/10 when launched from the app. ---------- assignee: docs@python components: Documentation, Windows messages: 144918 nosy: brian.curtin, docs@python priority: normal severity: normal status: open title: Module Doc viewer closes when browser window closes on Windows 8 type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13101> _______________________________________

5 7

[issue14303] Incorrect documentation for socket.py on linux
by Shane Hansen Oct. 6, 2014

Oct. 6, 2014

New submission from Shane Hansen <shanemhansen(a)gmail.com>: The python docs state that for socket.makefile "The file object references a dup()ped version of the socket file descriptor, so the file object and socket object may be closed or garbage-collected independently." In fact for socket.py dup() is never called, and no additional files are opened. Instead an object is returned which uses the original socket and does buffering. For me, this is the desired behaviour, but just thought I'd mention the docs were off. ---------- assignee: docs@python components: Documentation, IO files: test.py messages: 155768 nosy: Shane.Hansen, docs@python, georg.brandl, pitrou priority: normal severity: normal status: open title: Incorrect documentation for socket.py on linux type: behavior versions: Python 2.6, Python 2.7 Added file: http://bugs.python.org/file24843/test.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14303> _______________________________________

4 3

[issue10031] Withdraw anti-recommendation of relative imports from documentation
by Darren Dale Oct. 6, 2014

Oct. 6, 2014

New submission from Darren Dale <dsdale24(a)gmail.com>: Old-style relative imports have been strongly discouraged in some sections of the python documentation. This was discussed on the python-dev mailing list. Executive summary: "The issue is implementing a PEP with nice support for relative imports, and then documenting that it should never be used." To which Guido responded: --- "Isn't this mostly historical? Until the new relative-import syntax was implemented there were various problems with relative imports. The short-term solution was to recommend not using them. The long-term solution was to implement an unambiguous syntax. Now it is time to withdraw the anti-recommendation. Of course, without going overboard -- I still find them an acquired taste; but they have their place." --- It was suggested I open a ticket and suggest specific changes. They are listed below: The faq at http://docs.python.org/py3k/faq/programming.html#what-are-the-best-practice… could go from: "Never use relative package imports. If you’re writing code that’s in the package.sub.m1 module and want to import package.sub.m2, do not just write from . import m2, even though it’s legal. Write from package.sub import m2 instead. See PEP 328 for details." to: "Although the python community generally prefers absolute imports, relative imports may be useful in certain circumstances. See PEP 328 for details." The programming faq for python-2.7 at http://docs.python.org/faq/programming.html#what-are-the-best-practices-for… could go from: "Never use relative package imports. If you’re writing code that’s in the package.sub.m1 module and want to import package.sub.m2, do not just write import m2, even though it’s legal. Write from package.sub import m2 instead. Relative imports can lead to a module being initialized twice, leading to confusing bugs. See PEP 328 for details." to: "Although the python community generally prefers absolute imports, relative imports may be useful in certain circumstances. Support for relative imports has recently been improved, and the use of the old-style relative imports is strongly discouraged. See PEP 328 for details." There is also this warning against relative imports in PEP 8, that could go from: - Relative imports for intra-package imports are highly discouraged. Always use the absolute package path for all imports. Even now that PEP 328 [7] is fully implemented in Python 2.5, its style of explicit relative imports is actively discouraged; absolute imports are more portable and usually more readable. to: - While the python community generally prefers absolute imports, relative imports may be useful in certain circumstances. Now that PEP 328 [7] is fully implemented in Python 2.5 and later, the older style of implicit relative imports is strongly discouraged. ---------- assignee: docs@python components: Documentation messages: 118031 nosy: docs@python, dsdale24 priority: normal severity: normal status: open title: Withdraw anti-recommendation of relative imports from documentation versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10031> _______________________________________

5 5

[issue13211] urllib2.HTTPError does not have 'reason' attribute.
by Jason R. Coombs Oct. 3, 2014

Oct. 3, 2014

New submission from Jason R. Coombs <jaraco(a)jaraco.com>: The urllib2 docs indicate that HTTPError is a subclass of URLError and that URLError has an attribute of 'reason', but HTTPError does not have this attribute. The docs should be updated to reflect this deviance. It appears the Python 3.2 docs no longer include documentation for URLError Python 2.7.2 >>> try:urllib2.urlopen('http://api.wordnik.com/v4/word.json/foo/examples') ... except urllib2.HTTPError as exc: ... print(dir(exc)) ... ['_HTTPError__super_init', '__class__', '__delattr__', '__dict__', '__doc__', '__format__', '__getattribute__', '__getitem__', '__getslice__', '__hash__', '__init__', '__iter__', '__module__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__setstate__', '__sizeof__', '__str__', '__subclasshook__', '__unicode__', '__weakref__', 'args', 'close', 'code', 'errno', 'filename', 'fileno', 'fp', 'getcode', 'geturl', 'hdrs', 'headers', 'info', 'message', 'msg', 'next', 'read', 'readline', 'readlines', 'strerror', 'url'] The same issue exists in Python 3.2.2. Here's what I propose: - For Python 3.2 and 3.3, update HTTPError to supply a @property, aliasing .msg (will .msg always be a suitable .reason?). - For Python 2.7, document the deviance, such as by adding the following wording to the HTTPError docs: "Unlike URLError, HTTPError does not supply a reason attribute. The reason can be retrieved through the msg attribute." ---------- assignee: docs@python components: Documentation messages: 145805 nosy: docs@python, jason.coombs priority: normal severity: normal status: open title: urllib2.HTTPError does not have 'reason' attribute. versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13211> _______________________________________

8 23

[issue16252] bytes and bytearray methods are undocumented
by Antoine Pitrou Sept. 27, 2014

Sept. 27, 2014

New submission from Antoine Pitrou: Everything is in the title. I couldn't find any doc for bytes.join, etc. (while str methods are documented in library/stdtypes.html#string-methods). ---------- assignee: docs@python components: Documentation messages: 173074 nosy: docs@python, pitrou priority: normal severity: normal stage: needs patch status: open title: bytes and bytearray methods are undocumented type: behavior versions: Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16252> _______________________________________

5 6