Mailman 3 August 2012 - docs

[issue12901] Nest class/methods directives in documentation
by Éric Araujo March 15, 2014

March 15, 2014

New submission from Éric Araujo <merwok(a)netwok.org>: I picked up a few files in Doc/library and updated their markup to use directives nesting. The attached patch is the result; it’s a lot of changes for small benefit. If we think it’s a good change anyway, I have two questions - Do you think it would be a good idea to have the -checkins emails ignore whitespace changes in some cases? (I’m thinking a magic string in the commit message) - A number of files have a class directive near the top of the file, in the list of all public names, and a later section “XX objects” with the methods and attributes. When this is changed to nested class/methods directives, sometimes the first class directive gets a noindex flag, but I think it should jsut be removed: the index in the sidebar is enough to let people jump to the doc. Do you agree? ---------- assignee: docs@python components: Documentation messages: 143552 nosy: benjamin.peterson, docs@python, eric.araujo, georg.brandl priority: normal severity: normal status: open title: Nest class/methods directives in documentation versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12901> _______________________________________

3 5

[issue12354] packaging.pypi.simple docs use both client and crawler variable, which might be confusing
by Filip Gruszczyński March 13, 2014

March 13, 2014

New submission from Filip Gruszczyński <gruszczy(a)gmail.com>: In documentation for packaging.pypi.simple in first code snippet crawler variable is created on which further operations will be performed. However in all next snippets there is client variable, which is a little confusing on first sight. This could be consistent throughout the whole page. ---------- assignee: docs@python components: Distutils2, Documentation messages: 138538 nosy: alexis, docs@python, eric.araujo, gruszczy priority: normal severity: normal status: open title: packaging.pypi.simple docs use both client and crawler variable, which might be confusing versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12354> _______________________________________

4 9

[issue15231] update PyPI upload doc to say --no-raw passed to rst2html.py
by Chris Jerdonek March 12, 2014

March 12, 2014

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: I had an issue whereby my reST long_description wasn't getting rendered as HTML when uploaded to PyPI. Following the instructions here did not work as-is: http://docs.python.org/dev/distutils/uploading.html#pypi-package-display It seems that PyPI passes --no-raw (no HTML allowed) to rst2html.py, in which case the guidance would be better updated to read-- $ python setup.py --long-description | rst2html.py --no-raw > output.html ---------- assignee: docs@python components: Documentation keywords: easy messages: 164445 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: update PyPI upload doc to say --no-raw passed to rst2html.py versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15231> _______________________________________

5 39

[issue13530] Docs for os.lseek neglect to mention what it returns
by Ned Batchelder March 11, 2014

March 11, 2014

New submission from Ned Batchelder <ned(a)nedbatchelder.com>: The docs for os.lseek don't make any mention of its return value. I believe it's the new offset in the file, but I'm not sure if there are other subtleties to be mentioned. ---------- assignee: docs@python components: Documentation messages: 148861 nosy: docs@python, nedbat priority: normal severity: normal status: open title: Docs for os.lseek neglect to mention what it returns versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13530> _______________________________________

9 10

[issue14995] PyLong_FromString documentation should state that the string must be null-terminated
by Ryan Kelly March 2, 2014

March 2, 2014

New submission from Ryan Kelly <ryan(a)rfk.id.au>: PyLong_FromString will raise a ValueError if the given string doesn't contain a null byte after the digits. For example, this will result in a ValueError char *pend; PyLong_FromString("1234 extra", &pend, 10) While this will successfully read the number and set the pointer to the extra data: char *pend; PyLong_FromString("1234\0extra", &pend, 10) The requirement for a null-terminated string of digits is not clear from the docs. Suggested re-wording attached. ---------- assignee: docs@python components: Documentation files: PyLong_FromString-doc.patch keywords: patch messages: 162242 nosy: docs@python, rfk priority: normal severity: normal status: open title: PyLong_FromString documentation should state that the string must be null-terminated Added file: http://bugs.python.org/file25812/PyLong_FromString-doc.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14995> _______________________________________

2 1

[issue13663] pootle.python.org is outdated.
by INADA Naoki Feb. 16, 2014

Feb. 16, 2014

New submission from INADA Naoki <songofacandy(a)gmail.com>: I am one of Japanese translate of Python documents. We have done translating Python 2.7 document and will start translating Python 3.2 or 3.3. I want to use sphinx-i18n and pootle to translate. But http://pootle.python.org/ is very outdated. Anyone can update the site? If nobody maintain the site, could I create Python Document project at http://pootle.locamotion.org/ ? ---------- assignee: docs@python components: Documentation messages: 150261 nosy: docs@python, naoki priority: normal severity: normal status: open title: pootle.python.org is outdated. versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13663> _______________________________________

8 10

[issue14515] tempfile.TemporaryDirectory documented as returning object but returns name
by R. David Murray Feb. 5, 2014

Feb. 5, 2014

New submission from R. David Murray <rdmurray(a)bitdance.com>: The title pretty much says it all. I believe the behavior is correct (more useful than returning an object that is only useful for obtaining the name) even though it is unusual for context managers. In any case there is plenty of code using the existing behavior, so I think this is a doc bug. ---------- assignee: docs@python components: Documentation messages: 157635 nosy: docs@python, r.david.murray priority: normal severity: normal stage: needs patch status: open title: tempfile.TemporaryDirectory documented as returning object but returns name type: behavior versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14515> _______________________________________

6 9

[issue12704] Language References does not specify exception raised by final yield()
by Nikolaus Rath Jan. 27, 2014

Jan. 27, 2014

New submission from Nikolaus Rath <Nikolaus(a)rath.org>: >From http://docs.python.org/reference/simple_stmts.html#the-yield-statement: "As of Python version 2.5, the yield statement is now allowed in the try clause of a try ... finally construct. If the generator is not resumed before it is finalized (by reaching a zero reference count or by being garbage collected), the generator-iterator’s close() method will be called, allowing any pending finally clauses to execute." This strongly suggests that the last-executed yield statement will raise an exception if the generator is closed. If this is the case, it would be great if the documentation could be extended to say what exception is raised. If this is not the case, it would be great if whatever magic is happening could be documented as well. ---------- assignee: docs@python components: Documentation messages: 141724 nosy: Nikratio, docs@python priority: normal severity: normal status: open title: Language References does not specify exception raised by final yield() type: feature request versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12704> _______________________________________

8 18

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

Dec. 22, 2013

New submission from Stefan Behnel <scoder(a)users.sourceforge.net>: http://docs.python.org/library/xml.dom.minidom.html presents MiniDOM as a "Lightweight DOM implementation". The word "lightweight" is easily misunderstood as meaning "efficient" or "memory friendly". MiniDOM is well known to be neither of the two. The first paragraph then continues: """ xml.dom.minidom is a light-weight implementation of the Document Object Model interface. It is intended to be simpler than the full DOM and also significantly smaller. """ Again, "smaller" can be misread as "low memory footprint", whereas it is actually supposed to refer to an incomplete DOM API implementation. And "simpler" is also clearly exaggerated when compared to the alternative ElementTree package. I would like to see this changed and combined with a clear and visible comment that MiniDOM has very high resource profile, e.g. """ 19.7. xml.dom.minidom — Pure Python DOM implementation xml.dom.minidom is a pure Python implementation of the Document Object Model interface, as known from other programming languages. It is intended to provide a smaller API than the full DOM. Note, however, that MiniDOM has a very large memory footprint compared to other Python XML libraries. If you need a fast and memory friendly XML tree implementation with a vastly simpler API, use the xml.etree package instead. """ ---------- assignee: docs@python components: Documentation messages: 129914 nosy: docs@python, scoder priority: normal severity: normal status: open title: Remove "lightweight" from minidom description versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11379> _______________________________________

12 66

[issue12828] xml.dom.minicompat is not documented
by Sandro Tosi Nov. 12, 2013

Nov. 12, 2013

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: There's no documentation for xml.dom.minicompat - it's a public module and it should have (even a brief) doc. ---------- assignee: docs@python components: Documentation messages: 142845 nosy: docs@python, sandro.tosi priority: normal severity: normal status: open title: xml.dom.minicompat is not documented versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12828> _______________________________________

3 3

[issue13515] Consistent documentation practices for security concerns and considerations
by Nick Coghlan Oct. 21, 2013

Oct. 21, 2013

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: This issue proposes that we adopt and apply some standard practices when documenting modules that have potential security implications and other cross-cutting errors that may affect multiple interfaces within the module. Accordingly, the main target is the "Documenting Python" meta-docs, proposing the addition of a new subsection to the Style Guide, with an update to the subprocess module documentation serving as the exemplar of a new recommended style: ====================== 2.6 Security Considerations (and Other Concerns) ------------------------------------------------ Some modules provided with Python are inherently exposed to security issues (e.g. shell injection vulnerabilities) due to the purpose of the module (e.g. subprocess invocation). Littering the documentation of these modules with red warning boxes for problems that are due to the task at hand, rather than specifically to Python's support for that task, doesn't make for a good reading experience. Instead, these security concerns should be gathered into a dedicated "Security Considerations" section within the module's documentation, and cross-referenced from the documentation of affected interfaces with in-line text similar to "Please refer to the :ref:`security-considerations` section for important information on how to avoid common mistakes". Similarly, if there is a common error that affects many interfaces in a module (e.g. OS level pipe buffers filling up and stalling child processes), these can be documented in a "Common Errors" section and cross-referenced rather than repeated for every affected interface. ====================== (based on the thread at http://mail.python.org/pipermail/python-dev/2011-December/114717.html) ---------- assignee: docs@python components: Documentation messages: 148710 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Consistent documentation practices for security concerns and considerations _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________

9 27

[issue14502] Document better what happens on releasing an unacquired lock
by Georg Brandl Oct. 13, 2013

Oct. 13, 2013

New submission from Georg Brandl <georg(a)python.org>: >From docs(a)python.org: """ I recently ran into a situation where I could not be certain that a lock was currently in the acquired state. I checked the documentation to determine what would happen if I attempted to release a lock that was already released, and saw an ominous warning of "Do not call this method when the lock is unlocked." Needing to know what would happen, I cautiously tested it out. I half expected my computer to explode as I released a lock for the second time, but was pleased to see it raise a 'thread.error' exception which could be caught and handled. I generally expect the documentation to tell me what will happen if I do something invalid. In this case the documentation should indicate that a thread.error will be raised if you release an unlocked lock. """ I agree: if we know that a ThreadError will always be raised in this instance, we should document it as such. ---------- assignee: docs@python components: Documentation messages: 157544 nosy: docs@python, georg.brandl, pitrou priority: normal severity: normal status: open title: Document better what happens on releasing an unacquired lock versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14502> _______________________________________

9 23

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

Oct. 13, 2013

New submission from cardinalbiggles <jmandersen(a)gmail.com>: In the threading module, the documentation for Thread.isDaemon()/Thread.setDaemon() indicates they are the old API for Thread.daemon, which does not indicate the version in which it was introduced (2.6 I believe). Additionally, the documentation for Thread.setDaemon() should at least include the daemonic parameter, if not the full usage documentation for those targeting older versions. Targeting Python 2.4, and being unable to (as) efficiently navigate the old documentation site, I have come to rely on the various 'Changed/New in version 2.X' messages in the current documentation. This caused some confusion on my part. ---------- assignee: docs@python components: Documentation messages: 127927 nosy: cardinalbiggles, docs@python priority: normal severity: normal status: open title: threading.Thread.daemon Documentation Incomplete type: feature request versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11120> _______________________________________

2 1

[issue14486] Add some versionchanged notes in threading docs
by Nick Coghlan Oct. 13, 2013

Oct. 13, 2013

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: A (very) minor irritation discovered today - the PEP 8 style names were added to the threading.Thread API in 2.6, but the only notice of this is up at the top of the module docs. Some embedded notices like: ..versionchanged:: 2.6 Added PEP 8 compliant interfaces. See note at top of page. might be helpful. ---------- assignee: docs@python components: Documentation keywords: easy messages: 157451 nosy: docs@python, ncoghlan priority: low severity: normal stage: needs patch status: open title: Add some versionchanged notes in threading docs type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14486> _______________________________________

3 2

[issue13744] raw byte strings are described in a confusing way
by Barry A. Warsaw Oct. 13, 2013

Oct. 13, 2013

New submission from Barry A. Warsaw <barry(a)python.org>: The lexical analysis documentation says this: http://docs.python.org/py3k/reference/lexical_analysis.html?highlight=raw%2… "Bytes literals are always prefixed with 'b' or 'B';..." "Both string and bytes literals may optionally be prefixed with a letter 'r' or 'R';..." But that would lead you to believe that to get raw byte strings you should use rb"foo". In fact, that's a SyntaxError in Python 2.6+ and Python 3. What *does* work though is br"foo". Either Python should accept both spellings (harder) or the documentation should make it clear that the 'b' must preceded the 'r'. ---------- assignee: docs@python components: Documentation messages: 150936 nosy: barry, docs@python priority: normal severity: normal status: open title: raw byte strings are described in a confusing way versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13744> _______________________________________

7 11

[issue13915] Update Tutorial 6.1.3 for PEP 3145
by Terry J. Reedy Oct. 12, 2013

Oct. 12, 2013

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: http://docs.python.org/py3k/tutorial/modules.html#compiled-python-files needs to be updated for 3.2+ to reflect http://python.org/dev/peps/pep-3147/ The first sentence is still technically correct, but finding x.pyc in the same directory as x.py is now an anomaly, so that sentence, revised, should be near the bottom. Otherwise, the text should say that the default is to put x.<version>.pyc in __pycache__, where <version> is, for instance, 'cpython-32'. Note that this allows other implementations and other versions of cpython to use the same .py file. I do not know if there is anywhere else that this info is or should be. Using Python?. ---------- assignee: docs@python components: Documentation messages: 152415 nosy: docs@python, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Update Tutorial 6.1.3 for PEP 3145 type: behavior versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13915> _______________________________________

5 5

[issue13833] No documentation for PyStructSequence
by Torsten Landschoff Oct. 12, 2013

Oct. 12, 2013

New submission from Torsten Landschoff <t.landschoff(a)gmx.net>: While writing a C extension I wanted to create a namedtuple like object as os.statvfs and friends do. I was unable to find a simple way to do this from C and was wondering how the posixmodule does it. It turned out that there is a PyStructSequence type for this. It would be nice to have it documented. First draft for the documentation update attached. ---------- assignee: docs@python components: Documentation files: structseq_doc.diff keywords: patch messages: 151657 nosy: docs@python, torsten priority: normal severity: normal status: open title: No documentation for PyStructSequence type: enhancement versions: Python 3.3 Added file: http://bugs.python.org/file24280/structseq_doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13833> _______________________________________

3 2

[issue13905] Built-in Types Comparisons should mention rich comparison methods
by Catalin Iacob Oct. 12, 2013

Oct. 12, 2013

New submission from Catalin Iacob <iacobcatalin(a)gmail.com>: In 2.7 the Comparisons section of stdtypes.rst only talks about __cmp__ and never mentions the rich comparison methods: "Instances of a class normally compare as non-equal unless the class defines the __cmp__() method. Refer to Basic customization) for information on the use of this method to effect object comparisons." The first sentence is false, instances can also compare as equal if they define __eq__. And since __cmp__ is gone in Python3, I think the rich comparison methods should at least be mentioned, or even emphasized over __cmp__ to help people write more forward compatible code. ---------- assignee: docs@python components: Documentation messages: 152254 nosy: catalin.iacob, docs@python priority: normal severity: normal status: open title: Built-in Types Comparisons should mention rich comparison methods type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13905> _______________________________________

2 2

[issue13026] Dis module - documentation of MAKE_FUNCTION
by Arnaud Delobelle Oct. 12, 2013

Oct. 12, 2013

New submission from Arnaud Delobelle <arnodel(a)googlemail.com>: The description of the opcode MAKE_FUNCTION in the dis module document is out of date. It still describes the 2.X version of the opcode: """ MAKE_FUNCTION(argc) Pushes a new function object on the stack. TOS is the code associated with the function. The function object is defined to have argc default parameters, which are found below TOS. """ According to http://hg.python.org/cpython/file/default/Python/ceval.c#l2684: 2684 int posdefaults = oparg & 0xff; 2685 int kwdefaults = (oparg>>8) & 0xff; 2686 int num_annotations = (oparg >> 16) & 0x7fff; So the documentation should read something like """ MAKE_FUNCTION(argc) Pushes a new function object on the stack. TOS is the code associated with the function. The function object is defined to have argc & 0xFF positional default parameters, (argc >> 8) & 0xFF keyword only default parameters, and (argc >> 16) & 0x7FFF parameter annotations which are push below TOS in this order. For each keyword only default, the name of the parameter is pushed just below its default value. On top of all the annotations, a tuple is pushed listing the parameter names for these annotations. """ ---------- assignee: docs@python components: Documentation messages: 144393 nosy: arno, docs@python, terry.reedy priority: normal severity: normal status: open title: Dis module - documentation of MAKE_FUNCTION versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13026> _______________________________________

4 8

[issue13203] Doc: say id() is only useful for existing objects
by Terry J. Reedy Oct. 12, 2013

Oct. 12, 2013

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: Newbies too often do something like (3.2.2, ) >>> id(getattr(x, 'pop')) == id(x.pop) True and get confused by the (invalid) result, whereas >>> a,b=getattr(x, 'pop'),x.pop >>> id(a)==id(b) False works properly. I think we should add a sentence or two or three to the id() doc, such as Since a newly created argument object is either destroyed or becomes inaccessible before the function returns, *id(obj)* is only useful and valid if *obj* exists prior to the call and therefore after its return. The value of an expression such as *id(666)== id(667)* is arbitrary and meaningless. The id of the first int object might or might not be reused for the second one. ---------- assignee: docs@python components: Documentation messages: 145743 nosy: docs@python, terry.reedy priority: normal severity: normal status: open title: Doc: say id() is only useful for existing objects versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13203> _______________________________________

6 10

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

Oct. 8, 2013

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

6 8

[issue15455] index entries not showing up in glossary
by Chris Jerdonek Oct. 8, 2013

Oct. 8, 2013

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: I haven't tracked down the reason for this, but certain index entries seem to be getting skipped in the Glossary. If you view source on the Glossary page and search for "index-": http://docs.python.org/dev/glossary.html You will find that it skips from 'index-2' to 'index-5'. Only :pep: index entries are getting included even though the Glossary's rst file contains explicit index directives (where 'index-3' and 'index-4' would otherwise be). I tried some experiments, and this seems to occur even if the index directive text does not match the name of the Glossary term. ---------- assignee: docs@python components: Documentation messages: 166467 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: index entries not showing up in glossary type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15455> _______________________________________

3 3

[issue15264] PyErr_SetFromErrnoWithFilenameObject() undocumented
by Antoine Pitrou Oct. 8, 2013

Oct. 8, 2013

New submission from Antoine Pitrou <pitrou(a)free.fr>: Title says it all. ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 164736 nosy: docs@python, pitrou priority: normal severity: normal stage: needs patch status: open title: PyErr_SetFromErrnoWithFilenameObject() undocumented type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15264> _______________________________________

2 1

[issue13867] misleading comment in weakrefobject.h
by Jim Jewett Oct. 8, 2013

Oct. 8, 2013

New submission from Jim Jewett <jimjjewett(a)gmail.com>: http://hg.python.org/cpython/file/fec45282dc28/Include/weakrefobject.h#l54 The comment makes sense -- but doesn't appear to be true, so perhaps it is the macro that should change. /* This macro calls PyWeakref_CheckRef() last since that can involve a function call; this makes it more likely that the function call will be avoided. */ #define PyWeakref_Check(op) \ (PyWeakref_CheckRef(op) || PyWeakref_CheckProxy(op)) ---------- assignee: docs@python components: Documentation, Extension Modules messages: 151983 nosy: Jim.Jewett, docs@python priority: normal severity: normal status: open title: misleading comment in weakrefobject.h _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13867> _______________________________________

4 5

[issue14224] packaging: path description of resources is mixed up
by Johannes Kolb Oct. 8, 2013

Oct. 8, 2013

New submission from Johannes Kolb <johannes.kolb(a)gmx.net>: The documentation for "files" section of the setup.cfg file causes confusion: The examples don't match the description. Obviously the order of "destination" and "source" part in the generated filenames was mixed up in some places. ---------- assignee: docs@python components: Documentation files: packaging-docfixes.diff keywords: patch messages: 155123 nosy: docs@python, jokoala priority: normal severity: normal status: open title: packaging: path description of resources is mixed up type: behavior versions: Python 3.3 Added file: http://bugs.python.org/file24754/packaging-docfixes.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14224> _______________________________________

3 2

[issue13436] compile() doesn't work on ImportFrom with level=None
by Janosch Gräf Oct. 8, 2013

Oct. 8, 2013

New submission from Janosch Gräf <janosch.graef(a)gmx.net>: The documentation for ast says that arguments that are marked with a '?' in the abstract grammar are optional and can therefore be None. When I try to compile a Module node which contains an ImportFrom node with attribute level=None compile() throws an exception: Module(body=[ImportFrom(module='time', names=[alias(name='sleep', asname=None), alias(name='time', asname=None)], level=None, lineno=0, col_offset=0)]) Traceback (most recent call last): File "g0.py", line 423, in <module> p.main() File "g0.py", line 65, in main self.reproduce("g1.pyc") File "g0.py", line 85, in reproduce co = self.generate_bytecode(st, genome) File "g0.py", line 243, in generate_bytecode co = compile(st, id, "exec") ValueError: invalid integer value: �� So, I tried to set level=0: Module(body=[ImportFrom(module='time', names=[alias(name='sleep', asname=None), alias(name='time', asname=None)], level=0, lineno=0, col_offset=0)]) and everything worked fine. BTW: The unprintable bytes in the error message are: ef bf bd ef bf bd ef bf bd ef bf bd ef bf bd ef bf bd ef bf bd ef bf bd ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 147972 nosy: Janosch.Gräf, docs@python priority: normal severity: normal status: open title: compile() doesn't work on ImportFrom with level=None type: behavior versions: Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13436> _______________________________________

6 9

[issue12162] Documentation about re \number
by Seth Troisi Oct. 6, 2013

Oct. 6, 2013

New submission from Seth Troisi <braintwo(a)gmail.com>: It would be nice to clarify re documentation on how to use \number. current documentation lists three half examples: "(.+) \1 matches 'the the' or '55 55', but not 'the end' (note the space after the group)." This is rather confusing (at least to me) as it might be assumed that re.search("(.+) \1", "the the") would return a match, which it does not. A better example would be re.search("(\w+) \\1", "the the") which does match. the other confusing portion is the requirement of the second "\" to make it match. I would think that a quick example below the text would help. >>> re.search("(\w+) \\1", "can you do the can can?") # \\1 matches the second can at the end of the sentence <_sre.SRE_Match object at ...> This is my first python issue and if I have misfiled or left out some information please tell me how to proceed. ---------- assignee: docs@python components: Documentation messages: 136708 nosy: Seth.Troisi, docs@python priority: normal severity: normal status: open title: Documentation about re \number type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12162> _______________________________________

5 8

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

Oct. 6, 2013

New submission from Carsten Klein <carsten.klein(a)axn-software.de>: In zope.interface, you have something the following construct: class InterfaceBase: pass Interface = InterfaceBase() Using the above Interface as a derivation base for your own classes, will make that instance a type derived class: class IFoo(Interface): pass type(IFoo) -> Interface type(Interface) -> type I wonder why this behavior is not documented in the official documentation, or at least, I was unable to find it there... ---------- assignee: docs@python components: Documentation messages: 133173 nosy: carsten.klein, docs@python priority: normal severity: normal status: open title: Extend upon metaclass/type class documentation, here: zope.interface and usage of instances of classes as base classes type: feature request versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11789> _______________________________________

2 2

[issue11585] Documentation 1.8 shows Python 2 example
by Clive Darke Oct. 6, 2013

Oct. 6, 2013

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

2 2

[issue14101] example function in tertools.count is misindented
by Zbyszek Szmek Oct. 6, 2013

Oct. 6, 2013

New submission from Zbyszek Szmek <zbyszek(a)in.waw.pl>: Indentation is broken. diff --git a/Modules/itertoolsmodule.c b/Modules/itertoolsmodule.c --- a/Modules/itertoolsmodule.c +++ b/Modules/itertoolsmodule.c @@ -3221,10 +3221,10 @@ Return a count object whose .__next__() method returns consecutive values.\n\ Equivalent to:\n\n\ def count(firstval=0, step=1):\n\ - x = firstval\n\ - while 1:\n\ - yield x\n\ - x += step\n"); + x = firstval\n\ + while 1:\n\ + yield x\n\ + x += step\n"); ---------- assignee: docs@python components: Documentation, Library (Lib) files: itertools-count-indentation.diff keywords: patch messages: 154084 nosy: docs@python, zbysz priority: normal severity: normal status: open title: example function in tertools.count is misindented type: enhancement versions: Python 3.3 Added file: http://bugs.python.org/file24618/itertools-count-indentation.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14101> _______________________________________

4 3

[issue15432] gzip.py: mtime argument only since python 2.7
by Geir Ove Myhr Oct. 6, 2013

Oct. 6, 2013

New submission from Geir Ove Myhr <gomyhr(a)gmail.com>: In the gzip documentation (http://docs.python.org/library/gzip.html) a note should be added that the mtime option was added in Python 2.7. The patch which adds the option (http://svn.python.org/view?view=revision&revision=68319) is not included in Python 2.6.5. ---------- assignee: docs@python components: Documentation messages: 166214 nosy: docs@python, gomyhr priority: normal severity: normal status: open title: gzip.py: mtime argument only since python 2.7 versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15432> _______________________________________

2 2

[issue15228] os.utime() docs not clear on behavior on nonexistant files
by Daniel Grace Oct. 6, 2013

Oct. 6, 2013

New submission from Daniel Grace <thisgenericname(a)gmail.com>: The documentation for os.utime() at http://docs.python.org/py3k/library/os.html#os.utime states: "Set the access and modified times of the file specified by path. [...] The effect is similar to running the Unix program touch on the path.)" Unlike 'touch', os.utime() will not create an empty file if called on a file that does not exist. IMO the current behavior is correct, but the comparison of os.utime() to touch implies that it would create empty files. I suggest clarifying the documentation to emphasize that os.utime() will not create new files and raises OSError in the event that the file does not exist. ---------- assignee: docs@python components: Documentation messages: 164422 nosy: dewin, docs@python priority: normal severity: normal status: open title: os.utime() docs not clear on behavior on nonexistant files type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15228> _______________________________________

4 4

[issue11807] Documentation of add_subparsers lacks information about parametres
by Filip Gruszczyński Oct. 6, 2013

Oct. 6, 2013

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

3 8

[issue15213] _PyOS_URandom documentation
by Christian Heimes Oct. 6, 2013

Oct. 6, 2013

New submission from Christian Heimes <lists(a)cheimes.de>: The comment for Python/random.c:_PyOS_URandom() states > Fill buffer with size pseudo-random bytes, not suitable for cryptographic use, from the operating random number generator (RNG). which is not correct as all paths use a RNG that is suitable for most cryptographic purposes except long living private keys for asymmetric encryption. Also the function isn't documented although it's an official API function and plays a vital role on the new hash randomization. ---------- assignee: docs@python components: Documentation messages: 164218 nosy: christian.heimes, docs@python, haypo, pitrou priority: low severity: normal status: open title: _PyOS_URandom documentation versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15213> _______________________________________

5 6

[issue12350] Improve stat_result.st_blocks and st_blksize documentation
by Lars Wirzenius Oct. 6, 2013

Oct. 6, 2013

New submission from Lars Wirzenius <liw(a)liw.fi>: Attached patch adds a few words to the os.stat documentation for the st_blocks and st_blksize fields to clarify them. ---------- assignee: docs@python components: Documentation files: stat_result.patch keywords: patch messages: 138467 nosy: docs@python, liw priority: normal severity: normal status: open title: Improve stat_result.st_blocks and st_blksize documentation versions: Python 2.7 Added file: http://bugs.python.org/file22382/stat_result.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12350> _______________________________________

4 10

[issue11163] iter() documentation code doesn't work
by Michael Grazebrook Sept. 11, 2013

Sept. 11, 2013

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

6 10

[issue15233] atexit: guarantee order of execution of registered functions?
by Georg Brandl Aug. 21, 2013

Aug. 21, 2013

New submission from Georg Brandl <georg(a)python.org>: Currently, the atexit docs state "The order in which the functions are called is not defined" in the introduction and "all functions registered are called in last in, first out order" in the docs of the atexit() function. While the latter is correct, I don't think we should guarantee that behaviour by documenting it. Suggestions? ---------- assignee: docs@python components: Documentation messages: 164454 nosy: docs@python, georg.brandl, loewis, pitrou priority: normal severity: normal status: open title: atexit: guarantee order of execution of registered functions? versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15233> _______________________________________

8 23

[issue12645] test.support. import_fresh_module - incorrect doc
by Eli Bendersky Aug. 11, 2013

Aug. 11, 2013

New submission from Eli Bendersky <eliben(a)gmail.com>: >From Ezio Melotti's email to python-dev: diff --git a/Doc/library/test.rst b/Doc/library/test.rst --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -447,7 +447,7 @@ Module and package deprecation messages are suppressed during this import if *deprecated* is ``True``. - This function will raise :exc:`unittest.SkipTest` is the named module + This function will raise :exc:`unittest.SkipTest` if the named module Actually I think this is no longer true. import_fresh_module raises an ImportError if *name* can't be imported, or returns None if the fresh module is not found. Its use case is to enable or block accelerations for modules that optionally provide one. All the modules that currently use import_fresh_module are (afaik) always available (json, warnings, heapq), so raising SkipTest when the module is missing is not useful now. It returns None in the case an acceleration is missing, so e.g. in "cjson = import_fresh_module('json', fresh=['_json'])" cjson will be None and it will be possible to do things like @skipUnless(cjson, 'requires _json'). Here raising an ImportError will defeat (part of) the purpose of the function, i.e. avoiding: try: import _json except ImportError: _json = None and raising a SkipTest when the accelerations are missing is not an option if there are other tests (e.g. the tests for the Python implementation). These changes come from http://hg.python.org/cpython/rev/c1a12a308c5b . Before the change import_fresh_module was still returning the module (e.g. json) even when the acceleration (fresh=['_json']) was missing, and the C tests were run twice using the same pure-python module used for the Py ones. The typo and the wrong doc is also on 2.7. ---------- assignee: docs@python components: Documentation keywords: easy messages: 141255 nosy: docs@python, eli.bendersky, ezio.melotti priority: normal severity: normal status: open title: test.support. import_fresh_module - incorrect doc versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12645> _______________________________________

5 9

[issue10434] Document the rules for "public names"
by Alexander Belopolsky Aug. 1, 2013

Aug. 1, 2013

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: As discussed in "Breaking undocumented API" thread [1] on python-dev, a definition of "public names" is buried deep in the language reference manual: """ The public names defined by a module are determined by checking the module’s namespace for a variable named __all__; if defined, it must be a sequence of strings which are names defined or imported by that module. The names given in __all__ are all considered public and are required to exist. If __all__ is not defined, the set of public names includes all names found in the module’s namespace which do not begin with an underscore character ('_'). __all__ should contain the entire public API. It is intended to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module). """ [2] It has been argued that this is not the authoritative definition and alternatives have been suggested such as "any name that does not begin with an underscore except imported modules." mportant for the users and developers of cpython and other python implementations to know what names they can rely upon to stay defined between releases, the rules for "public names" should be documented. I agree that the library manual is a more appropriate place for such documentation. The definition should include the naming conventions and the set of promises that Python makes about public name availability in the future releases. [1] http://mail.python.org/pipermail/python-dev/2010-November/105490.html [2] http://docs.python.org/reference/simple_stmts.html ---------- assignee: docs@python components: Documentation messages: 121297 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: Document the rules for "public names" versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10434> _______________________________________

6 7

[issue15130] remove redundant paragraph in socket howto
by Tshepang Lekhonkhobe July 25, 2013

July 25, 2013

New submission from Tshepang Lekhonkhobe <tshepang(a)gmail.com>: same text used on Abstract is used in the beginning of the main text ---------- assignee: docs@python components: Documentation files: redundancy.diff keywords: patch messages: 163364 nosy: docs@python, tshepang priority: normal severity: normal status: open title: remove redundant paragraph in socket howto versions: Python 2.7, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file26076/redundancy.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15130> _______________________________________

4 4

[issue11908] Weird `slice.stop or sys.maxint`
by Ram Rachum July 11, 2013

July 11, 2013

New submission from Ram Rachum <cool-rr(a)cool-rr.com>: In the documentation for `itertools.islice` I see this line: it = iter(xrange(s.start or 0, s.stop or sys.maxint, s.step or 1)) Is it really okay to do `s.stop or sys.maxint`? I'm assuming this was targeting `None`, but what if `s.stop == 0`? And `s.step` could (pathologically) be `0` too, no? ---------- assignee: docs@python components: Documentation messages: 134276 nosy: cool-RR, docs@python priority: normal severity: normal status: open title: Weird `slice.stop or sys.maxint` type: behavior versions: Python 2.5, Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11908> _______________________________________

8 13

[issue14206] multiprocessing.Queue documentation is lacking important details
by Garrett Moore July 2, 2013

July 2, 2013

New submission from Garrett Moore <garrettmoore(a)gmail.com>: 1) If cancel_join_thread() is called, data may be lost. This is not explicitly stated. I had multiple writers put() data in a Queue, and wanted to have the workers finish before I began consuming the data. This caused a deadlock because my Queue was not empty, and it seemed like the a way to force my workers finish was to use cancel_join_thread(). This caused data loss. 2) multiprocessing.Queue states "The Queue class is a near clone of Queue.Queue." Queue.Queue states "If maxsize is less than or equal to zero, the queue size is infinite." mp.Queue provides no information on queue size. It is reasonable to assume then that it inherits the property of Queue.Queue. After discussion on IRC, it seems that mp.Queue maximum size is implementation-dependent and likely relies on how much data Pipes can hold on your platform. If this is the case there should be some mention of the fact that mp.Queue does NOT function like Queue.Queue does for maximum size. ---------- assignee: docs@python components: Documentation messages: 154995 nosy: Garrett.Moore, docs@python priority: normal severity: normal status: open title: multiprocessing.Queue documentation is lacking important details versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14206> _______________________________________

4 4

[issue12716] Reorganize os docs for files/dirs/fds
by Benjamin Peterson June 29, 2013

June 29, 2013

New submission from Benjamin Peterson <benjamin(a)python.org>: Right now many of the os function docs are split up into "Files and directories" and "file descriptor operations". This means, for example, that fchmod() and fchmodat() are in a different section than chmod(). It would make more sense to organize the docs such that functions that do the same thing are right next to each other. ---------- assignee: docs@python components: Documentation keywords: easy messages: 141820 nosy: benjamin.peterson, docs@python priority: low severity: normal status: open title: Reorganize os docs for files/dirs/fds versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12716> _______________________________________

7 9

[issue15818] multiprocessing documentation of Process.exitcode
by Josh Kupershmidt June 24, 2013

June 24, 2013

New submission from Josh Kupershmidt: [I tried to send this as an email to docs(a)python.org yesterday, but it seems to have gotten eaten, as I don't see the message in the archives.] Hi all, The documentation for the multiprocessing module claims: | Note that the start(), join(), is_alive() and exit_code methods | should only be called by the process that created the process object. Two problems with this description: 1. "exit_code" should be spelled "exitcode" 2. exitcode is an attribute of the Process class, not a method as claimed, since the underlying method is decorated with @property Also, aside from the above documentation issues, if it is true that it's not safe to query the exitcode from a separate process, should the exitcode property method include a check like so: assert self._parent_pid == os.getpid(), 'can only test a child process' since start(), join(), and is_alive() all perform this check? ---------- assignee: docs@python components: Documentation messages: 169428 nosy: docs@python, schmiddy priority: normal severity: normal status: open title: multiprocessing documentation of Process.exitcode versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15818> _______________________________________

3 3

[issue14015] surrogateescape largely missing from documentation
by Jim Jewett June 16, 2013

June 16, 2013

New submission from Jim Jewett <jimjjewett(a)gmail.com>: Recent discussion on the mailing lists and in http://bugs.python.org/issue13997 make it clear that the best way to get python2 results for "ASCII-in-the-parts-I-might-process-or-change" is to replace f = open(fname) with f = open(fname, encoding="ascii", errors="surrogateescape") Unfortunately, surrogateescape (let alone this recipe) is not easily discoverable. http://docs.python.org/dev/library/functions.html#open lists 5 error-handlers -- but not this one. It says that other error handlers are possible if they are registered with http://docs.python.org/dev/library/codecs.html#codecs.register_error but I haven't found a way to determine which error handlers are already registered. The codecs.register (as opposed to register_error) documentation does list it as a possible value, but that is the only reference. The other 5 error handlers are also available as module-level functions within the codecs module, and have their own documenation sections within http://docs.python.org/dev/library/codecs.html Neither help(open) nor import codecs; help(codecs) provides any hints of the existence of surrogateescape. Both explicitly suggest that it does not exist, by enumerating other values. ---------- assignee: docs@python components: Documentation, Unicode messages: 153359 nosy: Jim.Jewett, docs@python, ezio.melotti priority: normal severity: normal status: open title: surrogateescape largely missing from documentation versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14015> _______________________________________

5 5

[issue14616] subprocess docs should mention pipes.quote/shlex.quote
by Éric Araujo May 28, 2013

May 28, 2013

New submission from Éric Araujo <merwok(a)netwok.org>: The warning at http://docs.python.org/library/subprocess#frequently-used-arguments should IMO recommend using shlex.quote. Even if it strongly advises against using shell=True, there are people who need or want to use it, so let’s give them a pointer to the quote function. For older versions, I think we should talk about pipes.quote; even if it’s not documented in library/pipes, it is there, it is known and it is used, so I see no harm in mentioning it (with due mention that it’s only semi-official and that it becomes public in 3.3). ---------- assignee: docs@python components: Documentation messages: 158641 nosy: docs@python, eric.araujo priority: normal severity: normal status: open title: subprocess docs should mention pipes.quote/shlex.quote versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________

6 19

[issue14009] Clearer documentation for cElementTree
by Éric Araujo May 20, 2013

May 20, 2013

New submission from Éric Araujo <merwok(a)netwok.org>: This patch should clarify how to use cElementTree usage, as well as improving indexing. ---------- assignee: docs@python components: Documentation messages: 153338 nosy: docs@python, eli.bendersky, eric.araujo priority: normal severity: normal stage: commit review status: open title: Clearer documentation for cElementTree versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________

4 13

[issue14878] send statement from PEP342 is poorly documented.
by Stephen Lacy May 10, 2013

May 10, 2013

New submission from Stephen Lacy <slacy(a)slacy.com>: There's reasonable documentation of the yield statement for most python versions under Section 6: Simple Statements, particularly 6.8 "The Yield Statement" (http://docs.python.org/release/2.7/reference/simple_stmts.html#the-yield-st…) But, there's no mention of the return value of the yield statement, or that the send statement even exists. It's mentioned in passing here under "PEP342 New Generator Features" (http://docs.python.org/whatsnew/2.5.html#pep-342-new-generator-features) but should be given fuller explanation and cross-linking from the yield statement documentation. It's also mentioned a bit here: http://docs.python.org/howto/functional.html#passing-values-into-a-generator but again, not under the language documentation itself. ---------- assignee: docs@python components: Documentation messages: 161320 nosy: Stephen.Lacy, docs@python priority: normal severity: normal status: open title: send statement from PEP342 is poorly documented. 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/issue14878> _______________________________________

6 6

[issue14187] add "annotation" entry to Glossary
by Chris Rebert May 6, 2013

May 6, 2013

New submission from Chris Rebert <pybugs(a)rebertia.com>: The Glossary should include an entry for "annotation" and/or "function annotation" regarding the language feature introduced by PEP 3107. ---------- assignee: docs@python components: Documentation messages: 154852 nosy: cvrebert, docs@python priority: normal severity: normal status: open title: add "annotation" entry to Glossary versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14187> _______________________________________

8 23

[issue12825] Missing and incorrect link to a command line option.
by Kyle Simpson April 23, 2013

April 23, 2013

New submission from Kyle Simpson <illwhipyou(a)gmail.com>: The documentation for the runpy module has a link to the -m command line option. In version 2.7.2 of the docs, the link doesn't exist. http://docs.python.org/release/2.7/library/runpy.html http://docs.python.org/release/2.7.2/library/runpy.html If you run touch library/runpy.rst make html then the link is created, but with an anchor of "cmdoption-unittest-discover-m" instead of "cmdoption-m". http://docs.python.org/release/2.7.2/using/cmdline.html#cmdoption-unittest-… ---------- assignee: docs@python components: Documentation messages: 142797 nosy: Kyle.Simpson, docs@python priority: normal severity: normal status: open title: Missing and incorrect link to a command line option. versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12825> _______________________________________

2 3

[issue15575] Tutorial is unclear on multiple imports of a module.
by Roy Smith April 21, 2013

April 21, 2013

New submission from Roy Smith: Opening this bug at Ben Finney's request. See https://groups.google.com/forum/?fromgroups#!topic/comp.lang.python/wmDUrpW… for the full thread discussing the problem. Here's a significant excerpt: ------------------------------------------------- The tutorial is misleading on this. It it says plainly: A module can contain executable statements as well as function definitions. […] They are executed only the *first* time the module is imported somewhere. <URL:http://docs.python.org/tutorial/modules.html> but it doesn't make clear that a module can exist in the ‘sys.modules’ list multiple times under different names. ------------------------------------------------- Also note: -------------------------------------------------- The footnote to that is wrong too: > [1] In fact function definitions are also ‘statements’ that are ‘executed’; the execution of a module-level function enters the function name in the module’s global symbol table. I think what it's supposed to say is "... the execution of a module-level def statement ..." --------------------------------------------------- ---------- assignee: docs@python components: Documentation messages: 167628 nosy: docs@python, roysmith priority: normal severity: normal status: open title: Tutorial is unclear on multiple imports of a module. type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15575> _______________________________________

5 5

[issue13510] Clarify that readlines() is not needed to iterate over a file
by Peter Otten April 15, 2013

April 15, 2013

New submission from Peter Otten <__peter__(a)web.de>: I've been looking at code on the tutor mailing list for some time, and for line in file.readlines(): ... is a common idiom there. I suppose this is because the readlines() method is easily discoverable while the proper way (iterate over the file object directly) is not. A note added to the readlines() documentation might help: """ You don't need the readlines() method to loop over the lines of a file. for line in file: process(line) consumes less memory and is often faster. """ ---------- assignee: docs@python components: Documentation messages: 148679 nosy: docs@python, potten priority: normal severity: normal status: open title: Clarify that readlines() is not needed to iterate over a file type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13510> _______________________________________

12 21

[issue13050] RLock support the context manager protocol but this is not documented
by Brian Brazil April 14, 2013

April 14, 2013

New submission from Brian Brazil <brian.brazil(a)gmail.com>: This is already documented: http://docs.python.org/library/threading.html#using-locks-conditions-and-se… ---------- nosy: +bbrazil _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13050> _______________________________________

6 5

compileall module: exclusion example is path separator-specific
by Paul A. Giannaros April 14, 2013

April 14, 2013

Hi, The docs for compileall give an example of compiling pyc files in a directory while excluding '.svn' subdirectories: compileall.compile_dir('Lib/', rx=re.compile('/[.]svn'), force=True) Neither this part nor documentation for the 'rx' attribute make clear that the paths searched with the regular expression will have OS specific separators. This example doesn't work on Windows, for example. I think the example should be explicit that the paths will contain the native separators (or it should use pathsep instead of '/', or maybe '[/\\]', to make it clearer in the example). Thanks, Paul

2 1

Bug in the Reference Data Model
by Ted Yin April 14, 2013

April 14, 2013

It's said that : When it would yield a class method object, it is transformed into a bound user-defined method object whose im_class and im_self attributes are both C. in the Reference <http://docs.python.org/reference/datamodel.html> And I did an EX. >>> class C(object) : ... @classmethod ... def cm(cls) : print cls ... >>> C.cm <bound method type.cm of <class '__main__.C'>> >>> C.cm.im_self <class '__main__.C'> >>> C.cm.im_class <type 'type'> It's not hard for me to understand the result. But unfortunately, in the reference, it's told that im_self should be *the same* as im_class. And in my opinion , 'im_self' shold be C, but im_class is 'type' since C's metaclass is type. So they're obviously *not* 'both C'. -- [This information is automatically generated] *ted.sybil* aka. *ymfoi* aka. *Ted Yin*

2 2

Bug Report: Incorrect Abstract Method Requirements in numbers.Integral Documentation
by Lefavor, Matthew (GSFC-582.0)[MICROTEL LLC] April 14, 2013

April 14, 2013

To whom it may concern: The documentation for numbers.Integral reports incorrect abstract method requirements for numbers.Integral. The documentation for numbers.Integral (in both Python 2.7 and Python 3.2) states: Subtypes Rational<http://docs.python.org/library/numbers.html#numbers.Rational> and adds a conversion to int<http://docs.python.org/library/functions.html#int>. Provides defaults for float()<http://docs.python.org/library/functions.html#float>, numerator<http://docs.python.org/library/numbers.html#numbers.Rational.numerator>, and denominator<http://docs.python.org/library/numbers.html#numbers.Rational.denominator>, and bit-string operations: <<, >>, &, ^, |, ~. Defaults for operations <<, >>, &, ^, |, and ~ are not provided, and a look at the source code shows that they are all given as abstract methods. In addition, in Python 2.x, numbers.Integral adds an abstract conversion to long. This is not recorded in the documentation. Originally, I was going to report this as a bug, because PEP 3141<http://www.python.org/dev/peps/pep-3141/> (the PEP that specifies the numbers module) goes so far as to include the <<, >>, &, ^, |, and ~ in the source code for numbers.Integral. It looks like somebody already had reported this years ago, however, to python-dev with Issue 3056<http://bugs.python.org/issue3056>. The issue was never resolved, but has since been closed. Since the development community does not seem interested in adding these features, the features should be removed from documentation. Thank you for your time, Matthew Lefavor NASA GSFC [Microtel, LLC] Mail Code 699.0/Org Code 582.0 matthew.lefavor(a)nasa.gov (301) 614-6818 (Desk) (443) 758-4891 (Cell)

2 1

'Bug' in modules tutorial
by Wenceslao Grillo April 14, 2013

April 14, 2013

Hi, guys, I'm only starting out with Python, and the docs are a great help. Congrats on an excelent work! Found a bug though: in <http://docs.python.org/tutorial/modules.html> there's a footnote that reads: In fact function definitions are also 'statements' that are 'executed'; the execution of a module-level function enters the function name in the module's global symbol table. It seems to me it should be: In fact function definitions are also 'statements' that are 'executed'; the execution of a module-level function *definition* enters the function name in the module's global symbol table. Congrats again! Regards: Wences

2 1

integer leak in refcount docs?
by Daniel Shahaf April 14, 2013

April 14, 2013

In <http://docs.python.org/c-api/intro.html#reference-count-details>, the example code reads: 1 int 2 set_all(PyObject *target, PyObject *item) 3 { 4 int i, n; 5 6 n = PyObject_Length(target); 7 if (n < 0) 8 return -1; 9 for (i = 0; i < n; i++) { 10 PyObject *index = PyInt_FromLong(i); 11 if (!index) 12 return -1; 13 if (PyObject_SetItem(target, index, item) < 0) 14 return -1; 15 Py_DECREF(index); 16 } 17 return 0; 18 } Seems to me that line 14 leaks a reference to 'index'; that is: @@ -13,2 +13,4 @@ - if (PyObject_SetItem(target, index, item) < 0) + if (PyObject_SetItem(target, index, item) < 0) { + Py_DECREF(index); return -1; + } Does that make sense?

2 1

Python 3 doc update (re) symbolic group: name validity.
by Patrice Joulain April 14, 2013

April 14, 2013

Hello, I'd like to report a bug dealing with update from Python 2 to Python 3, in the Python 3.x Documentation. Python Standard Library / Chapter 6.2.1 Regular Expression Syntax - says "Group names must be valid Python identifiers" which is not true for 3.x . (?P<name>...) accepts Python 2 valid identifier only (contrary to named fields of collections.namedtuple). I've checked re-HOWTO and tutorial: no specification about valididity of group name, hence no mistake. >>> re.match(r'(?P<DejaVu>test)','test') <_sre.SRE_Match object at 0x00BF25A0> >>> assert 'DéjàVu'.isidentifier() >>> re.match(r'(?P<DéjàVu>test)','test') Traceback (most recent call last): File "C:\Python32\lib\functools.py", line 176, in wrapper result = cache[key] KeyError: (<class 'str'>, '(?P<DéjàVu>test)', 0) During handling of the above exception, another exception occurred: Traceback (most recent call last): File "<stdin>", line 1, in <module> File "C:\Python32\lib\re.py", line 153, in match return _compile(pattern, flags).match(string) File "C:\Python32\lib\re.py", line 255, in _compile return _compile_typed(type(pattern), pattern, flags) File "C:\Python32\lib\functools.py", line 180, in wrapper result = user_function(*args, **kwds) File "C:\Python32\lib\re.py", line 267, in _compile_typed return sre_compile.compile(pattern, flags) File "C:\Python32\lib\sre_compile.py", line 491, in compile p = sre_parse.parse(p, flags) File "C:\Python32\lib\sre_parse.py", line 692, in parse p = _parse_sub(source, pattern, 0) File "C:\Python32\lib\sre_parse.py", line 315, in _parse_sub itemsappend(_parse(source, state)) File "C:\Python32\lib\sre_parse.py", line 552, in _parse raise error("bad character in group name") sre_constants.error: bad character in group name >>> => From Lib\sre_parse.py: def isident(char): return "a" <= char <= "z" or "A" <= char <= "Z" or char == "_" def isdigit(char): return "0" <= char <= "9" def isname(name): # check that group name is a valid stringEnvoyer if not isident(name[0]): return False for char in name[1:]: if not isident(char) and not isdigit(char): return False return True Thank you for dealing this report (Sorry for my bad english). Waiting for some response: <pat.jln(a)hotmail.fr>

2 1

[issue14462] In re's named group the name cannot contain unicode characters
by py.user April 14, 2013

April 14, 2013

New submission from py.user <port139(a)yandex.ru>: http://docs.python.org/py3k/library/re.html "(?P<name>...) Similar to regular parentheses, but the substring matched by the group is accessible within the rest of the regular expression via the symbolic group name name. Group names must be valid Python identifiers, and each group name must be defined only once within a regular expression." >>> chr(255) 'ÿ' >>> 'ÿ'.isidentifier() True >>> import re >>> re.search(r'(?P<ÿ>a)', 'abc') Traceback (most recent call last): File "/usr/local/lib/python3.2/functools.py", line 176, in wrapper result = cache[key] KeyError: (<class 'str'>, '(?P<ÿ>a)', 0) During handling of the above exception, another exception occurred: Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/local/lib/python3.2/re.py", line 158, in search return _compile(pattern, flags).search(string) File "/usr/local/lib/python3.2/re.py", line 255, in _compile return _compile_typed(type(pattern), pattern, flags) File "/usr/local/lib/python3.2/functools.py", line 180, in wrapper result = user_function(*args, **kwds) File "/usr/local/lib/python3.2/re.py", line 267, in _compile_typed return sre_compile.compile(pattern, flags) File "/usr/local/lib/python3.2/sre_compile.py", line 491, in compile p = sre_parse.parse(p, flags) File "/usr/local/lib/python3.2/sre_parse.py", line 692, in parse p = _parse_sub(source, pattern, 0) File "/usr/local/lib/python3.2/sre_parse.py", line 315, in _parse_sub itemsappend(_parse(source, state)) File "/usr/local/lib/python3.2/sre_parse.py", line 552, in _parse raise error("bad character in group name") sre_constants.error: bad character in group name >>> also: (?P=name) (?(name)yes|no) \g<name> ---------- assignee: docs@python components: Documentation, Regular Expressions messages: 157266 nosy: docs@python, ezio.melotti, mrabarnett, py.user priority: normal severity: normal status: open title: In re's named group the name cannot contain unicode characters type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14462> _______________________________________

5 5

[issue13638] PyErr_SetFromErrnoWithFilenameObject is undocumented
by Antoine Pitrou April 14, 2013

April 14, 2013

New submission from Antoine Pitrou <pitrou(a)free.fr>: Its declaration can be found in Include/pyerrors.h. Same for PyErr_SetExcFromWindowsErrWithFilenameObject. ---------- assignee: docs@python components: Documentation messages: 149877 nosy: arnaudc, docs@python, haypo, pitrou priority: normal severity: normal stage: needs patch status: open title: PyErr_SetFromErrnoWithFilenameObject is undocumented versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13638> _______________________________________

2 1

Apparent bug in python socket howto
by Patrick Maupin April 14, 2013

April 14, 2013

Thanks for the howto. It's a great conceptual introduction, and I was happy to have it to read when I needed to get my hands a bit dirtier than using SocketServer. But the statement "If we had used s.bind(('', 80)) [the socket would only be] visible within the same machine." appears to be incorrect. As the socket module documentation states, "the empty string represents INADDR_ANY." Thanks and best regards, Patrick Maupin Austin, Texas

2 1

[issue12768] docstrings for the threading module
by Eli Bendersky April 13, 2013

April 13, 2013

New submission from Eli Bendersky <eliben(a)gmail.com>: The threading module has very few methods with docstrings. Docstrings should be added to all public methods (contents can be borrowed from the documentation). ---------- assignee: docs@python components: Documentation keywords: easy messages: 142247 nosy: docs@python, eli.bendersky priority: low severity: normal stage: needs patch status: open title: docstrings for the threading module type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12768> _______________________________________

6 29

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

April 4, 2013

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

12 28

[issue12207] Document ast.PyCF_ONLY_AST
by Éric Araujo March 25, 2013

March 25, 2013

New submission from Éric Araujo <merwok(a)netwok.org>: Title says it all. ---------- assignee: docs@python components: Documentation files: document-pycf-only-ast.diff keywords: needs review, patch messages: 137203 nosy: docs@python, eric.araujo priority: normal severity: normal stage: patch review status: open title: Document ast.PyCF_ONLY_AST versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file22175/document-pycf-only-ast.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12207> _______________________________________

5 8

[issue11367] xml.etree.ElementTree.find(all): docs are wrong
by anatoly techtonik March 12, 2013

March 12, 2013

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

5 19

[issue14489] repr() function link on the built-in function documentation is incorrect
by H Xu March 10, 2013

March 10, 2013

New submission from H Xu <xuhdev(a)gmail.com>: The `repr()` built-in function link in this page [ http://docs.python.org/library/functions.html ] should link to the built-in version of `repr()`. It should link to: http://docs.python.org/library/functions.html#repr However, it links to here: http://docs.python.org/library/repr.html#module-repr ---------- assignee: docs@python components: Documentation messages: 157462 nosy: H.Xu, docs@python priority: normal severity: normal status: open title: repr() function link on the built-in function documentation is incorrect versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14489> _______________________________________

6 11

[issue15465] Improved documentation for C API version info
by Nick Coghlan March 7, 2013

March 7, 2013

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: As far as I can tell, the only mentions of the C API version macros are: 1. In the prose for the stable ABI section (incidentally: this section has a typo in the title) 2. In the documentation for sys.hexversion There should be a clear "API and ABI Versioning" section in the C API docs that covers: PY_LIMITED_API PY_HEX_VERSION PY_MAJOR_VERSION PY_MINOR_VERSION PY_MICRO_VERSION PY_RELEASE_LEVEL PY_RELEASE_SERIAL ---------- assignee: docs@python components: Documentation messages: 166546 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Improved documentation for C API version info type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15465> _______________________________________

3 9

[issue14123] Doc change re old and new string formatting
by Christine Jones March 4, 2013

March 4, 2013

New submission from Christine Jones <silly.english.knights(a)gmail.com>: Change to this http://docs.python.org/py3k/library/stdtypes.html as suggested by Nick Coghlan here http://www.gossamer-threads.com/lists/python/dev/969817 "The formatting operations described here are modelled on C's printf() syntax. They only support formatting of certain builtin types, and the use of a binary operator means that care may be needed in order to format tuples and dictionaries correctly. As the new string formatting syntax is more powerful, flexible, extensible and handles tuples and dictionaries naturally, it is recommended for new code. However, there are no current plans to deprecate printf-style formatting." ---------- assignee: docs@python components: Documentation messages: 154283 nosy: docs@python, telephonebook priority: normal severity: normal status: open title: Doc change re old and new string formatting _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14123> _______________________________________

8 10

[issue15580] fix True/False/None reST markup
by Chris Jerdonek Feb. 8, 2013

Feb. 8, 2013

New submission from Chris Jerdonek: The Dev Guide says not to markup True, False, and None in the documentation in a way that generates a link (e.g. ":const:`True`") because "they’re fundamental to the language and should be known to any programmer": http://docs.python.org/devguide/documenting.html#documenting Rather, it says to use "``True``" (and similarly for False and None): This issue is to update the documentation to conform to this guidance. While working on the documentation, I noticed many occurrences of ":const:`True`", for example. See here for some examples, where you can see the hyperlinks: http://docs.python.org/dev/library/tarfile.html#tarfile.TarFile.add ---------- assignee: docs@python components: Documentation messages: 167648 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: fix True/False/None reST markup _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________

5 14

[issue15116] remove out-of-date Mac application scripting documentation
by hhas Feb. 2, 2013

Feb. 2, 2013

New submission from hhas <hhas(a)users.sourceforge.net>: 1. The entire '4.6. Application Scripting' section should be deleted from the following Python 2 & 3 pages as appscript (and PyOSA) is no longer developed or supported and its use is not recommended for new projects (http://appscript.sourceforge.net/status.html): http://docs.python.org/using/mac.html#application-scripting http://docs.python.org/release/3.2/using/mac.html#application-scripting http://docs.python.org/dev/using/mac.html#application-scripting 2. The sentence 'For more up-to-date implementation of AppleScript support for Python, see the third-party py-appscript project: <http://pypi.python.org/pypi/appscript/>' should be deleted from the following Python 2 page: http://docs.python.org/library/macosa.html ---------- assignee: docs@python components: Documentation messages: 163282 nosy: docs@python, hhas priority: normal severity: normal status: open title: remove out-of-date Mac application scripting documentation 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/issue15116> _______________________________________

3 4

[issue13048] Handling of paths in first argument of imp.find_module()
by Arfrever Frehtes Taifersar Arahesis Jan. 25, 2013

Jan. 25, 2013

New submission from Arfrever Frehtes Taifersar Arahesis <Arfrever.FTA(a)GMail.Com>: It's undocumented that imp.find_module() supports paths with "/" as the first argument: $ mkdir /tmp/imp_tests $ cd /tmp/imp_tests $ mkdir a $ touch a/b.py $ python3.3 -c 'import imp; print(imp.find_module("a/b"))' (<_io.TextIOWrapper name=4 mode='U' encoding='utf-8'>, 'a/b.py', ('.py', 'U', 1)) ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 144532 nosy: Arfrever, brett.cannon, docs@python, ezio.melotti, ncoghlan priority: normal severity: normal status: open title: Handling of paths in first argument of imp.find_module() versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13048> _______________________________________

2 2

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

Jan. 22, 2013

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

8 17

[issue12103] Documentation of open() does not claim 'e' support in mode string
by Марк Коренберг Jan. 3, 2013

Jan. 3, 2013

New submission from Марк Коренберг <socketpair(a)gmail.com>: open() and friends (like temporaryfile) does not document 'e' letter in second arguement. At least on Linux, it opens file with O_CLOEXEC. Not sure under Windows. Also, there are other interesting letters (man -a fopen), like: c (since glibc 2.3.3) Do not make the open operation, or subsequent read and write operations, thread cancellation points. e (since glibc 2.7) Open the file with the O_CLOEXEC flag. See open(2) for more information. m (since glibc 2.3) Attempt to access the file using mmap(2), rather than I/O system calls (read(2), write(2)). Currently, use of mmap(2) is only attempted for a file opened for reading. x Open the file exclusively (like the O_EXCL flag of open(2)). If the file already exists, fopen() fails, and sets errno to EEXIST. This flag is ignored for fdopen(). ---------- assignee: docs@python components: Documentation messages: 136223 nosy: docs@python, mmarkk priority: normal severity: normal status: open title: Documentation of open() does not claim 'e' support in mode string _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12103> _______________________________________

4 6

[issue14393] Incorporate Guide to Magic Methods?
by Dirkjan Ochtman Jan. 3, 2013

Jan. 3, 2013

New submission from Dirkjan Ochtman <dirkjan(a)ochtman.nl>: Should we perhaps ask if we can include https://github.com/RafeKettler/magicmethods in the official docs? It seems nice (and now ranks higher on Google than the official docs...). ---------- assignee: docs@python components: Documentation messages: 156639 nosy: djc, docs@python priority: normal severity: normal status: open title: Incorporate Guide to Magic Methods? _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14393> _______________________________________

6 6

[issue14870] os.utimensat's method description uses wrong notation
by Hynek Schlawack Dec. 27, 2012

Dec. 27, 2012

New submission from Hynek Schlawack <hs(a)ox.cx>: It says: > os.utimensat(dirfd, path[, atime=(atime_sec, atime_nsec), mtime=(mtime_sec, mtime_nsec), flags=0]) > Updates the timestamps of a file with nanosecond precision. The atime and mtime tuples default to None, which sets those values to the current time. It should be the other way around: atime=None, mtime=None in the signature and explain in the body how they look like. It looks like atime_sec and atime_nsec are some magic constants this way. ---------- assignee: docs@python components: Documentation keywords: easy messages: 161264 nosy: docs@python, eric.araujo, ezio.melotti, georg.brandl, hynek priority: low severity: normal status: open title: os.utimensat's method description uses wrong notation versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14870> _______________________________________

4 4

[issue13424] Add examples for open’s new opener argument
by Éric Araujo Nov. 22, 2012

Nov. 22, 2012

New submission from Éric Araujo <merwok(a)netwok.org>: The new opener argument to open and TextIOWrapper closed two bugs on this tracker: using O_CLOEXEC and replacing the unofficial 'c' mode (O_CREATE). I think it’d be nice to have these as examples (maybe not in the docs of TextIOWrapper which are already huge, but for example in the os docs after the O_* constants). ---------- assignee: docs@python components: Documentation messages: 147840 nosy: docs@python, eric.araujo priority: normal severity: normal status: open title: Add examples for open’s new opener argument versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13424> _______________________________________

6 13

[issue15292] import hook behavior documentation improvement
by Anders Hammarquist Nov. 17, 2012

Nov. 17, 2012

New submission from Anders Hammarquist <iko(a)iko.pp.se>: When testing Eutaxia on PyPy (1.9) I discovered a discrepancy in the path_hooks import hook implementation. In CPython (2.7), if the find_module() method raises ImportError (as imp.find_module() does when it does not find a module in the given path), will cause the search to continue, whereas PyPy would propagate the ImportError. PyPy has now been changed to behave like CPython. The documentation is not entirely clear, but it does not explicitly document the import hook mechanism as eating an ImportError in find_module(). It should probably be made explicit, which ever way it should be. It is not obvious what is the correct behaviour, given the implicit relative imports, where the ImportError simply means that the import hook cannot find the module. Quick testing on CPython 3.3 indicates that it behaves like PyPy did, but as it doesn't do implicit relative imports my test case didn't work as it was. For 3.3, without implicit relative imports, propagating the ImportError feels like the correct behaviour. The attached demonstration needs a file /tmp/test/foo.py that does a top-level import, e.g. "import errno" to demonstrate the discrepancy. ---------- assignee: docs@python components: Documentation files: testimport.py messages: 164998 nosy: docs@python, iko priority: normal severity: normal status: open title: import hook behavior documentation improvement type: behavior versions: Python 2.7 Added file: http://bugs.python.org/file26315/testimport.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15292> _______________________________________

4 6

[issue15677] Gzip/zlib allows for compression level=0
by Sandro Tosi Nov. 11, 2012

Nov. 11, 2012

New submission from Sandro Tosi: As reported at http://mail.python.org/pipermail/docs/2012-August/009837.html gzip/zlib allows for a compression level=0 (that's basically no compression) so the documentation should mention that possibility too. ---------- assignee: docs@python components: Documentation messages: 168332 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: needs patch status: open title: Gzip/zlib allows for compression level=0 versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15677> _______________________________________

5 4

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

Nov. 8, 2012

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

3 3

[issue15148] shutul.which() docstring could be clearer
by Tshepang Lekhonkhobe Nov. 2, 2012

Nov. 2, 2012

New submission from Tshepang Lekhonkhobe <tshepang(a)gmail.com>: I find this a little hard to parse (ignoring the obvious typo and the grammar error): """ Given a file, mode, and a path string, return the path whichs conform to the given mode on the path. """ One other suggestion: wouldn't 'file' read better as 'command'? ---------- assignee: docs@python components: Documentation messages: 163515 nosy: docs@python, hynek, tarek, tshepang priority: normal severity: normal status: open title: shutul.which() docstring could be clearer _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________

6 13

[issue14893] Tutorial: Add function annotation example to function tutorial
by Zachary Ware Nov. 1, 2012

Nov. 1, 2012

New submission from Zachary Ware <zachary.ware(a)gmail.com>: A couple months ago, I had never before heard of function annotations and came across a function that had them (I don't remember where or what it was). I spent a fair bit of time searching fruitlessly to figure out what the heck that "->" in the function definition meant. Then finally, a week or two ago, I came across a mention of pep 3107 and function annotations, and figured out what it was that confused me so thoroughly. In an effort to save others from the same confusion, I've put together a small subsection to add to the tutorial about function definition. The text I'm proposing to add is as follows: """ :ref:`Function annotations <function>` are completely optional, arbitrary metadata information about user-defined functions. Python itself currently does not use annotations for anything, so this section is just for familiarity with the syntax. Annotations are stored in the :attr:`__annotations__` attribute of the function as a dictionary and have no effect on any other part of the function. Parameter annotations are defined by a colon after the parameter name, followed by an expression evaluating to the value of the annotation. Return annotations are defined by a literal ``->``, followed by an expression, between the parameter list and the colon denoting the end of the :keyword:`def` statement. The following example has a positional argument, a keyword argument, and the return value annotated with nonsense:: >>> def f(ham: 42, eggs: int = 'spam') -> "Nothing to see here": ... print("Annotations:", f.__annotations__) # print the function's own annotations ... print("Arguments:", ham, eggs) ... >>> f('wonderful') Annotations: {'eggs': <class 'int'>, 'return': 'Nothing to see here', 'ham': 42} Arguments: wonderful spam """ I'd also like to see a link for "->" in the index, either to this note or to the relevant paragraph of compound_stmts.rst or both. The attached patch attempts to add such a link to this section, but I'm not certain that it's done properly. Thanks :) ---------- assignee: docs@python components: Documentation files: annotations_tutorial.patch keywords: patch messages: 161451 nosy: docs@python, zach.ware priority: normal severity: normal status: open title: Tutorial: Add function annotation example to function tutorial type: enhancement versions: Python 3.2, Python 3.3 Added file: http://bugs.python.org/file25684/annotations_tutorial.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14893> _______________________________________

6 9

[issue14570] Document json "sort_keys" parameter properly
by Nick Coghlan Oct. 28, 2012

Oct. 28, 2012

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: The json "sort_keys" parameter is actually supported as an argument to dump() and dumps() (and is used that way in the examples), but is only documented as an argument to the JSONEncoder constructor. ---------- assignee: docs@python components: Documentation keywords: easy messages: 158194 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Document json "sort_keys" parameter properly type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14570> _______________________________________

7 16

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

Oct. 27, 2012

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

5 9

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

Oct. 26, 2012

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

3 4

[issue11160] ZipFile.comment expects bytes
by Xuanji Li Oct. 25, 2012

Oct. 25, 2012

New submission from Xuanji Li <xuanji(a)gmail.com>: The documentation for zipfile describes ZipFile.comment as "The comment text associated with the ZIP file." From reading this I expect that setting it to a string is ok; however ZipFile.comment must actually be set to bytes (or a bytes-like object, I am not very sure). This may also unexpectedly affect old code because I saw one patch on the bug tracker that was written just last year that set ZipFile.comment to a string. IMO there are 2 ways to fix: 1) Change docs to mention that ZipFile.comment only accepts bytes 2) Patch zipfile.py to accept string and try to convert, throwing an error if the conversion fails ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 128217 nosy: docs@python, haypo, xuanji priority: normal severity: normal status: open title: ZipFile.comment expects bytes versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11160> _______________________________________

4 4

[issue13498] os.makedirs exist_ok documentation is incorrect, as is some of the behavior
by R. David Murray Oct. 23, 2012

Oct. 23, 2012

New submission from R. David Murray <rdmurray(a)bitdance.com>: The documentation for os.makedirs says: If the target directory with the same mode as specified already exists, raises an OSError exception if exist_ok is False, otherwise no exception is raised. This is not correct. If the file exists but the mode is different than that specified (or defaulted) after applying the umask, then an error is raised regardless of the value of exist_ok. The above wording also implies that if the directory exists but has a different mode, that the mode will be changed. Again, this is not what the code does. It's not clear how useful this raise behavior is, but reading the original issue that added this option it is clearly intentional. The documented behavior does seem useful, but if it actually reset the mode that would be a fairly significant behavior change, and would not be a good idea if the user had not specified a mode. However, at the very least exists_ok should not raise if no mode was specified in the call. The error message raised is also wrong in this case, since it says that the error is that the file already exists when we've said that that is OK. A custom error message for this case would be better. ---------- assignee: docs@python components: Documentation, Library (Lib) keywords: easy messages: 148564 nosy: docs@python, r.david.murray priority: normal severity: normal stage: needs patch status: open title: os.makedirs exist_ok documentation is incorrect, as is some of the behavior type: behavior versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13498> _______________________________________

9 22

[issue14394] missing links on performance claims of cdecimal
by Tshepang Lekhonkhobe Oct. 21, 2012

Oct. 21, 2012

New submission from Tshepang Lekhonkhobe <tshepang(a)gmail.com>: Looking at "What's New" section for cdecimal [1], I see this claim: "Performance gains range from 12x for database applications to 80x for numerically intensive applications..." But there's no link on the benchmark code. [1] http://hg.python.org/cpython/file/9ceac471bd8c/Doc/whatsnew/3.3.rst#l599 ---------- assignee: docs@python components: Documentation messages: 156640 nosy: docs@python, tshepang priority: normal severity: normal status: open title: missing links on performance claims of cdecimal versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14394> _______________________________________

6 8

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

Oct. 20, 2012

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

5 9

[issue15586] Provide some examples for usage of ElementTree methods/attributes
by Sarbjit singh Oct. 15, 2012

Oct. 15, 2012

New submission from Sarbjit singh: Please provide some basic usage examples for ElementTree module documentation. While parsing an xml, most common scenarios will be reading elements from xml, modifying elements, removal of elements. Though there are few examples given for modification of xml element. But if you look from beginners learning point of view, its very hard to just get any idea from the example that is currently provided. There is lot of text there, but what would be more helpful is some small examples for each function so that user can quickly understand its usage there only. I myself is learning Python, but in order to start using this module, i had to search lot of articles on internet on usage of this module. If we could have provided some basic use cases in Python doc itself, user would not have to rely on external sources for learning its usage. Some Basic Scenarios: 1) Parsing an xml and finding some elements of xml 2) deletion of an element from an xml and writing back 3) Modification of an xml element 4) Usage of XPath queries (some basic usage) ---------- assignee: docs@python components: Documentation messages: 167670 nosy: Sarbjit.singh, docs@python, eli.bendersky priority: normal severity: normal status: open title: Provide some examples for usage of ElementTree methods/attributes type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________

7 27

[issue12947] Examples in library/doctest.html lack the flags
by Éric Araujo Oct. 11, 2012

Oct. 11, 2012

New submission from Éric Araujo <merwok(a)netwok.org>: The docs for the doctest module contains examples that use doctest flags to control behavior, but the HTML version does not contain the flags, making the examples useless. I don’t know if this is a bug with the HTML builder or something we can fix in markup. ---------- assignee: docs@python components: Documentation messages: 143775 nosy: docs@python, eric.araujo, georg.brandl priority: normal severity: normal status: open title: Examples in library/doctest.html lack the flags versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12947> _______________________________________

10 35

[issue11710] Landing pages in docs for standard library packages
by Nick Coghlan Oct. 6, 2012

Oct. 6, 2012

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: http://docs.python.org/py3k/urllib errors out rather than returning an index page for the modules that are part of the urllib package. This index page could also link to the HOWTO at http://docs.python.org/py3k/howto/urllib2.html The following packages have the same problem: xml, http, xmlrpc, concurrent These ones look OK: logging, curses, html, tkinter These index pages don't necessarily need to be linked from the contents page, but they should exist so that manually typed URLs for these packages do something useful rather than erroring out with a 404. ---------- assignee: docs@python components: Documentation messages: 132481 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Landing pages in docs for standard library packages versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11710> _______________________________________

6 9

[issue14503] docs:Code not highlighted
by Ramchandra Apte Sept. 30, 2012

Sept. 30, 2012

New submission from Ramchandra Apte <maniandram01(a)gmail.com>: In http://docs.python.org/dev/whatsnew/3.3.html#pep-380-syntax-for-delegating-… , two code samples ---------- assignee: docs@python components: Documentation messages: 157551 nosy: docs@python, ramchandra.apte priority: normal severity: normal status: open title: docs:Code not highlighted _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14503> _______________________________________

7 11

[issue15821] Improve docs for PyMemoryView_FromBuffer()
by Stefan Krah Sept. 28, 2012

Sept. 28, 2012

New submission from Stefan Krah: People are using PyMemoryView_FromBuffer() to create and return permanent memoryviews from buffers that are allocated on the stack. See: http://stackoverflow.com/questions/8123121/how-to-get-back-a-valid-object-f… The docs should perhaps warn against this. ---------- assignee: docs@python components: Documentation messages: 169443 nosy: belopolsky, docs@python, ncoghlan, pitrou, skrah priority: normal severity: normal status: open title: Improve docs for PyMemoryView_FromBuffer() type: enhancement versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15821> _______________________________________

3 20

[issue15593] urlparse.parse_qs documentation wrong re: urlencode
by Rob Kinyon Sept. 28, 2012

Sept. 28, 2012

New submission from Rob Kinyon: This may appear to be a duplicate of http://bugs.python.org/issue12390 and http://bugs.python.org/issue833405, but it's not. The documentation of urlparse.parse_qs() should state that in order for urllib.urlencode to properly reverse its output, the doseq parameter must be set to True. Please amend the documentation to make this very clear. Ideally, the documentation of urlencode() would also make it clear that doseq=True is required if the output is from parse_qs(). ---------- assignee: docs@python components: Documentation messages: 167707 nosy: Rob.Kinyon, docs@python priority: normal severity: normal status: open title: urlparse.parse_qs documentation wrong re: urlencode versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15593> _______________________________________

5 4

[issue10665] Update and expand unicodedata module documentation
by Alexander Belopolsky Sept. 26, 2012

Sept. 26, 2012

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: unicodedata module documentation has not been updated to reflect transition to 6.0. Attached patch fixes the version and unicode.org links and starts making the documentation rely less on the unicode.org pages for basic understanding of the provided functionality. I am posting work in progress to solicit feedback on how much of the Unicode Standard information we would want to present here. On of the goals of this patch is to provide a standard reference that can be used throughout the library manual for basic Unicode concepts without sending the reader over to unicode.org. ---------- assignee: docs@python components: Documentation files: unicodedata-doc.diff keywords: patch messages: 123700 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: Update and expand unicodedata module documentation versions: Python 3.2 Added file: http://bugs.python.org/file19990/unicodedata-doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10665> _______________________________________

6 25

[issue14167] document return statement in finally blocks
by Yury Selivanov Sept. 24, 2012

Sept. 24, 2012

New submission from Yury Selivanov <yselivanov(a)gmail.com>: I think that the documentation should put more emphasis on the `return` statement in a `finally` block. Example: def test(): try: 1/0 finally: return 10 >>> test() 10 I think we need to add a warning, or at least a note, that 'return' masks exceptions, if any occurred. ---------- assignee: docs@python components: Documentation messages: 154697 nosy: Yury.Selivanov, docs@python, georg.brandl, rhettinger priority: normal severity: normal status: open title: document return statement in finally blocks type: enhancement versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14167> _______________________________________

5 17

[issue15548] Mention all new os functions in What's New in Python 3.3
by STINNER Victor Sept. 20, 2012

Sept. 20, 2012

New submission from STINNER Victor: The os module has a lot of new functions in Python 3.3. It looks like only a few are documented in What's New in Python 3.3. Examples : truncate(), ftruncate() and sync() are not mentionned. Does Sphinx have a function to list of new functions added to Python 3.3? At least to check that the What's New in Python 3.3 is complete. I would like to have the full list to check that new functions are consistent. See for example the issue #15547. ---------- assignee: docs@python components: Documentation messages: 167315 nosy: docs@python, georg.brandl, haypo, larry, rhettinger priority: normal severity: normal status: open title: Mention all new os functions in What's New in Python 3.3 versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15548> _______________________________________

5 5

[issue15796] Fix readline() docstrings
by Serhiy Storchaka Sept. 18, 2012

Sept. 18, 2012

New submission from Serhiy Storchaka: Here is a patch that escapes '\n' in readline() docstrings. ---------- assignee: docs@python components: Documentation files: escape_nl.patch keywords: patch messages: 169235 nosy: docs@python, storchaka priority: normal severity: normal status: open title: Fix readline() docstrings versions: Python 2.7, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file27021/escape_nl.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15796> _______________________________________

3 4

[issue15789] mention shell-like parts of the std lib in the subprocess docs
by Chris Rebert Sept. 15, 2012

Sept. 15, 2012

New submission from Chris Rebert: To further dissuade people from using subprocess.Popen's shell=True option unnecessarily, this patch points out that some common shell features are also available directly in Python via certain modules & functions. ---------- assignee: docs@python components: Documentation files: subprocess.rst.patch keywords: patch messages: 169188 nosy: cvrebert, docs@python priority: normal severity: normal status: open title: mention shell-like parts of the std lib in the subprocess docs versions: Python 2.7, Python 3.3, Python 3.4 Added file: http://bugs.python.org/file27013/subprocess.rst.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15789> _______________________________________

5 6

[issue15831] comma after leading optional argument is after bracket in docs
by Chris Jerdonek Sept. 15, 2012

Sept. 15, 2012

New submission from Chris Jerdonek: >From docs(a)python.org: """ In a number of places we find documentation with optional leading arguments where the meta-notation (square brackets) are in the wrong place. For example, for range, the standard doc heading says range([start], stop [, step]) # The comma after start should be inside the square bracket, not outside. The same error occurs with docs for print, and for slice, for random.randrange and for random.seed, etc, etc. This seems a consistent bug whenever a function or method takes an optional first argument, and it looks like it might have been put there by some tool that generates the docs. I use Python 3 - perhaps there was once a time when one had to supply the comma if one omitted the first argument? In Python 3 it gives errors if one follows the documentation carefully and uses the comma. """" (or see http://mail.python.org/pipermail/docs/2012-August/010051.html ) ---------- assignee: docs@python components: Documentation messages: 169547 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: comma after leading optional argument is after bracket in docs type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15831> _______________________________________

5 33

[issue15437] Merge Doc/ACKS and Misc/ACKS
by Chris Jerdonek Sept. 13, 2012

Sept. 13, 2012

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: This issue is to merge the Doc/ACKS and Misc/ACKS files as discussed here: http://mail.python.org/pipermail/python-dev/2012-July/121096.html ---------- assignee: docs@python components: Documentation keywords: easy messages: 166247 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: Merge Doc/ACKS and Misc/ACKS _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15437> _______________________________________

8 25

[issue15439] Include Misc/ACKS names into the documentation
by Chris Jerdonek Sept. 13, 2012

Sept. 13, 2012

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: This issue is to include the names in Misc/ACKS into the documentation -- in place of the names from Doc/ACKS.txt. This was mentioned in the discussion for issue 15437, which is to add the names from Doc/ACKS.txt into Misc/ACKS. This issue should be done shortly after issue 15437. The current issue can include (1) converting Misc/ACKS into rst format, (2) deleting DOC/ACKS.txt (after confirming that any changes since issue 15437 are reflected in Misc/ACKS), and (3) resolving the intros in the two files with about.rst's surrounding text so that the text makes sense when included into the main documentation. Should Guido's note of acknowledgment in Misc/ACKS be included as is? And should a new "Python Acknowledgments" section be added to the docs, or is it okay for this more general acknowledgment to be included in the section called "About these documents"? If the former, the "About these documents" section could link to the more general "Python Acknowledgments" section to reference documentation contributors. ---------- assignee: docs@python components: Documentation keywords: easy messages: 166279 nosy: cjerdonek, docs@python, eric.araujo, ezio.melotti, georg.brandl, jcea, pitrou priority: normal severity: normal stage: needs patch status: open title: Include Misc/ACKS names into the documentation _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15439> _______________________________________

10 20

[issue14617] confusing docs with regard to __hash__
by Ethan Furman Sept. 12, 2012

Sept. 12, 2012

New submission from Ethan Furman <ethan(a)stoneleaf.us>: >From http://docs.python.org/py3k/reference/datamodel.html#object.__hash__ ----------------------------------------------------------------------- Classes which inherit a __hash__() method from a parent class but change the meaning of __eq__() such that the hash value returned is no longer appropriate (e.g. by switching to a value-based concept of equality instead of the default identity based equality) can explicitly flag themselves as being unhashable by setting __hash__ = None in the class definition. Doing so means that not only will instances of the class raise an appropriate TypeError when a program attempts to retrieve their hash value, but they will also be correctly identified as unhashable when checking isinstance(obj, collections.Hashable) (unlike classes which define their own __hash__() to explicitly raise TypeError). If a class that overrides __eq__() needs to retain the implementation of __hash__() from a parent class, the interpreter must be told this explicitly by setting __hash__ = <ParentClass>.__hash__. Otherwise the inheritance of __hash__() will be blocked, just as if __hash__ had been explicitly set to None. ----------------------------------------------------------------------- The first paragraph says the user has to change __hash__ if it's different because of changes to __eq__, the second paragraph says __hash__ is automatically removed if __eq__ is changed; the second paragraph reflects reality. Proposed change: ----------------------------------------------------------------------- Classes which change the meaning of __eq__() (thus losing automatic delegation to the parent class' __hash__) can explicitly flag themselves as being unhashable by setting __hash__ = None in the class definition (which is otherwise done implicity). Having __hash__ set to None, either explicitly or implicitly, means that not only will instances of the class raise an appropriate TypeError when a program attempts to retrieve their hash value, but they will also be correctly identified as unhashable when checking isinstance(obj, collections.Hashable) (unlike classes which define their own __hash__() to explicitly raise TypeError). If a class that overrides __eq__() needs to retain the implementation of __hash__() from a parent class, the interpreter must be told this explicitly by setting __hash__ = <ParentClass>.__hash__. ----------------------------------------------------------------------- Patch attached. ---------- assignee: docs@python components: Documentation, Interpreter Core files: __hash__.diff keywords: patch messages: 158644 nosy: docs@python, stoneleaf priority: normal severity: normal status: open title: confusing docs with regard to __hash__ type: behavior versions: Python 3.1, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file25261/__hash__.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14617> _______________________________________

8 17

[issue15724] Add "versionchanged" to memoryview docs
by Stefan Krah Sept. 9, 2012

Sept. 9, 2012

New submission from Stefan Krah: There are a couple of places in the memoryview docs that still need a "versionchanged" tag. Other places might need explanations what exactly has changed. ---------- assignee: docs@python components: Documentation messages: 168563 nosy: docs@python, skrah priority: normal severity: normal stage: needs patch status: open title: Add "versionchanged" to memoryview docs type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15724> _______________________________________

3 6

[issue15520] Document datetime.timestamp() in 3.3 What's New
by Dirkjan Ochtman Sept. 7, 2012

Sept. 7, 2012

New submission from Dirkjan Ochtman: It seems nice if datetime.timestamp() would be mentioned in the What's New. Does that seem acceptable? I'm happy to whip up a patch. ---------- assignee: docs@python components: Documentation messages: 167096 nosy: djc, docs@python priority: normal severity: normal status: open title: Document datetime.timestamp() in 3.3 What's New versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15520> _______________________________________

4 3

[issue14783] Make int() and str() docstrings correct
by Terry J. Reedy Aug. 31, 2012

Aug. 31, 2012

Terry J. Reedy added the comment: The large issue is documenting complex signatures that do not really fit in any of the standard one-line patterns. I was initially puzzled by Raymond describing the 3.3 line as 'confusing', but putting on 'newbie glasses' I see now that correctly parsing int([number | string[, base]]) requires knowing that '[, option]' binds tighter than '|'. Since ',' normally has the lowest binding priority, someone who does not know the signature already (ie, a target audience member) could parse it as int([ (number | string) [, base]]) rather than as intended: int([number | (string[, base]) ]) So I agree that the two stacked lines in the doc patch are clearer. However, this issue is about the docstring. Leave it incorrect? Change it to the hard-to-parse one liner? Change it to a two-line signature also? I noticed this issue while working on IDLE tooltips, using int as a test case. They currently use only the first line of the docstring, but I have decided that they should get more when needed for C functions. (For Python functions, tooltips use inspect for the actual signature and the first docstring line only for a description.) The first line of the str docstring is also incorrect in that the optional parameters are only valid for first arguments that are strings. str(string[, encoding[, errors]]) -> str It needs either a '|' construction like int or another line: str(object) I prefer the latter. I revised the title to add str.__doc__ to the issue. While we are at it, how about range(stop) range(start, stop, [step]) instead of the current doc and docstring signature range([start,] stop[, step]) ? The current docstring is inaccurate and confusing to some. (How can there be an optional first arg and required second ? -- Answer: there can't.) The technically accurate signature is range(start_or_stop[, stop[, step]]) but that has been rejected as confusing. The bytes and bytearrays docstrings have 5 signature lines!. (The manual gives just one which does not quite cover all cases.) So (a) there is precedent for multiple signatures in docstrings and (b) tooltips already need to grab multiple signature lines. So I think int and str (and maybe range) should use a couple of clear lines. If the new inspect.signature function were to give signatures for C functions, there would be no problem for tooltips, but it does not. (Can signature objects even handle multiple (or type-dependent) signatures?) ---------- nosy: +georg.brandl title: Update int() docstring from manual -> Make int() and str() docstrings correct _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14783> _______________________________________

1 0

[issue14783] Update int() docstring from manual
by Ezio Melotti Aug. 31, 2012

Aug. 31, 2012

Ezio Melotti added the comment: Here's a patch for the signature. ---------- assignee: -> ezio.melotti keywords: +patch stage: needs patch -> commit review Added file: http://bugs.python.org/file27075/issue14783.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14783> _______________________________________

1 0

[issue14783] Update int() docstring from manual
by Éric Araujo Aug. 31, 2012

Aug. 31, 2012

Éric Araujo added the comment: +1! This notation helps clearing up how int, str and other constructors work. ---------- nosy: +eric.araujo _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14783> _______________________________________

1 0

Python 3 documentation bugs?
by Peter Wentworth Aug. 31, 2012

Aug. 31, 2012

In a number of places we find documentation with optional leading arguments where the meta-notation (square brackets) are in the wrong place. For example, for range, the standard doc heading says range([start], stop [, step]) # The comma after start should be inside the square bracket, not outside. The same error occurs with docs for print, and for slice, for random.randrange and for random.seed, etc, etc. This seems a consistent bug whenever a function or method takes an optional first argument, and it looks like it might have been put there by some tool that generates the docs. I use Python 3 - perhaps there was once a time when one had to supply the comma if one omitted the first argument? In Python 3 it gives errors if one follows the documentation carefully and uses the comma. Thanks Peter

2 1

comma after leading optional argument
by Chris Jerdonek Aug. 31, 2012

Aug. 31, 2012

Date: Thu, 30 Aug 2012 16:37:03 +0000 From: Peter Wentworth <p.wentworth(a)ru.ac.za> Subject: [docs] Python 3 documentation bugs? > In a number of places we find documentation with optional leading arguments where the meta-notation (square brackets) are in the wrong place. For example, for range, the standard doc heading says > > range([start], stop [, step]) # The comma after start should be inside the square bracket, not outside. Thanks for the report. I filed an issue to track this here: http://bugs.python.org/issue15831 --Chris

1 0

Character Encoding corner case
by Phillip Aug. 31, 2012

Aug. 31, 2012

The python.org server seems to be serving this page: http://docs.python.org/library/curses.ascii.html using the "us-ascii" character encoding in the headers... which causes things like the dash in the page title, and the paragraph mark "link to this section" link in the header, to display incorrectly (at least in Firefox and Chrome, the browsers I have available to test it in). It doesn't appear to be happening on any other pages... I think the web server is just guessing the content type based on the filename. -- Phlip <link rel="signature" type="text/hilarious" href="/funnysig.txt" />

3 2

UserWarning: cookielib bug!
by Tomáš Beluský Aug. 31, 2012

Aug. 31, 2012

Hi, I found this bug: /usr/local/lib/python2.7/cookielib.py:1584: UserWarning: cookielib bug! Traceback (most recent call last): File "/usr/local/lib/python2.7/cookielib.py", line 1582, in make_cookies parse_ns_headers(ns_hdrs), request) File "/usr/local/lib/python2.7/cookielib.py", line 485, in parse_ns_headers v = http2time(_strip_quotes(v)) # None if invalid File "/usr/local/lib/python2.7/cookielib.py", line 266, in http2time return _str2time(day, mon, yr, hr, min, sec, tz) File "/usr/local/lib/python2.7/cookielib.py", line 176, in _str2time t = _timegm((yr, mon, day, hr, min, sec, tz)) File "/usr/local/lib/python2.7/cookielib.py", line 76, in _timegm return timegm(tt) File "/usr/local/lib/python2.7/calendar.py", line 608, in timegm days = datetime.date(year, month, 1).toordinal() - _EPOCH_ORD + day - 1 ValueError: year is out of range _warn_unhandled_exception()

2 1

'print'-syntax error
by L P Aug. 31, 2012

Aug. 31, 2012

Dear Community! I have a problem with my python interpreter, as the subject shows, it's about the ,print'-command. It's the following: >>> print "Hello" SyntaxError: invalid syntax After telling me there's an error, it points at the second quote. I've no idea why this happens all the time. I already copied source code from a python ebook, but it still doesn't work. And that error occurs whilst using the GUI and the command line. I'm using Python 3.2 on Windows (64-bit). Please help me out as soon as possible, as I finally want to begin learning python J Thanks in advance.

2 1

[issue15829] Threading Lock - Wrong Exception Name
by R. David Murray Aug. 31, 2012

Aug. 31, 2012

R. David Murray added the comment: Please see Issue 14502. The docs probably do need clarification, but it must be done carefully. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15829> _______________________________________

1 0

[issue15829] Threading Lock - Wrong Exception Name
by Mike Hoy Aug. 31, 2012

Aug. 31, 2012

Mike Hoy added the comment: 2.7 patch. ---------- Added file: http://bugs.python.org/file27072/15829-thread-errror2.7.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15829> _______________________________________

1 0

[issue15829] Threading Lock - Wrong Exception Name
by Mike Hoy Aug. 31, 2012

Aug. 31, 2012

Mike Hoy added the comment: 3.3 patch ---------- keywords: +patch Added file: http://bugs.python.org/file27071/15829-thread-errror3.3.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15829> _______________________________________

1 0

[issue15829] Threading Lock - Wrong Exception Name
by Andrew Svetlov Aug. 31, 2012

Aug. 31, 2012

Andrew Svetlov added the comment: Sounds good. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15829> _______________________________________

1 0

[issue15829] Threading Lock - Wrong Exception Name
by Mike Hoy Aug. 31, 2012

Aug. 31, 2012

Mike Hoy added the comment: I discussed this in IRC and got the following information from Ezio: < Taggnostr> the doc fix can go in 2.7/3.3, the code fix in 3.4 Plan is to put the definition for ThreadError in threading.rst for both 2.7 and 3.3 ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15829> _______________________________________

1 0

Description of str.replace
by Martin Vlach Aug. 31, 2012

Aug. 31, 2012

is ambiguous. I described the problem here: http://diigo.com/0snx7 Regards Huge

1 0

[issue15825] Typo in OrderedDict docs
by ThiefMaster Aug. 31, 2012

Aug. 31, 2012

New submission from ThiefMaster: "It is also straight-forward to create an ordered dictionary variant that the remembers the order the keys were last inserted." The first "the" doesn't belong there. ---------- assignee: docs@python components: Documentation messages: 169493 nosy: ThiefMaster, docs@python priority: normal severity: normal status: open title: Typo in OrderedDict docs versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15825> _______________________________________

4 4

[issue15829] Threading Lock - Wrong Exception Name
by Andrew Svetlov Aug. 31, 2012

Aug. 31, 2012

Andrew Svetlov added the comment: ValueError can be referenced by :exc:`ValueError`. For ThreadError you can add section for describing this exception type like: .. exception:: ThreadError Raised when lock object cannot be acquired or released. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15829> _______________________________________

1 0

[issue15829] Threading Lock - Wrong Exception Name
by Andrew Svetlov Aug. 31, 2012

Aug. 31, 2012

Changes by Andrew Svetlov <andrew.svetlov(a)gmail.com>: ---------- Removed message: http://bugs.python.org/msg169518 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15829> _______________________________________

1 0

[issue15829] Threading Lock - Wrong Exception Name
by Mike Hoy Aug. 31, 2012

Aug. 31, 2012

Mike Hoy added the comment: >>I think RuntimeError should be replaced by ThreadingError for _RLock >>and Condition implementations as well as docs need to be updated. >> >>Also I think this patch should be applied to 3.4 only, it is >>enchacement, not bugfix. >>About fixing docs for 2.7-3.3: I see nothing wrong if current >>inconsistency will be documented, perhaps as *warning* or *note* block. I should warn that ThreadError or `ThreadError` has no link. I've tried to find a place in the docs I could link to but haven't yet. `ValueError` does have a link. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15829> _______________________________________

1 0

[issue15829] Threading Lock - Wrong Exception Name
by Mike Hoy Aug. 31, 2012

Aug. 31, 2012

Mike Hoy added the comment: >>I think RuntimeError should be replaced by ThreadingError for _RLock >>and Condition implementations as well as docs need to be updated. >> >>Also I think this patch should be applied to 3.4 only, it is >>enchacement, not bugfix. >>About fixing docs for 2.7-3.3: I see nothing wrong if current >>inconsistency will be documented, perhaps as *warning* or *note* block. I should warn that ThreadError or `ThreadError` has no link. I've tried to find a place in the docs I could link to but haven't yet. `ValueError` does have a link. ---------- type: enhancement -> _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15829> _______________________________________

1 0

[issue15829] Threading Lock - Wrong Exception Name
by Andrew Svetlov Aug. 31, 2012

Aug. 31, 2012

Andrew Svetlov added the comment: The problem is: threading.Lock raises ThreadingError (which is subclass of RuntimeError for 3.3 but not for 3.2), but threading.Condition raises RuntimeError for the same reason. RLock behavior is even worse: it raises ThreadingError if C accelerator is available in _thread and RuntimeError otherwise. I think RuntimeError should be replaced by ThreadingError for _RLock and Condition implementations as well as docs need to be updated. Also I think this patch should be applied to 3.4 only, it is enchacement, not bugfix. About fixing docs for 2.7-3.3: I see nothing wrong if current inconsistency will be documented, perhaps as *warning* or *note* block. ---------- components: +Library (Lib) nosy: +asvetlov type: -> enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15829> _______________________________________

1 0

[issue15829] Threading Lock - Wrong Exception Name
by Mike Hoy Aug. 31, 2012

Aug. 31, 2012

Mike Hoy added the comment: Working on a patch now unless there are objections to the OP. ---------- nosy: +docs@python _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15829> _______________________________________

1 0

threading Lock - wrong exception name
by Slawomir Kuszczynski Aug. 30, 2012

Aug. 30, 2012

Hi I found a bug in python docs which can be accessed at links: http://docs.python.org/library/threading.html#lock-objects http://docs.python.org/py3k/library/threading.html#lock-objects Bug is in second paragraph describing threading.Lock. I found that statement: "If an attempt is made to release an unlocked lock, a RuntimeError<http://docs.python.org/library/exceptions.html#exceptions.RuntimeError>will be raised." Which is not true, name of exception is wrong it should be (and it relay is) ThreadError (from threading module) Could someone fix it? -- Br, Slawomir Kuszczynski

1 0

[issue15807] Bogus versionchanged note in logging.handlers.MemoryHandler doc
by Gunnlaugur Thor Briem Aug. 29, 2012

Aug. 29, 2012

New submission from Gunnlaugur Thor Briem: In logging.handlers.MemoryHandler documentation: “Changed in version 2.6: credentials was added.” There's no `credentials` anywhere nearby, and at first glance I can't see anything new in `MemoryHandler` when this was introduced. Presumably the `.. versionchanged::` note just landed there by copy-paste error in 6fb033af9310. ---------- assignee: docs@python components: Documentation messages: 169360 nosy: docs@python, gthb priority: normal severity: normal status: open title: Bogus versionchanged note in logging.handlers.MemoryHandler doc type: enhancement versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15807> _______________________________________

3 2

multiprocessing documentation of Process.exitcode
by Josh Kupershmidt Aug. 29, 2012

Aug. 29, 2012

Hi all, The documentation for the multiprocessing module claims: | Note that the start(), join(), is_alive() and exit_code methods | should only be called by the process that created the process object. Two problems with this description: 1. "exit_code" should be spelled "exitcode" 2. exitcode is an attribute of the Process class, not a method as claimed, since the underlying method is decorated with @property Also, aside from the above documentation issues, if it is true that it's not safe to query the exitcode from a separate process, should the exitcode property method include a check like so: assert self._parent_pid == os.getpid(), 'can only test a child process' since start(), join(), and is_alive() all perform this check? Josh

1 0

[issue14783] Update int() docstring from manual
by Ezio Melotti Aug. 28, 2012

Aug. 28, 2012

Ezio Melotti added the comment: .. function:: int(n=0) int(s, base=10) should do the trick. +1 on using this instead of int([number | string[, base]]) ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14783> _______________________________________

1 0

[issue14042] json.dumps() documentation is slightly incorrect.
by Petri Lehtinen Aug. 28, 2012

Aug. 28, 2012

Petri Lehtinen added the comment: This is a documentation bug for 2.7. Setting as duplicate of #13769. ---------- nosy: +petri.lehtinen resolution: -> duplicate stage: needs patch -> committed/rejected status: open -> closed superseder: -> json.dump(ensure_ascii=False) return str instead of unicode versions: -Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14042> _______________________________________

1 0

[issue14880] csv.reader and .writer use wrong kwargs notation in 2.7 docs
by Hynek Schlawack Aug. 28, 2012

Aug. 28, 2012

New submission from Hynek Schlawack <hs(a)ox.cx>: It says > csv.reader(csvfile[, dialect='excel'][, fmtparam]) > csv.writer(csvfile[, dialect='excel'][, fmtparam]) in 2.7. I presume it should be like in 3.x: > csv.reader(csvfile, dialect='excel', **fmtparams) > csv.writer(csvfile, dialect='excel', **fmtparams) Or am I missing something? (I found argument renaming to be too invasive for my default-args-notation ticket #14804) ---------- assignee: docs@python components: Documentation keywords: easy messages: 161332 nosy: docs@python, hynek priority: normal severity: normal status: open title: csv.reader and .writer use wrong kwargs notation in 2.7 docs versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14880> _______________________________________

4 9

[issue11964] Undocumented change to indent param of json.dump in 3.2
by Éric Araujo Aug. 28, 2012

Aug. 28, 2012

New submission from Éric Araujo <merwok(a)netwok.org>: I found out that the indent parameter of json.dump was changed in 3.2: it can be a string as well as an int. The docstring was not updated; the reST doc was, but without a versionchanged directive. This probably applies to the doc and docstring of the classes implementing dump, too, and there may be other half-documented changes. ---------- assignee: docs@python components: Documentation, Library (Lib) keywords: easy messages: 134869 nosy: bob.ippolito, docs@python, eric.araujo, rhettinger priority: normal severity: normal stage: needs patch status: open title: Undocumented change to indent param of json.dump in 3.2 versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11964> _______________________________________

7 14

[issue9694] argparse required arguments displayed under "optional arguments"
by Martin Burger Aug. 28, 2012

Aug. 28, 2012

Changes by Martin Burger <m(a)rtin-burger.net>: ---------- nosy: +mburger _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9694> _______________________________________

1 0

[issue14783] Update int() docstring from manual
by Raymond Hettinger Aug. 28, 2012

Aug. 28, 2012

Raymond Hettinger added the comment: The 3.3 version has the virtue of being accurate and the vice of being confusing. In a way, it has made the docs worse for the average user of common cases. Is there a way to stack the alternative signatures rather than mush the various used into a single pile of mush? int(x=0) --> integer coercion int(str, base=10) --> integer converted from string in a given base ---------- nosy: +rhettinger _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14783> _______________________________________

1 0

[issue9650] format codes in time.strptime docstrings
by Chris Rebert Aug. 28, 2012

Aug. 28, 2012

Chris Rebert added the comment: +1 on including am/pm-related codes. Blame us backwards, non-metric Americans. Sounds GTM otherwise. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9650> _______________________________________

1 0

[issue15790] Python 3.3.0rc1 release notes claims PEP-405 support, yet pysetup is not in the package (needs more usage documentation, to get pip working)
by Pas Aug. 27, 2012

Aug. 27, 2012

New submission from Pas: Python 3.3.0rc1 release notes ( http://python.org/download/releases/3.3.0/ ) claims PEP-405 support, yet pysetup is not in the tarball. (After reading through mailing lists and bugs it's clear that the move to "packaging" module got pulled, so it's still just distutils in there.) There is no documentation on how to get a pyvenv (or virtualenv, or any other virtual enviroment solution) built venv to gain setuptools/pip support. ---------- assignee: docs@python components: Documentation messages: 169194 nosy: docs@python, pas priority: normal severity: normal status: open title: Python 3.3.0rc1 release notes claims PEP-405 support, yet pysetup is not in the package (needs more usage documentation, to get pip working) versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15790> _______________________________________

3 5

[issue12403] Mention sys.displayhook in code module docs and the compile builtin docs
by Aaron Iles Aug. 27, 2012

Aug. 27, 2012

Aaron Iles added the comment: I've submitted a patch which adds a section to the code module's documentation on overriding console output. It attempts to catalogue when sys.stderr, sys.excepthook and sys.displayhook are used to print console output. ---------- keywords: +patch nosy: +aliles Added file: http://bugs.python.org/file27014/p1346072775.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12403> _______________________________________

1 0

[issue9650] format codes in time.strptime docstrings
by Alexander Belopolsky Aug. 27, 2012

Aug. 27, 2012

Alexander Belopolsky added the comment: I would like to add my +1 to this issue. I suggest adding something like this: """ Commonly used format codes: %Y Year with century as a decimal number. %m Month as a decimal number [01,12]. %d Day of the month as a decimal number [01,31]. %H Hour (24-hour clock) as a decimal number [00,23]. %M Minute as a decimal number [00,59]. %S Second as a decimal number [00,61]. %z Time zone offset from UTC. %a Locale’s abbreviated weekday name. %A Locale’s full weekday name. %b Locale’s abbreviated month name. %B Locale’s full month name. %c Locale’s appropriate date and time representation. Other codes may be available on your platform. See documentation for the C library strftime function. """ This is a subjective selection in a subjective order of importance, so some bikesheding is welcome. My choice was motivated by the assumption that most commonly used are the codes required to form RFC 3339 timestamps. I deliberately omitted deprecated %y code and the %Z code that produces non-standardized TZ names. I can be persuaded to add 12 hour clock codes. ---------- assignee: docs@python -> belopolsky _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9650> _______________________________________

1 0

[issue14783] Update int() docstring from manual
by Chris Rebert Aug. 27, 2012

Aug. 27, 2012

Changes by Chris Rebert <pybugs(a)rebertia.com>: ---------- nosy: +cvrebert _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14783> _______________________________________

1 0

[issue9650] format codes in time.strptime docstrings
by Chris Rebert Aug. 27, 2012

Aug. 27, 2012

Changes by Chris Rebert <pybugs(a)rebertia.com>: ---------- nosy: +cvrebert _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9650> _______________________________________

1 0

[issue7186] Document specialness of __doc__, and possibly other "special" attributes
by Chris Rebert Aug. 27, 2012

Aug. 27, 2012

Changes by Chris Rebert <pybugs(a)rebertia.com>: ---------- nosy: +cvrebert _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue7186> _______________________________________

1 0

[issue15788] cross-refs in the subprocess.Popen.std{in, out, err} warning box aren't linked
by Chris Rebert Aug. 27, 2012

Aug. 27, 2012

New submission from Chris Rebert: The cross-references, particularly to Popen.communicate(), in the warning box in the subprocess docs about using Popen.stdout.read() etc. aren't hyperlinked. The attached patch fixes that. ---------- assignee: docs@python components: Documentation files: link_communicate_warning.patch keywords: patch messages: 169182 nosy: cvrebert, docs@python priority: normal severity: normal status: open title: cross-refs in the subprocess.Popen.std{in,out,err} warning box aren't linked versions: Python 2.7, Python 3.3, Python 3.4 Added file: http://bugs.python.org/file27010/link_communicate_warning.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15788> _______________________________________

3 6

xdrlib: see also RFC 1832 obsoleted by RFC 4506
by Kyle Altendorf Aug. 26, 2012

Aug. 26, 2012

On the xdrlib page: http://docs.python.org/library/xdrlib.html in the first 'See Also:' there is reference to RFC 1832 which seems to have been obsoleted by RFC 4506: http://tools.ietf.org/html/rfc4506 Not so much an error, just an opportunity to update/add a reference. Cheers, -kyle

1 0

[issue1432343] Description of file-object read() method is wrong.
by R. David Murray Aug. 26, 2012

Aug. 26, 2012

R. David Murray added the comment: It looks to me like we (now, as of 67dc99a989cd) handle EINTR, so that the suggested caveat is no longer true. Since the TTY example has also been explained as correct, I'm going to close this. If I'm wrong about EINTR, someone (Antoine or Gregory, presumably) can reopen it... ---------- assignee: docs@python -> nosy: +gregory.p.smith, r.david.murray resolution: -> out of date stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue1432343> _______________________________________

1 0

[issue13801] The Python 3 Docs don't highlight nonlocal
by Ezio Melotti Aug. 26, 2012

Aug. 26, 2012

Ezio Melotti added the comment: Our version is 1.3.1. Georg said that this can be update after the 3.3 release. ---------- versions: +Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13801> _______________________________________

1 0

[issue13801] The Python 3 Docs don't highlight nonlocal
by Berker Peksag Aug. 26, 2012

Aug. 26, 2012

Berker Peksag added the comment: > 'nonlocal' is not highlighted because in the pygments version that we are using 'nonlocal' is missing in Python3Lexer.tokens['keywords'] see (Doc/tools/pygments/lexers/agile.py:196). The nonlocal keyword has been added in Pygments 1.5. https://bitbucket.org/birkenfeld/pygments-main/src/972a251fa742/pygments/le… ---------- nosy: +berker.peksag _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13801> _______________________________________

1 0

[issue13801] The Python 3 Docs don't highlight nonlocal
by Ezio Melotti Aug. 26, 2012

Aug. 26, 2012

Ezio Melotti added the comment: Sphinx is configured to use Python3Lexer (highlight_language is set to 'python3' in Doc/conf.py). 'nonlocal' is not highlighted because in the pygments version that we are using 'nonlocal' is missing in Python3Lexer.tokens['keywords'] see (Doc/tools/pygments/lexers/agile.py:196). If this is fixed in more recent pygments versions, we only have to update our version. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13801> _______________________________________

1 0

[issue14674] Add link to RFC 4627 from json documentation
by Serhiy Storchaka Aug. 24, 2012

Aug. 24, 2012

New submission from Serhiy Storchaka <storchaka(a)gmail.com>: The json module documentation should give a link to RFC 4627 and explain the current implementation is different from it. For example, according to RFC 4627 only an object or an array can be top-level JSON element. ---------- assignee: docs@python components: Documentation messages: 159367 nosy: docs@python, storchaka priority: normal severity: normal status: open title: Add link to RFC 4627 from json documentation type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14674> _______________________________________

9 37

bug in offline documentation (Browser-specific)
by Lorenzo Grespan Aug. 23, 2012

Aug. 23, 2012

Hi, I downloaded the offline docs from here (version 3.2.3) http://docs.python.org/py3k/archives/python-3.2.3-docs-html.tar.bz2 unpacked them and opened 'index.html'. I then inserted a search term (I tried 'GIL') and ran 'search'. Google Chrome Version 21.0.1180.79 is stuck at the 'searching...' phase (see screenshot), while Firefox correctly rendered the search results. CPU usage is not increased (there's nothing at 100%) but nothing happens while the 'search' page is stuck. I am currently running Max OSX 10.7.4 on a 2.2 GHz Intel Core 2 Duo, with 2GB ram.

1 0

[issue1660009] continuing problem with httplib multiple set-cookie headers
by moijes12 Aug. 23, 2012

Aug. 23, 2012

Changes by moijes12 <moijes12(a)gmail.com>: ---------- nosy: -moijes12 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue1660009> _______________________________________

1 0

[issue10436] tarfile.extractfile in "r|" stream mode fails with filenames or members from getmembers()
by Wichert Akkerman Aug. 23, 2012

Aug. 23, 2012

Wichert Akkerman added the comment: You could also look for the first matching file and extract that. That way you can at least implement something similar to what standard tar can do: [fog;/tmp]-10> tar tf x.tar docs/ docs/index.rst docs/glossary.rst docs/Makefile docs/conf.py docs/changes.rst [fog;/tmp]-12> cat x.tar| tar xf - docs/index.rst [fog;/tmp]-13> ls docs index.rst ---------- nosy: +wichert _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10436> _______________________________________

1 0

[issue5088] optparse: inconsistent default value for append actions
by R. David Murray Aug. 22, 2012

Aug. 22, 2012

R. David Murray added the comment: It may or may not be too old to deserve comments, but it is too old to do anything about it. This can't change for backward compatibility reasons, and since optparse is deprecated in favor of argparse it isn't getting any new features. We still need to apply the doc patch, though...(makes note to self). ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue5088> _______________________________________

1 0

deque maxlen parameter
by Marcin Kuźmiński Aug. 22, 2012

Aug. 22, 2012

Hi, In the http://docs.python.org/library/collections.html#collections.deque it is written that the maxlen parameter was added in python2.7, while in python2.6.8 i can provide maxlen parameter to deque. Is this a docbug ? Cheers Marcin Kuzminski

1 0

[issue5088] optparse: inconsistent default value for append actions
by Louis Deflandre Aug. 22, 2012

Aug. 22, 2012

Louis Deflandre added the comment: Hello, Tell me if the issue is too old to deserve comments anymore. But I would like to challenge the conclusion made in this issue. The message msg9944 stated "Think of the default as the initial list" but it is inconsistent with the proper meaning of default which can be defined as : "a preselected option adopted by a computer program or other mechanism WHEN NO ALTERNATIVE IS SPECIFIED" (http://www.wordreference.com/definition/default - Oxford Dictionary). The "initial list" conclusion seems to me more implementation oriented than really user oriented ---------- nosy: +louis.deflandre _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue5088> _______________________________________

1 0

[issue12415] Missing: How to checkout the Doc sources
by Philip Olson Aug. 20, 2012

Aug. 20, 2012

New submission from Philip Olson <philip(a)roshambo.org>: I was unable to determine how to download the Python documentation source files (for building via Sphinx) but did figure out the following: hg clone http://hg.python.org/cpython cd cpython/Doc make html Where to get the Doc sources deserves a mention here: http://docs.python.org/dev/documenting/building.html I don't know this topic so won't propose a patch, but building.txt should mention where/how to get 'Doc' before the 'cd Doc' example. ---------- assignee: docs@python components: Documentation messages: 139147 nosy: docs@python, philip priority: normal severity: normal status: open title: Missing: How to checkout the Doc sources _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12415> _______________________________________

5 20

[issue13799] Base 16 should be hexadecimal in Unicode HOWTO
by Ramchandra Apte Aug. 20, 2012

Aug. 20, 2012

New submission from Ramchandra Apte <maniandram01(a)gmail.com>: "base 16" should be "hexadecimal" in the Unicode HOWTO in both Python 2 and 3 docs. ---------- assignee: docs@python components: Documentation messages: 151354 nosy: docs@python, ramchandra.apte priority: normal severity: normal status: open title: Base 16 should be hexadecimal in Unicode HOWTO 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/issue13799> _______________________________________

7 9

[issue15742] SQLite3 documentation changes
by Mike Hoy Aug. 20, 2012

Aug. 20, 2012

New submission from Mike Hoy: In Core-Mentorship we discussed this and decided on the following patch. ---------- assignee: docs@python components: Documentation files: sqlite3-docs-changes.diff keywords: patch messages: 168681 nosy: docs@python, mikehoy, r.david.murray priority: normal severity: normal status: open title: SQLite3 documentation changes versions: Python 3.3 Added file: http://bugs.python.org/file26933/sqlite3-docs-changes.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15742> _______________________________________

4 4

[issue4966] Improving Lib Doc Sequence Types Section
by Roundup Robot Aug. 20, 2012

Aug. 20, 2012

Roundup Robot added the comment: New changeset 463f52d20314 by Nick Coghlan in branch 'default': Close #4966: revamp the sequence docs in order to better explain the state of modern Python http://hg.python.org/cpython/rev/463f52d20314 ---------- nosy: +python-dev resolution: -> fixed stage: needs patch -> committed/rejected status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue4966> _______________________________________

1 0

[issue4966] Improving Lib Doc Sequence Types Section
by Nick Coghlan Aug. 20, 2012

Aug. 20, 2012

Changes by Nick Coghlan <ncoghlan(a)gmail.com>: ---------- assignee: -> ncoghlan versions: -Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue4966> _______________________________________

1 0

TZ offset description is unclear in docs (issue 8810)
by ncoghlan＠gmail.com Aug. 20, 2012

Aug. 20, 2012

Ben's patch is a definite improvement. I'll tweak it in accordance with my comments and apply the fix here at the sprints. http://bugs.python.org/review/8810/diff/5782/Doc/library/datetime.rst File Doc/library/datetime.rst (right): http://bugs.python.org/review/8810/diff/5782/Doc/library/datetime.rst#newco… Doc/library/datetime.rst:1013: a magnitude of a whole number of minutes and larger than 24 hours (if not, The offsets actually have to be between -1 day and +1 day http://bugs.python.org/review/8810/diff/5782/Modules/_datetimemodule.c File Modules/_datetimemodule.c (right): http://bugs.python.org/review/8810/diff/5782/Modules/_datetimemodule.c#newc… Modules/_datetimemodule.c:3124: PyDoc_STR("datetime -> DST offset in minutes east of UTC.")}, The C docstrings should match the Python ones http://bugs.python.org/review/8810/

1 0

Looking to contribute
by Sebastiaan de Haan Aug. 19, 2012

Aug. 19, 2012

Hey Guy's I'd like to help out with the python project and have read the documentation on the website. Still a bit unsure as to where to go next but I'd like to take a shot at the following issue: http://bugs.python.org/issue1722 It is my understanding that this is a relatively easy issue to get one's feet wet in the world of contributing. Please be gentle and sorry for any grammatical errors, English is not my first language. Please let me know if you have any tips/comments/suggestions about this issue, or my contribution in general. Kind regards, Sebastiaan.

2 5

[issue15131] Document py/pyw launchers
by Brian Curtin Aug. 19, 2012

Aug. 19, 2012

New submission from Brian Curtin <brian(a)python.org>: As of http://hg.python.org/cpython/rev/a7ecbb2ad967, the PEP 397 launchers are included. Their functionality should be documented. ---------- assignee: docs@python components: Documentation, Windows messages: 163374 nosy: brian.curtin, docs@python priority: critical severity: normal stage: needs patch status: open title: Document py/pyw launchers type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15131> _______________________________________

1 2

suggestion for tutorial, section 2
by Christopher Crawford Aug. 19, 2012

Aug. 19, 2012

Hello, As someone just learning Python from Bash/C++ background, I would like to suggest a small addition to 2.1.2: how to execute a script inside the shell (similar to bash 'scriptname', 'source script' or '. script'): import fn, or reload(fn) related, it would be nice to have info near the beginning of the tutorial how to call system commands: import os; os.system('..') --thanks, Chris Christopher Crawford Dept. of Physics & Astronomy University of Kentucky 373 C.-P. Building Lexington, KY 40506-0055 859-257-2504 (office) 859-421-9612 (cell) 859-323-2846 (fax)

1 0

Re: [docs] Missing items in installation/setup instructions (issue 12436)
by ezio.melotti＠gmail.com Aug. 19, 2012

Aug. 19, 2012

http://bugs.python.org/review/12436/diff/5769/Doc/using/windows.rst File Doc/using/windows.rst (right): http://bugs.python.org/review/12436/diff/5769/Doc/using/windows.rst#newcode… Doc/using/windows.rst:587: Notepad++ is a free source code editor and Notepad replacement that support several languagees including Python. Running in the MS Windows environment, its use is governed by GPL license. Also this line is too long. http://bugs.python.org/review/12436/

1 0

Missing items in installation/setup instructions (issue 12436)
by ezio.melotti＠gmail.com Aug. 19, 2012

Aug. 19, 2012

http://bugs.python.org/review/12436/diff/5769/Doc/using/windows.rst File Doc/using/windows.rst (right): http://bugs.python.org/review/12436/diff/5769/Doc/using/windows.rst#newcode… Doc/using/windows.rst:587: Notepad++ is a free source code editor and Notepad replacement that support several languagees including Python. Running in the MS Windows environment, its use is governed by GPL license. supports http://bugs.python.org/review/12436/

1 0

[issue15569] Doc doc: incorrect description of some roles as format-only
by Mike Hoy Aug. 19, 2012

Aug. 19, 2012

Mike Hoy added the comment: I would like to submit a patch for this. Is anyone currently working on one? ---------- nosy: +mikehoy _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15569> _______________________________________

1 0

Comment on a section 7.2.5.7.
by Ovidius Publius Naso Aug. 18, 2012

Aug. 18, 2012

Hi, My comment does not affect the validity of the example given in section 7.2.5.7. "Finding all Adverbs and their Positions", but its misleading title. The reason is that none all adverbs end on "ly" (e.g. well, fast, slow, tight) and not all words ending on "ly" are adverbs (e.g. bully, friendly, Italy, apply, supply), or there are words whose type depends on situation (e.g. ugly) Cheers, Ovidius

2 1

(no subject)
by Juan Kalimacho Baldez Aug. 18, 2012

Aug. 18, 2012

Hi. If not a secret, What software was used in creating Python tutorials? Thanks Juan

2 1

Bug in python tutorial
by Øystein Rognes Solheim Aug. 18, 2012

Aug. 18, 2012

In chapter 4.4 of the python tutorial ( http://docs.python.org/tutorial/controlflow.html#break-and-continue-stateme… ), the second example reads: >>> for num in range(2, 10):... if x % 2 == 0:... print("Found an even number", num)... continue... print("Found a number", num)Found an even number 2Found a number 3Found an even number 4Found a number 5Found an even number 6Found a number 7Found an even number 8Found a number 9 The x in line 2 should be replaced by num. best regards, Øystein R. Solheim

2 1

[issue15636] base64.decodebytes is only available in Python3.1+
by Andrew Scheller Aug. 18, 2012

Aug. 18, 2012

New submission from Andrew Scheller: According to the documentation ( http://docs.python.org/py3k/library/base64.html#base64.decodebytes ) both the decodebytes and the deprecated decodestring methods are available in the base64 module in Python3.x However in Python3.0 (I'm testing with version 3.0.1 built from source) the base64 module only has the decodestring method, it doesn't have decodebytes. IMHO the documentation should be updated to reflect this. It looks like decodebytes was added to Python3.1 by http://bugs.python.org/issue3613 ---------- assignee: docs@python components: Documentation messages: 168080 nosy: docs@python, lurchman priority: normal severity: normal status: open title: base64.decodebytes is only available in Python3.1+ type: enhancement versions: Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15636> _______________________________________

5 5

[issue15355] generator.__next__() docs should mention exception if already executing
by Chris Jerdonek Aug. 18, 2012

Aug. 18, 2012

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: I think the generator.__next__() documentation should say that it raises an exception if the generator is already executing: http://docs.python.org/dev/reference/expressions.html#generator.__next__ I don't think this is currently mentioned anywhere in the section on yield expressions. I think this is worth mentioning because this is different from the general situation for iterators, for example. One consequence of this is that, unlike for iterators, using a bare generator in a multithreaded situation will always result in a critical section (since an iterator can be made to take care of its own locking, etc). ---------- assignee: docs@python components: Documentation keywords: easy messages: 165476 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: generator.__next__() docs should mention exception if already executing versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15355> _______________________________________

5 13

[issue15694] link to "file object" glossary entry in open() and io docs
by Chris Jerdonek Aug. 18, 2012

Aug. 18, 2012

New submission from Chris Jerdonek: It would be nice if the first sentence of the documentation for the open() built-in function: "Open file and return a corresponding stream. If the file cannot be opened, an OSError is raised." http://docs.python.org/dev/library/functions.html#open linked to the glossary entry for "file object": http://docs.python.org/dev/glossary.html#term-file-object Incidentally, this would be similar to what was done 2.7 documentation of open(): http://docs.python.org/library/functions.html#open Similarly, the introductory overview section of the io module should also link to the glossary entry for "file object": "Concrete objects belonging to any of these categories will often be called streams; another common term is file-like objects." (from http://docs.python.org/dev/library/io.html#overview ) ---------- assignee: docs@python components: Documentation messages: 168392 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: link to "file object" glossary entry in open() and io docs type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15694> _______________________________________

5 7

[issue15660] Clarify 0 prefix for width specifier in str.format doc,
by Terry J. Reedy Aug. 17, 2012

Aug. 17, 2012

Changes by Terry J. Reedy <tjreedy(a)udel.edu>: ---------- assignee: docs@python -> terry.reedy _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15660> _______________________________________

1 0

[issue15660] Clarify 0 prefix for width specifier in str.format doc,
by Terry J. Reedy Aug. 17, 2012

Aug. 17, 2012

Changes by Terry J. Reedy <tjreedy(a)udel.edu>: ---------- stage: needs patch -> committed/rejected status: open -> closed title: In str.format there is a misleading error message about alignment -> Clarify 0 prefix for width specifier in str.format doc, _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15660> _______________________________________

1 0

[issue15660] In str.format there is a misleading error message about alignment
by Terry J. Reedy Aug. 17, 2012

Aug. 17, 2012

Changes by Terry J. Reedy <tjreedy(a)udel.edu>: ---------- resolution: -> fixed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15660> _______________________________________

1 0

[issue15660] In str.format there is a misleading error message about alignment
by Roundup Robot Aug. 17, 2012

Aug. 17, 2012

Roundup Robot added the comment: New changeset 85cd54b2d3a1 by Terry Jan Reedy in branch '2.7': Issue 15660: Clarify 0 prefix for width field in str.format doc. http://hg.python.org/cpython/rev/85cd54b2d3a1 New changeset 6bc14974024f by Terry Jan Reedy in branch '3.2': Issue 15660: Clarify 0 prefix for width field in str.format doc. http://hg.python.org/cpython/rev/6bc14974024f New changeset f181dd088e63 by Terry Jan Reedy in branch 'default': Merge with 3.2 #15660 http://hg.python.org/cpython/rev/f181dd088e63 ---------- nosy: +python-dev _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15660> _______________________________________

1 0

[issue15660] In str.format there is a misleading error message about alignment
by Terry J. Reedy Aug. 17, 2012

Aug. 17, 2012

Terry J. Reedy added the comment: As I read the docs, the error message is correct and this issue is invalid as a behavior issue. I read the OP's second message as more or less saying this also. "'=' Forces the padding to be placed after the sign (if any) but before the digits. This is used for printing fields in the form ‘+000000120’. This alignment option is only valid for numeric types." "If the width field is preceded by a zero ('0') character, this enables zero-padding. This is equivalent to an alignment type of '=' and a fill character of '0'." So ":02" is equivalent to ":0=2", which is invalid. >>> '{:02d}'.format(1) '01' works fine. I decided make this a doc issue and add " for numeric types" after "this enables zero-padding" before closing this. ---------- assignee: -> docs@python components: +Documentation -Interpreter Core nosy: +docs@python, terry.reedy versions: +Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15660> _______________________________________

1 0

[issue15412] Note in documentation for weakrefs
by Richard Oudkerk Aug. 17, 2012

Aug. 17, 2012

New submission from Richard Oudkerk <shibturn(a)gmail.com>: In the documentation on weakrefs there is the following quote Note: Weak references to an object are cleared before the object’s __del__() is called, to ensure that the weak reference callback (if any) finds the object still alive. But I think the weakref is always dead by the time the callback is invoked. The first paragraph from the documentation for weakref.ref(object[, callback]) contains the following: If callback is provided and not None, and the returned weakref object is still alive, the callback will be called when the object is about to be finalized; the weak reference object will be passed as the only parameter to the callback; **the referent will no longer be available**. Which does prompt a question: what use is there for the weakref argument to the callback if it already dead? (Compare http://bugs.python.org/issue14933) ---------- assignee: docs@python components: Documentation messages: 166002 nosy: docs@python, pitrou, sbt priority: normal severity: normal status: open title: Note in documentation for weakrefs _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15412> _______________________________________

3 5

[issue6696] Profile objects should be documented
by Andrew Svetlov Aug. 16, 2012

Aug. 16, 2012

Changes by Andrew Svetlov <andrew.svetlov(a)gmail.com>: ---------- nosy: +asvetlov _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue6696> _______________________________________

1 0

Re: [docs] Provide some examples for usage of ElementTree methods/attributes (issue 15586)
by ezio.melotti＠gmail.com Aug. 16, 2012

Aug. 16, 2012

http://bugs.python.org/review/15586/

1 0

Re: [docs] Provide some examples for usage of ElementTree methods/attributes (issue 15586)
by ezio.melotti＠gmail.com Aug. 16, 2012

Aug. 16, 2012

http://bugs.python.org/review/15586/diff/5727/Doc/library/xml.etree.element… File Doc/library/xml.etree.elementtree.rst (right): http://bugs.python.org/review/15586/diff/5727/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:155: ... tree.write('output.xml') This should now have the >>> prompt (same with the following examples). http://bugs.python.org/review/15586/

1 0

[issue15543] central documentation for 'universal newlines'
by Chris Jerdonek Aug. 15, 2012

Aug. 15, 2012

New submission from Chris Jerdonek: "Universal newlines" of PEP 278 does not seem to have a central, linkable description within the documentation. In particular, there does not seem to be a glossary entry or any index entries for it. The main documentation seems to be in the middle of the documentation for the open() built-in function: http://docs.python.org/dev/library/functions.html?highlight=open#open But this does not feature prominently when searching for universal newlines in the "Quick Search". This would allow us, for example, to reference and link to an explanation of universal newlines in the documentation for str.splitlines(): http://docs.python.org/dev/library/stdtypes.html#str.splitlines I would be happy to provide a patch. ---------- assignee: docs@python components: Documentation keywords: easy messages: 167279 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: central documentation for 'universal newlines' versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________

7 26

gzip compression level
by Wolfgang Rohdewald Aug. 15, 2012

Aug. 15, 2012

http://docs.python.org/library/gzip.html says level is 1..9 actually 0 works too - this the original uncompressed data but with a gzip header. I need level 0 for getting a smaller git repository with many svgz files which have often been edited (the file names and types cannot be changed) So - is this a documentation bug or have I just been lucky? -- Wolfgang

2 1

Bug in part 5 of the Python 3 tutorial
by Anton Eliasson Aug. 15, 2012

Aug. 15, 2012

Hi! In the Python 3 tutorial about data structures, in the section about nested list comprehensions (http://docs.python.org/py3k/tutorial/datastructures.html#nested-list-compre…); the zip function is described differently than it works in my installation (Ubuntu 12.04). I'm fairly new to Python so the issue is probably described best using an example: $ python3 Python 3.2.3 (default, May 3 2012, 15:51:42) [GCC 4.6.3] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> matrix = [ ... [1, 2, 3, 4], ... [5, 6, 7, 8], ... [9, 10, 11, 12], ... ] >>> zip(*matrix) <zip object at 0x1053098> However, in the tutorial the zip function returns a list of tuplets like this: >>> zip(*matrix) [(1, 5, 9), (2, 6, 10), (3, 7, 11), (4, 8, 12)] In order to get that result, I have to do this in my installation: >>> list(zip(*matrix)) [(1, 5, 9), (2, 6, 10), (3, 7, 11), (4, 8, 12)] -- Med vänliga hälsningar / Kindest Regards Anton Eliasson

3 2

[issue15656] "Extending Python with C" page needs update for 3.x
by Sandro Tosi Aug. 15, 2012

Aug. 15, 2012

New submission from Sandro Tosi: Hello, this has been reported at http://mail.python.org/pipermail/docs/2012-July/009223.html but since I have no experience to judge if it's correct or not, i'll just report it: >>> I've recenty started to try using C code in python using the wonderful python API, although i have to say the learning curve was non neglectable :P I've spotted what I believe to be a small mistake in the documentation from this page: http://docs.python.org/release/3.2/extending/extending.html In paragraph 1.8 (http://docs.python.org/release/3.2/extending/extending.html#keyword-paramet…), the code example given contains an error, which is actually obsolete code from python 2.7: void initkeywdarg(void) { /* Create the module and add the functions */ Py_InitModule("keywdarg", keywdarg_methods); } This doesn't work in Python3.2. It's supposed to be static struct PyModuleDef keywdargmodule = { PyModuleDef_HEAD_INIT, "keywdarg", /* name of module */ keywdarg_doc, /* module documentation, may be NULL */ -1, /* size of per-interpreter state of the module, or -1 if the module keeps state in global variables. */ keywdarg_methods }; PyMODINIT_FUNC PyInit_keywdarg(void) { return PyModule_Create(&keywdargmodule); } As explained above (and confirmed by experience). <<< ---------- assignee: docs@python components: Documentation messages: 168223 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: patch review status: open title: "Extending Python with C" page needs update for 3.x versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15656> _______________________________________

4 6

Bug in Functional Programming HOWTO
by Sergey Skovorodkin Aug. 15, 2012

Aug. 15, 2012

Hi, http://docs.python.org/howto/functional.html#iterators > You’ll run into obvious problems if the iterator is infinite; max(), min(), and "not in" will never return, and if the element X never appears in the stream, the "in" operator won’t return either. "not in" returns False if the element X appears in the stream, so I think it's better to say > max() and min() will never return, and if the element X never appears in the stream, the "in" and "not in" operators won’t return either. -- Sergey Skovorodkin

2 1

[issue15269] Document dircmp.left and dircmp.right
by Chris Jerdonek Aug. 15, 2012

Aug. 15, 2012

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: The documentation for the filecmp.dircmp class doesn't mention dircmp.left and dircmp.right. Being aware of this up front would make certain simplifications easier to think of. For example, knowing about these attributes opens up the possibility of passing dircmp instances around without having to pass the two paths separately (e.g. in certain recursive algorithms involving dircmp). Knowing this also means you can recover the two paths if using the subdirs attribute (whose values are dircmp instances). ---------- assignee: docs@python components: Documentation keywords: easy messages: 164781 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: Document dircmp.left and dircmp.right versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15269> _______________________________________

5 17

Error in Python 3 docs for PyMethodDef
by Michael Welsh Duggan Aug. 14, 2012

Aug. 14, 2012

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. -- Michael Welsh Duggan (mwd(a)cert.org)

2 1

Language Missing in Python
by Isaac Munjunga Aug. 14, 2012

Aug. 14, 2012

I can't find my language every time I update my Ubuntu distro. Kindly include and update locale: 'en_ZM': 'en_GB.ISO8859-1', 'en_ZM.iso88591': 'en_GB.ISO8859-1', I manually include that, but I know someone people may not have the time to do it. Thanks, Isaac

2 1

Small error in the "Extending Python with C" page
by Hadrien Titeux Aug. 14, 2012

Aug. 14, 2012

Hello, I've recenty started to try using C code in python using the wonderful python API, although i have to say the learning curve was non neglectable :P I've spotted what I believe to be a small mistake in the documentation from this page: http://docs.python.org/release/3.2/extending/extending.html In paragraph 1.8 (http://docs.python.org/release/3.2/extending/extending.html#keyword-paramet…), the code example given contains an error, which is actually obsolete code from python 2.7: void initkeywdarg(void) { /* Create the module and add the functions */ Py_InitModule("keywdarg", keywdarg_methods); } This doesn't work in Python3.2. It's supposed to be static struct PyModuleDef keywdargmodule = { PyModuleDef_HEAD_INIT, "keywdarg", /* name of module */ keywdarg_doc, /* module documentation, may be NULL */ -1, /* size of per-interpreter state of the module, or -1 if the module keeps state in global variables. */ keywdarg_methods }; PyMODINIT_FUNC PyInit_keywdarg(void) { return PyModule_Create(&keywdargmodule); } As explained above (and confirmed by experience). Thanks for your work, Hadrien.

2 1

Grammatical error
by b99902035＠csie.ntu.edu.tw Aug. 14, 2012

Aug. 14, 2012

Under http://docs.python.org/py3k/tutorial/inputoutput.html#fancier-output-format…, "(or will force a SyntaxError if there is not equivalent syntax)" should be "(or will force a SyntaxError if there is __no__ equivalent syntax)". Regards. ---------------------------------------------------------------- This message was sent using IMP, the Internet Messaging Program.

2 1

Little mistake
by Christoph Müller Aug. 14, 2012

Aug. 14, 2012

On http://docs.python.org/py3k/tutorial/introduction.html: *code * *prints * *instead of * word[4] 'p' 'A' word[0:2] 'AH' 'He' word[2:4] 'el' 'lp'

1 2

re.VERBOSE whitespace behavior not completely documented (issue 15606)
by ezio.melotti＠gmail.com Aug. 14, 2012

Aug. 14, 2012

http://bugs.python.org/review/15606/diff/5718/Doc/library/re.rst File Doc/library/re.rst (right): http://bugs.python.org/review/15606/diff/5718/Doc/library/re.rst#newcode540 Doc/library/re.rst:540: extension construct (so, for example, ``(?P<a_or_b> a | b)`` is a Reading this it seems to me that ``( ?:`` is allowed. Maybe saying something like "within tokens like ``(?:`` or ``(?P<...>``" is better. http://bugs.python.org/review/15606/diff/5718/Doc/library/re.rst#newcode546 Doc/library/re.rst:546: the leftmost such ``'#'`` through the end of the line are ignored. I find this paragraph a bit confusing, and would rephrase it to something like: """ All the text after and including the ``'#'`` character is considered as comment and ignored, unless the ``'#'`` is in a character class or it's preceded by an unescaped backslash. """ http://bugs.python.org/review/15606/

1 0

Re: [docs] Typo in the String docs
by Sandro Tosi Aug. 14, 2012

Aug. 14, 2012

Hello Ramon, On Mon, Aug 13, 2012 at 2:09 PM, Ramon Royo Giner <rroyog(a)uoc.edu> wrote: > "Helloo".replace('oo', 'o') #does work -> "Hello" > "Helloo".replace('Helloo', 'oo', 'o') #doesnt work, throws a type error, > because 'o' is in the place of the third argument (maxreplace), which should > be an int I'm sorry, I could have used some examples to make my original email more clear. What you're doing is using the replace() method of the string object: >>> s = "Helloo" >>> type(s) <type 'str'> which has the first argument already "filled": >>> s.replace('oo', 'o') 'Hello' so you don't need to specify once again the string it operates on. In the example you cited in the original email refers to the replace() function of the string module: >>> import string >>> string.replace('Helloo', 'oo', 'o') 'Hello' Regards, -- Sandro Tosi (aka morph, morpheus, matrixhasu) My website: http://matrixhasu.altervista.org/ Me at Debian: http://wiki.debian.org/SandroTosi

1 0

Re: [docs] Provide some examples for usage of ElementTree methods/attributes (issue 15586)
by eliben＠gmail.com Aug. 14, 2012

Aug. 14, 2012

http://bugs.python.org/review/15586/diff/5726/Doc/library/xml.etree.element… File Doc/library/xml.etree.elementtree.rst (right): http://bugs.python.org/review/15586/diff/5726/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:102: import xml.etree.ElementTree as ET Please fix this similarly to my fix for the 3.3 patch The parse method you call returns an element, not a tree, and anyway there's a shorter way (ET.parse function) http://bugs.python.org/review/15586/diff/5726/Doc/library/xml.etree.element… Doc/library/xml.etree.elementtree.rst:111: :func:`fromstring` parses XML from a string directly into an :class:`Element`, Please also align here for the fixed 3.3 patch http://bugs.python.org/review/15586/

1 0

[issue15497] correct characters in TextWrapper.replace_whitespace docs
by Chris Jerdonek Aug. 13, 2012

Aug. 13, 2012

New submission from Chris Jerdonek: This issue is to correct the list of whitespace characters to replace in the documentation for the textwrap module's TextWrapper.replace_whitespace attribute. The documentation says this list is string.whitespace: http://docs.python.org/dev/library/textwrap.html#textwrap.TextWrapper.repla… However, the code deliberately avoids using string.whitespace and uses a hard-coded list of characters instead. For example, see this code comment: # Hardcode the recognized whitespace characters to the US-ASCII # whitespace characters. The main reason for doing this is that in # ISO-8859-1, 0xa0 is non-breaking whitespace, so in certain locales # that character winds up in string.whitespace.... http://hg.python.org/cpython/file/917295aaad76/Lib/textwrap.py#l12 Patch attached. ---------- assignee: docs@python components: Documentation files: issue-textwrap-whitespace.patch keywords: easy, patch messages: 166855 nosy: cjerdonek, docs@python priority: normal severity: normal stage: patch review status: open title: correct characters in TextWrapper.replace_whitespace docs versions: Python 2.7, Python 3.3 Added file: http://bugs.python.org/file26591/issue-textwrap-whitespace.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15497> _______________________________________

3 3

[issue15628] Add import ABC hierarchy to docs for importlib
by Brett Cannon Aug. 13, 2012

Aug. 13, 2012

Brett Cannon added the comment: http://hg.python.org/cpython/rev/1c8a6df94602 seems to be commit this. ---------- resolution: -> fixed stage: -> committed/rejected status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15628> _______________________________________

1 0

[issue15561] update subprocess docs to reference io.TextIOWrapper
by Chris Jerdonek Aug. 13, 2012

Aug. 13, 2012

New submission from Chris Jerdonek: This is an issue to update the subprocess module documentation after updates to io.TextIOWrapper's documentation here: http://hg.python.org/cpython/rev/f17a1410ebe5 This issue was discussed briefly on python-dev: http://mail.python.org/pipermail/python-dev/2012-August/121239.html Patch attached. ---------- assignee: docs@python components: Documentation files: issue-subprocess-docs-1.patch keywords: easy, patch messages: 167512 nosy: cjerdonek, docs@python, haypo priority: normal severity: normal stage: patch review status: open title: update subprocess docs to reference io.TextIOWrapper versions: Python 3.3 Added file: http://bugs.python.org/file26703/issue-subprocess-docs-1.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________

3 18