Mailman 3 June 2013 - docs

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

Oct. 14, 2015

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

3 6

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

Oct. 3, 2015

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

8 24

[issue16893] Create IDLE help.txt from Doc/library/idle.rst
by Zachary Ware Sept. 23, 2015

Sept. 23, 2015

New submission from Zachary Ware: Lib/idlelib/help.txt and Doc/library/idle.rst contain almost exactly the same information, only formatted a bit differently. This issue is to suggest the merger of the two files, by way of creating help.txt from idle.rst as a part of the build or install process. This could be as simple as merely copying the one to the other, but that of course leaves in place all reST directives that mean nothing to a simple text document. Thus, idle.rst should be processed to create help.txt. This could be done with sphinx/docutils, but to avoid having the CPython build process (not just the doc build process) depend on those tools, I think a very simple dedicated script could be created to do the processing without much trouble. As far as I can tell, this new script would only have to do a few simple steps: - Remove comments (including index markers, etc.) - Remove reST roles (replace ":role:`" with "`", possibly remove "`" as well) - Remove backslash escapes - Remove (or undouble) double colons - Replace "#." with "1.", etc. Thoughts? ---------- assignee: docs@python components: Documentation, IDLE messages: 179362 nosy: Todd.Rovito, docs@python, eric.araujo, zach.ware priority: normal severity: normal status: open title: Create IDLE help.txt from Doc/library/idle.rst type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16893> _______________________________________

12 49

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

Aug. 13, 2015

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

4 4

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

July 30, 2015

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

8 10

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

July 21, 2015

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

8 21

[issue17359] python modules.zip is not documented
by Marc-Andre Lemburg July 16, 2015

July 16, 2015

New submission from Marc-Andre Lemburg: The feature to run a ZIP file containing Python modules is not documented. It was implemented in Python 2.6: * http://bugs.python.org/issue1739468 and mentioned in the "What's new": * http://docs.python.org/2/whatsnew/2.6.html?highlight=python%20run%20zip%20f… but searching the documentation for "__main__.py" returns 0 hits in the docs (for Python 2.7 and 3.4). I guess "python dir" should also be mentioned somewhere... ---------- assignee: docs@python components: Documentation messages: 183550 nosy: docs@python, lemburg priority: normal severity: normal status: open title: python modules.zip is not documented versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17359> _______________________________________

6 13

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

June 24, 2015

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

5 8

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

June 20, 2015

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

4 3

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

May 17, 2015

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

3 3

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

April 25, 2015

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

6 10

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

April 22, 2015

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

11 21

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

April 21, 2015

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

4 4

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

April 20, 2015

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

10 29

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

April 19, 2015

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

6 5

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

April 14, 2015

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

10 12

[issue17380] initproc return value is unclear
by Zbyszek Jędrzejewski-Szmek April 13, 2015

April 13, 2015

New submission from Zbyszek Jędrzejewski-Szmek: initproc is declared to return an int, but what returned values mean is not documented. Noddy_init in http://docs.python.org/3/extending/newtypes.html?highlight=initproc#adding-… can be seen to return 0 on success and -1 on error, but that's about it. Also, when I wrote a function which return 1 on error, on every second invocation the exception would be ignored: static int Reader_init(Reader *self, PyObject *args, PyObject *keywds) { ... if (flags && path) { PyErr_SetString(PyExc_ValueError, "cannot use both flags and path"); return 1; } ... } >>> obj(123, '/tmp') >>> obj(123, '/tmp') ... ValueError >>> obj(123, '/tmp') >>> obj(123, '/tmp') ... ValueError I'm not sure how to interpret this since I couldn't find the documentation for the expected value. ---------- assignee: docs@python components: Documentation, Extension Modules messages: 183689 nosy: docs@python, zbysz priority: normal severity: normal status: open title: initproc return value is unclear type: behavior versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17380> _______________________________________

6 9

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

April 12, 2015

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

9 17

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

March 24, 2015

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

9 19

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

March 18, 2015

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

5 7

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

Feb. 20, 2015

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

10 23

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

Feb. 18, 2015

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

3 3

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

Feb. 16, 2015

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

6 10

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

Feb. 10, 2015

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

4 9

[issue17876] Doc issue with threading.Event
by Xavier Ordoquy Dec. 16, 2014

Dec. 16, 2014

New submission from Xavier Ordoquy: The documentation isn't correct for the threading.Event class under python 3.2. In the threading doc page (http://docs.python.org/3.2/library/threading.html), Event is said to be at the same time a function and a class. This is misleading and lead to a regression for celery under python 3.2 (https://github.com/celery/celery/pull/1333). Could the doc be updated under python 3.2 so that threading.Event leads to the function and threading._Event leads to the class ? Regards, Xavier. ---------- assignee: docs@python components: Documentation messages: 188127 nosy: docs@python, xordoquy priority: normal severity: normal status: open title: Doc issue with threading.Event type: enhancement versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17876> _______________________________________

4 5

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

Dec. 12, 2014

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

7 11

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

Oct. 31, 2014

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

11 35

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

Oct. 23, 2014

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

8 26

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

Oct. 23, 2014

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

7 13

[issue16863] Argparse tutorial outdated
by Charlie Dimino Oct. 22, 2014

Oct. 22, 2014

New submission from Charlie Dimino: http://docs.python.org/2/howto/argparse.html Error message in the first example is outdated, may indicate further out of date information on page. Example: The tutorial says: prog.py: error: the following arguments are required: echo When the actual error received is: prog.py: error: too few arguments ---------- assignee: docs@python components: Documentation messages: 179041 nosy: Charlie.Dimino, docs@python priority: normal severity: normal status: open title: Argparse tutorial outdated versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16863> _______________________________________

8 13

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

Oct. 19, 2014

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

14 34

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

Oct. 14, 2014

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

3 11

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

Oct. 10, 2014

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

8 12

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

Oct. 6, 2014

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

7 11

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

Oct. 6, 2014

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

8 12

[issue17057] Data model documentation grammar
by Hobs Oct. 6, 2014

Oct. 6, 2014

New submission from Hobs: New-style and old-style class expalanation in the datamodel section has minor grammatical errors and one minor ambiguity that could be improved. http://docs.python.org/2/reference/datamodel.html#new-style-and-classic-cla… * "independently of" should always be "indepenent of" * single hyphens (-) should be double-hyphens (--) for an m-dash * "flavour" should be "flavor" (used 100x more often in docs.python) * "only the symantics of..." is ambiguous. can't tell if 'only' modifies 'symantics' or 'new-style classes'? ---------- assignee: docs@python components: Documentation files: datamodel-reference-docs.patch keywords: patch messages: 180812 nosy: Hobson.Lane, docs@python priority: normal severity: normal status: open title: Data model documentation grammar type: enhancement versions: Python 2.7 Added file: http://bugs.python.org/file28876/datamodel-reference-docs.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17057> _______________________________________

3 2

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

Oct. 6, 2014

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

6 8

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

Oct. 6, 2014

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

5 7

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

Oct. 6, 2014

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

4 3

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

Oct. 6, 2014

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

5 5

[issue18043] No mention of `match.regs` in `re` documentation
by Ram Rachum Oct. 4, 2014

Oct. 4, 2014

New submission from Ram Rachum: There's no mention of `match.regs` in the documentation of the `re` module. ---------- assignee: docs@python components: Documentation messages: 189859 nosy: cool-RR, docs@python priority: normal severity: normal status: open title: No mention of `match.regs` in `re` documentation type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18043> _______________________________________

6 7

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

Oct. 4, 2014

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

8 23

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

Sept. 27, 2014

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

5 6

[issue10702] bytes and bytearray methods are not documented
by Alexander Belopolsky Sept. 27, 2014

Sept. 27, 2014

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: Library reference manual has a section dedicated to string methods [1], but similar methods of bytes and bytearray types are not documented. Adding two new sections would probably be too repetitious, so I wonder if it would make sense to add notes about byte/bytearray methods to the matching string methods' entries. See also issue10587. [1] http://docs.python.org/dev/py3k/library/stdtypes.html#string-methods ---------- assignee: docs@python components: Documentation messages: 123960 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: bytes and bytearray methods are not documented versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10702> _______________________________________

6 7

[issue17462] argparse FAQ: how it is different from optparse
by anatoly techtonik Sept. 26, 2014

Sept. 26, 2014

New submission from anatoly techtonik: http://stackoverflow.com/questions/3217673/why-use-argparse-rather-than-opt… Too many votes. This should be confirmed by the official documentation. ---------- assignee: docs@python components: Documentation messages: 184468 nosy: docs@python, techtonik priority: normal severity: normal status: open title: argparse FAQ: how it is different from optparse _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17462> _______________________________________

9 15

[issue16827] Remove the relatively advanced content from section 2 in tutorial
by Ramchandra Apte Sept. 18, 2014

Sept. 18, 2014

New submission from Ramchandra Apte: Most of the content in section 2 in the tutorial, http://docs.python.org/3/tutorial/interpreter.html , is relatively advanced and doesn't belong in, at least, the beginning of the tutorial. Only 2.1. Invoking the Interpreter, and 2.2.3. Source Code Encoding should be in section 2. The rest can be moved outside the tutorial, or in later portions. Thanks to Ezio Melotti for helping me overcome my laziness in filing this bug. ---------- assignee: docs@python components: Documentation messages: 178680 nosy: docs@python, ramchandra.apte priority: normal severity: normal status: open title: Remove the relatively advanced content from section 2 in tutorial _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________

9 14

[issue14824] reprlib documentation references string module
by Jasper St. Pierre Sept. 18, 2014

Sept. 18, 2014

New submission from Jasper St. Pierre <jstpierre(a)mecheye.net>: http://docs.python.org/dev/library/reprlib.html """ Formatting methods for specific types are implemented as methods with a name based on the type name. In the method name, TYPE is replaced by string.join(string.split(type(obj).__name__, '_')). Dispatch to these methods is handled by repr1(). Type-specific methods which need to recursively format a value should call self.repr1(subobj, level - 1). """ Outstanding. ---------- assignee: docs@python components: Documentation messages: 160805 nosy: docs@python, magcius priority: normal severity: normal status: open title: reprlib documentation references string module versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14824> _______________________________________

5 8

[issue15418] 2to3 docs should mention setup.py fixes required to install compatible packages in Python 3
by anatoly techtonik Aug. 30, 2014

Aug. 30, 2014

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/py3k/library/2to3.html should mention the practice of running 2to3 in setup.py for codebase compatible with both Python 2 and Python 3. ---------- assignee: docs@python components: Documentation messages: 166108 nosy: docs@python, techtonik priority: normal severity: normal status: open title: 2to3 docs should mention setup.py fixes required to install compatible packages in Python 3 versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15418> _______________________________________

4 3

[issue13540] Document the Action API
by Jason R. Coombs Aug. 24, 2014

Aug. 24, 2014

New submission from Jason R. Coombs <jaraco(a)jaraco.com>: In http://docs.python.org/dev/library/argparse.html#action, when describing an arbitrary action, the documentation states, "You can also specify an arbitrary action by passing an object that implements the Action API." This statement does not link to any documentation on the Action API and does not describe the API except to give an example. Furthermore, the example contradicts the description. The description says "pass an object" but the example passes a class. The documentation should clarify the text relating to the example and should document the expected interface for a custom action. ---------- assignee: docs@python components: Documentation messages: 148921 nosy: docs@python, jason.coombs priority: low severity: normal status: open title: Document the Action API type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13540> _______________________________________

8 30

[issue15428] add "Name Collision" section to argparse docs
by Steven Bethard Aug. 7, 2014

Aug. 7, 2014

New submission from Steven Bethard <steven.bethard(a)gmail.com>: Several bugs (e.g. Issue 15327 and Issue 15271) have been filed suggesting that people aren't really clear on how argparse handles argument name collisions or how they can get it to do what they want. I think these problems could probably be solved by a "Name Collision" section (or something like that) in the argparse documentation. It would give a few example problems and show how to resolve them. Some things to include: * What happens when two arguments have the same dest (Issue 15271), with solutions including action='append' or different dest= values combined with identical metavar= values. * What happens when a parser and a sub-parser share some of the same argument names (Issue 15327), with solutions including specifying different dest= values for the parser and sub-parser * A brief mention and cross-reference to the "conflict_handler" section. ---------- assignee: docs@python components: Documentation messages: 166185 nosy: bethard, docs@python priority: normal severity: normal status: open title: add "Name Collision" section to argparse docs versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15428> _______________________________________

3 3

[issue15759] "make suspicious" doesn't display instructions in case of failure
by Ezio Melotti Aug. 5, 2014

Aug. 5, 2014

New submission from Ezio Melotti: I was running "make suspicious" in Doc/ and this was the output after finding 3 suspicious markups: writing output... [ 52%] library/inspect WARNING: [library/inspect:437] ":int" found in ">>> def foo(a, *, b:int, **kwargs):" WARNING: [library/inspect:437] ":int" found in "'(a, *, b:int, **kwargs)'" WARNING: [library/inspect:437] ":int" found in "'b:int'" writing output... [100%] whatsnew/index build finished with problems, 3 warnings. make: *** [build] Error 1 After figuring out how to mark these as false positives and adding the relevant entries to susp-ignored.csv, I ran "make suspicious" again, and got this useful message at the end: writing output... [100%] whatsnew/index build succeeded. Suspicious check complete; look for any errors in the above output or in build/suspicious /suspicious.csv. If all issues are false positives, append that file to tools/sphinxext/susp-ignored.csv. The problem is that this message should be displayed when there are failures, but it's not. Attached an attempt to fix the Makefile to avoid exiting in case of failures when the builder is "suspicious". Given that I'm not really familiar with makefiles, it probably doesn't make much sense. ---------- assignee: docs@python components: Documentation files: issue15759.diff keywords: patch messages: 168842 nosy: docs@python, eric.araujo, ezio.melotti, georg.brandl priority: normal severity: normal stage: patch review status: open title: "make suspicious" doesn't display instructions in case of failure type: behavior versions: Python 3.3 Added file: http://bugs.python.org/file26956/issue15759.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15759> _______________________________________

5 15

[issue18034] Last two entries in the programming FAQ are out of date (import related)
by R. David Murray Aug. 4, 2014

Aug. 4, 2014

New submission from R. David Murray: The second to last talks about the __import__ quirk with out calling __import__ out as deprecated. The last uses the imp module for reload. ---------- assignee: docs@python components: Documentation messages: 189827 nosy: brett.cannon, docs@python, eric.snow, r.david.murray priority: normal severity: normal stage: needs patch status: open title: Last two entries in the programming FAQ are out of date (import related) type: behavior versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18034> _______________________________________

5 8

[issue12970] os.wlak() consider some symlinks as dirs instead of non-dirs
by Марк Коренберг July 28, 2014

July 28, 2014

New submission from Марк Коренберг <socketpair(a)gmail.com>: Consider code: for (root, dirs, nondirs) in os.walk(path, followlinks=False): print (nondirs) This code will not print symlinks that refer to some dir. I think it is the bug. In other words: If followlinks is True, we should consider some symlinks as dirs. If not, any symlink is the non-dir. Patch included. Also, please fix documentation about this nuance. ---------- assignee: docs@python components: Documentation, Library (Lib) files: z.patch keywords: patch messages: 143965 nosy: docs@python, mmarkk priority: normal severity: normal status: open title: os.wlak() consider some symlinks as dirs instead of non-dirs type: behavior versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 Added file: http://bugs.python.org/file23140/z.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12970> _______________________________________

7 9

[issue17709] http://docs.python.org/2.7/objects.inv doesn't support :func:`repr` or :exc:`Exception`
by Russell Stuart July 23, 2014

July 23, 2014

New submission from Russell Stuart: .. topic:: http://docs.python.org/2.7/objects.inv doesn't support :func:`repr` or :exc:`Exception` A bug report for Python 2.7's docs. .. _intro: Bug === Running:: sphinx-build -c conf2.7 -n -b html -E . html Produces:: Running Sphinx v1.1.3 loading intersphinx inventory from http://docs.python.org/2.7/objects.inv... building [html]: targets for 1 source files that are out of date updating environment: 1 added, 0 changed, 0 removed reading sources... [100%] bug looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] bug /home/rstuart/zzz/bug.rst:1: WARNING: py:exc reference target not found: Exception /home/rstuart/zzz/bug.rst:1: WARNING: py:func reference target not found: repr writing additional files... genindex search copying static files... done dumping search index... done dumping object inventory... done build succeeded, 2 warnings. Note the ``WARNING`` lines. They should not be there. Running:: sphinx-build -c conf3.2 -b html -n -E . html Produces:: Running Sphinx v1.1.3 loading intersphinx inventory from http://docs.python.org/3.2/objects.inv... building [html]: targets for 1 source files that are out of date updating environment: 1 added, 0 changed, 0 removed reading sources... [100%] bug looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] bug writing additional files... genindex search copying static files... done dumping search index... done dumping object inventory... done build succeeded. I presume this means something is wrong with http://docs.python.org/2.7/objects.inv it downloads. ``conf2.7.py``: .. include:: conf2.7/conf.py :literal: ``conf3.2.py``: .. include:: conf3.2/conf.py :literal: ---------- assignee: docs@python components: Documentation files: bug.rst messages: 186697 nosy: docs@python, ras priority: normal severity: normal status: open title: http://docs.python.org/2.7/objects.inv doesn't support :func:`repr` or :exc:`Exception` versions: Python 2.7 Added file: http://bugs.python.org/file29794/bug.rst _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17709> _______________________________________

4 5

[issue11945] Adopt and document consistent semantics for handling NaN values in containers
by Nick Coghlan July 21, 2014

July 21, 2014

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: The question of the way Python handles NaN came up again on python-dev recently. The current semantics have been assessed as a reasonable compromise, but a poorly explained and inconsistently implemented one. Based on a suggestion from Terry Reedy [1] I propose that a new glossary entry be added for "Reflexive Equality": "Part of the standard mathematical definition of equality is that it is reflexive, that is ``x is y`` necessarily implies that ``x == y``. This is an essential property that is relied upon when designing and implementing container classes such as ``list`` and ``dict``. However, the IEEE754 committee defined the float Not_a_Number (NaN) values as being unequal with all others floats, including themselves. While this design choice violates the basic mathematical definition of equality, it is still considered desirable to be able to correctly implement IEEE754 floating point semantics, and those of similar types such as ``decimal.Decimal``, directly in Python. Accordingly, Python makes the follow compromise in order to cope with types that use non-reflexive definitions of equality without breaking the invariants of container classes that rely on reflexive definitions of equality: 1. Direct equality comparisons involving ``NaN``, such as ``nan=float('NaN'); nan == nan``, follow the IEEE754 rule and return False (or True in the case of ``!=``). This rule applies to ``float`` and ``decimal.Decimal`` within the builtins and standard library. 2. Indirect comparisons conducted internally by container classes, such as ``x in someset`` or ``seq.count(x)`` or ``somedict[x]``, enforce reflexivity by using the expressions ``x is y or x == y`` and ``x is not y and x != y`` respectively rather than assuming that ``x == y`` and ``x != y`` will always respect the reflexivity requirement. This rule applies to all container types within the builtins and standard library that may contain values of arbitrary types. Also see [1] for a more comprehensive theoretical discussion of this topic. [1] http://bertrandmeyer.com/2010/02/06/reflexivity-and-other-pillars-of-civili…" Specific container methods that have currently been identified as relying on the reflexivity assumption are: - __contains__() (for x in c: assert x in c) - __eq__() (assert [x] == [x]) - __ne__() (assert not [x] != [x]) - index() (for x in c: assert 0 <= c.index(x) < len(c)) - count() (for x in c: assert c.count(x) > 0) collections.Sequence and array.array (with the 'f' or 'd' type indicators) have already been identified as container classes in the standard library that fails to follow the second guideline and hence fail to correctly implement the above invariants in the presence of non-reflexive definitions of equality. They will be fixed as part of implementing this patch. Other container types that fail to correctly enforce reflexivity can be fixed as they are identified. [1] http://mail.python.org/pipermail/python-dev/2011-April/110962.html ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 134639 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Adopt and document consistent semantics for handling NaN values in containers type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11945> _______________________________________

8 18

[issue17210] documentation of PyUnicode_Format() states wrong argument type requirements
by Stefan Behnel July 19, 2014

July 19, 2014

New submission from Stefan Behnel: The current documentation says: """ PyObject* PyUnicode_Format(PyObject *format, PyObject *args) Return value: New reference. Return a new string object from format and args; this is analogous to format % args. The args argument must be a tuple. """ According to the implementation, however, "args" can be a tuple, a unicode string, or an arbitrary mapping, i.e. everything that Python's "%" operator allows for strings as well. ---------- assignee: docs@python components: Documentation messages: 182140 nosy: docs@python, scoder priority: normal severity: normal status: open title: documentation of PyUnicode_Format() states wrong argument type requirements type: behavior versions: Python 2.6, Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17210> _______________________________________

3 2

[issue16237] bdist_rpm SPEC files created with distutils may be distro specific
by Nick Coghlan July 16, 2014

July 16, 2014

New submission from Nick Coghlan: In resolving 14443 we effectively embedded the vendor macros in the SPEC file generated by bdist_rpm on older versions of RHEL (and derivatives). While I think that's a necessary evil (in order to create Python 3 RPMs that actually work properly at all on those platforms), we should note the distro limitation somewhere in the documentation: even if the RPM would otherwise work properly on Fedora *and* RHEL (and perhaps even openSUSE), the embedded copy of the vendor post install macros may misfire. ---------- assignee: docs@python components: Documentation messages: 172938 nosy: dmalcolm, docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: bdist_rpm SPEC files created with distutils may be distro specific type: enhancement versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16237> _______________________________________

4 5

[issue15962] Windows STDIN/STDOUT Redirection is actually FIXED
by Nacsa Kristóf July 13, 2014

July 13, 2014

New submission from Nacsa Kristóf: The Python docs faq says that due to a bug in Windows NT's cmd.exe, the output redirection and piping won't work when started from file extension. http://docs.python.org/faq/windows.html#how-do-i-make-python-scripts-execut… http://docs.python.org/py3k/faq/windows.html#how-do-i-make-python-scripts-e… This is actually fixed in Windows, but the fix is disabled by default, and you need to enable it in regedit, the keyword is "InheritConsoleHandles". Proof & Details: http://support.microsoft.com/default.aspx?kbid=321788 It would be great if the docs could refer to this fix, as the docs is the major source of information for many. ---------- assignee: docs@python components: Documentation, Installation, Windows messages: 170641 nosy: Nacsa.Kristóf, docs@python priority: normal severity: normal status: open title: Windows STDIN/STDOUT Redirection is actually FIXED 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/issue15962> _______________________________________

6 6

[issue12842] Docs: first parameter of tp_richcompare() always has the correct type
by Stefan Krah July 3, 2014

July 3, 2014

New submission from Stefan Krah <stefan-usenet(a)bytereef.org>: I've noticed that assumptions about the operand types in tp_richcompare() are not always consistent. As far as I can see, the first parameter in tp_richcompare() is guaranteed to be of the correct type. But in some places the first parameter's type is still checked: Objects/cellobject.c: if (!PyCell_Check(a) || !PyCell_Check(b)) { The attached patch makes it clear that the first parameter has the correct type. ---------- assignee: docs@python components: Documentation files: tp_richcompare.diff keywords: patch messages: 142991 nosy: docs@python, skrah priority: normal severity: normal status: open title: Docs: first parameter of tp_richcompare() always has the correct type type: feature request versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file23047/tp_richcompare.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12842> _______________________________________

4 3

[issue11389] unittest: no way to control verbosity of doctests from cmd
by anatoly techtonik July 2, 2014

July 2, 2014

New submission from anatoly techtonik <techtonik(a)gmail.com>: I can't find a way to execute DocTests contained in a separate README.txt file using unittest.main() function. That doesn't allow to control verbosity for debugging. I am doing it this way in the tests.py import doctest import unittest if __name__ == '__main__': runner = unittest.TextTestRunner() runner.run(doctest.DocFileSuite('README.txt', optionflags=doctest.ELLIPSIS)) I could find a way to subclass TestLoader.loadTestsFromNames() by looking at the source code of undocumented TestProgram. I'd like to see this use case at least covered by documentation if not properly developed for stdlib of Python4. ---------- assignee: docs@python components: Documentation, Tests messages: 130001 nosy: docs@python, techtonik priority: normal severity: normal status: open title: unittest: no way to control verbosity of doctests from cmd _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11389> _______________________________________

4 6

[issue14097] Improve the "introduction" page of the tutorial
by Ezio Melotti July 2, 2014

July 2, 2014

New submission from Ezio Melotti <ezio.melotti(a)gmail.com>: I was reading the "introduction" page of the tutorial [0], and noticed a few things that could be improved: 1) the first paragraph is a bit confusing, showing a simple example and explaining what the >>> is would be better; 2) comments can be introduced later too, they are not really necessary at the beginning; 3) the first example is supposed to introduce numbers and basic operations, but it's still going on with the comments; 4) the note about floating point issues is not so relevant anymore nowadays, so it could be (re)moved; 5) "A value can be assigned to several variables simultaneously:" is not technically correct; 6) "Variables must be “defined” (assigned a value) before they can be used" this might be improved too; 7) almost half of the section about numbers goes on explaining complex numbers. This is totally unnecessary here, I think that mentioning them and maybe showing a simple example is more than enough. Another option is to make a subsection with a note that says that the section can be skipped; 8) the examples in this part lack some space (e.g. "a=3.0+4.0j"); 9) the print() function could get a better introduction and used in the first set of string examples; 10) suggesting to use continuation lines with a trailing \ in string literals is not a good idea, it's better to use """...""" or implicit concatenation inside (); 11) "Degenerate slice indices are handled gracefully" it might be better to show that it's not the same for "non-slice" indices; 12) the "About Unicode" section could link to the Unicode HOWTO; 13) while it's true that lists can contain different types of object, they usually shouldn't; 14) while the "while" example is good (it first shows a piece of code and then explains what it does), I would introduce the "if" and the "for" first. The "while" is arguably the most complex and less used of the three statements. [0]: http://docs.python.org/py3k/tutorial/introduction.html ---------- assignee: docs@python components: Documentation messages: 154051 nosy: docs@python, eli.bendersky, eric.araujo, ezio.melotti, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Improve the "introduction" page of the tutorial type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14097> _______________________________________

11 35

[issue11762] Ast doc: warning and version number
by Terry J. Reedy June 30, 2014

June 30, 2014

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: Two related proposals. 1. Add a warning similar to the one for the dis module. As modified: "CPython implementation detail: The ast definition is specific to the CPython interpreter! Ast nodes may be added, removed, or changed between versions. Use *ast.__version__* to work across versions." I omitted " Use of this module should not be considered to work across Python VMs or Python releases." as redundant and too legalistic. *ast.__version__* should link to its (new) entry). 2. Add a full entry for __version__. Currently (3.2): "The module defines a string constant __version__ which is the decimal Subversion revision number of the file shown below." Proposed replacement (with hidden reference point): ast.__version__ [__version__ in normal entry boldface] String constant with version number of abstract grammar file. 3.1: 67616; 3.2: 82163; 3.3: xxxxxxxxx ---------- assignee: docs@python components: Documentation messages: 132951 nosy: docs@python, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Ast doc: warning and version number versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11762> _______________________________________

6 9

Documentation error in function getaddrinfo in socket module
by Krishna Kumar Thakur June 30, 2014

June 30, 2014

Hi, python version : 3.3.0 Description : getaddrinfo() function expecting 'type' as the keyword argument but the function documentation says 'socktype' . please see the below output >>> help(getaddrinfo) Help on built-in function getaddrinfo in module _socket: getaddrinfo(...) getaddrinfo(host, port [, family, socktype, proto, flags]) -> list of (family, socktype, proto, canonname, sockaddr) >>> getaddrinfo.__doc__ 'getaddrinfo(host, port [, family, socktype, proto, flags])\n -> list of (family, socktype, proto, canonname, sockaddr)\n\nResolve host and port into addrinfo struct.' so if the function is called >>> i = getaddrinfo('www.python.org','http',socktype = SOCK_STREAM) Traceback (most recent call last): File "<pyshell#20>", line 1, in <module> i = getaddrinfo('www.python.org','http',socktype = SOCK_STREAM) TypeError: 'socktype' is an invalid keyword argument for this function then I have found the correct keyword argument as 'type' in python 3.3 official documentation. Its not the major issue but sometimes it confuses. As I appreciate python, so I felt its my duty to help make this language error free as much as possible. :) ________________________________ Thank You Krishna Kumar Thakur Contact: +91-7411251885 E_mail: krishnak.thakur(a)yahoo.com

2 1

[issue11385] TextTestRunner methods are not documented
by anatoly techtonik June 27, 2014

June 27, 2014

New submission from anatoly techtonik <techtonik(a)gmail.com>: TextTestRunner has a run method, which is not documented. It is also is not clear how to add suite to TextTestRunner to be executed later by unittest.main() ---------- assignee: docs@python components: Documentation, Tests messages: 129988 nosy: docs@python, techtonik priority: normal severity: normal status: open title: TextTestRunner methods are not documented versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11385> _______________________________________

6 10

[issue15588] quopri: encodestring and decodestring handle bytes, not strings
by patrick vrijlandt June 25, 2014

June 25, 2014

New submission from patrick vrijlandt: quopri.py's functions encodestring and decodestring are documented to handle strings; and this is clearly suggested by their name. However, these functions accept and return bytes, not strings. This should be reflected in the documentation. Even better: deprecate these functions and introduce new ones with behaviour as suggested by their names: encode_string, encode_bytes etc. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 167672 nosy: docs@python, patrick.vrijlandt priority: normal severity: normal status: open title: quopri: encodestring and decodestring handle bytes, not strings type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15588> _______________________________________

6 8

[issue14013] tarfile should expose supported formats
by Éric Araujo June 23, 2014

June 23, 2014

New submission from Éric Araujo <merwok(a)netwok.org>: shutil contains high-level functions to create a zipfile or a tarball. When a new format is added to the tarfile module, then shutil needs to be updated manually. If tarfile exposed the names of the compressors it supports, then shutil could just automatically support everything that tarfile supports instead of having to re-do import dances for optional modules (bz2, lzma, zlib) and also duplicate formats in its doc. This may also be useful for other code wanting to do some introspection. Attached patch implements tarfile.formats, a list of strings (I thought about using a frozenset but then followed the precedent set by the 3.3 crypt module). Tests and docs not updated, I wanted to get Lars’ approval on the principle first. One could argue that this is not needed: compression modules are not added often; updating shutil after updating tarfile is not hard; it is not that useful to have access to the list of supported formats. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 153350 nosy: docs@python, eric.araujo, lars.gustaebel, nadeem.vawda priority: normal severity: normal stage: patch review status: open title: tarfile should expose supported formats type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14013> _______________________________________

3 4

[issue13779] os.walk: bottom-up
by patrick vrijlandt June 16, 2014

June 16, 2014

New submission from patrick vrijlandt <patrick.vrijlandt(a)gmail.com>: PythonWin 3.2 (r32:88445, Feb 20 2011, 21:29:02) [MSC v.1500 32 bit (Intel)] on win32. Portions Copyright 1994-2008 Mark Hammond - see 'Help/About PythonWin' for further copyright information. >>> import os >>> os.makedirs("g:/a/b/c") >>> os.listdir("g:/a") ['b'] >>> for root, dirs, files in os.walk("g:/a", topdown = False): ... print(root, dirs, files, os.listdir(root)) ... os.rmdir(root) ... g:/a\b\c [] [] [] g:/a\b ['c'] [] [] g:/a ['b'] [] [] >>> >From the documentation of os.walk: If topdown is False, the triple for a directory is generated after the triples for all of its subdirectories (directories are generated bottom-up). As the above example shows, the directories are generated in the correct order, "generated" referring to yield from generator os.walk. However, the generated (files? and) dirs do not necessarily reflect the current situation as produced by os.listdir. Therefore, this does not clear the entire directory tree as I would expect. >>> os.makedirs("g:/a/b/c") >>> for root, dirs, files in os.walk("g:/a", topdown = False): ... print(root, dirs, files, os.listdir(root)) ... if not (files + dirs): ... os.rmdir(root) ... g:/a\b\c [] [] [] g:/a\b ['c'] [] [] g:/a ['b'] [] ['b'] I think that at least the documentation should be more clear on this issue. I would like even better, if files + dirs would match os.listdir on the moment they are generated (=yielded). ---------- assignee: docs@python components: Documentation messages: 151169 nosy: docs@python, patrick.vrijlandt priority: normal severity: normal status: open title: os.walk: bottom-up type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13779> _______________________________________

6 10

[issue12617] Mutable Sequence Type can work not only with iterable in slice[i:j] = t
by py.user June 14, 2014

June 14, 2014

New submission from py.user <port139(a)yandex.ru>: 1) 4.6.4 Mutable Sequence Types | s[i:j] = t | slice of s from i to j is replaced | | | by the contents of the iterable t | >>> lst = list('abc') >>> barr = bytearray(b'abc') >>> lst[:1] = 4 Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: can only assign an iterable >>> barr[:1] = 4 >>> barr bytearray(b'\x00\x00\x00\x00bc') >>> there is no info about this feature in the documentation 2) 4.6.4 Mutable Sequence Types | s.extend(x) | same as s[len(s):len(s)] = x | >>> lst = list('abc') >>> barr = bytearray(b'abc') >>> lst.extend(4) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: 'int' object is not iterable >>> barr.extend(4) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: 'int' object is not iterable >>> lst[len(lst):len(lst)] = 4 Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: can only assign an iterable >>> barr[len(barr):len(barr)] = 4 >>> barr bytearray(b'abc\x00\x00\x00\x00') >>> barr.extend(x) != barr[len(barr):len(barr)] = x ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 140924 nosy: docs@python, py.user priority: normal severity: normal status: open title: Mutable Sequence Type can work not only with iterable in slice[i:j] = t type: behavior versions: Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12617> _______________________________________

6 5

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

June 7, 2014

New submission from Giampaolo Rodola' <g.rodola(a)gmail.com>: http://docs.python.org/library/os.html#os.getuid os.getuid() documentation just states: > Return the current process’s user id. It is not clear, however, whether "user id" refers to real, effective or saved user id. As per: http://linux.about.com/library/cmd/blcmdl2_getuid.htm ...it should refer to _real_ user id. ---------- assignee: docs@python components: Documentation messages: 122117 nosy: docs@python, giampaolo.rodola priority: normal severity: normal status: open title: os.getuid() documentation should be clear on what kind of uid it is referring versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10503> _______________________________________

5 6

[issue16774] Additional recipes for itertools docs
by Alexey Kachayev May 26, 2014

May 26, 2014

New submission from Alexey Kachayev: Additional recipes for itertools documentation (widespread functions in other programming languages): * drop * split-at * split-by ---------- assignee: docs@python components: Documentation files: itertools.doc.diff keywords: patch messages: 178098 nosy: asvetlov, docs@python, kachayev priority: normal severity: normal status: open title: Additional recipes for itertools docs versions: Python 3.4 Added file: http://bugs.python.org/file28427/itertools.doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16774> _______________________________________

5 9

[issue15871] Online docs: make index search always available.
by Terry J. Reedy May 13, 2014

May 13, 2014

New submission from Terry J. Reedy: For the Windows Help version of the docs, the left side box has 4 tabs: Contents, Index, Search, Favorites. I now mostly use the Index tab. That means that I can enter an indexed keyword, topic, or object name and jump from place to place in the docs. The left margin of the online docs only has a text search box equivalent to the Windows search tab (which I essentially never use). The index is only available on the front page, possibly not even visible without scrolling. Consequently, people, especially beginners, tend to use the text search box when they should be using the index. The result is often useless. The issue came up on python-list about a beginner entering 'print' and getting nothing useful. With the Windows doc, 'print' in the index search immediately brings up print (builtin function) (twice, I did not look into why). The same thing in the search lists 153 pages, with the builtin functions page at 75. Not too surprising, as it is a long page with only 3 occurrences of 'print'. Also not useful. So I think the online docs should also have an always available index search box in addition to the text search box (which should be properly labeled as such). 'Enter a module, class, for function name.' should be applied to index search, not text search. An alternative is for the one box to give both index search results and text search results, but doing the latter when one only wants the former is a waste of both server and reader resources. ---------- assignee: docs@python components: Documentation messages: 169930 nosy: docs@python, eric.araujo, ezio.melotti, georg.brandl, terry.reedy priority: normal severity: normal status: open title: Online docs: make index search always available. type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15871> _______________________________________

7 14

[issue13030] Be more generic when identifying the Windows main dir in installation doc
by Sandro Tosi May 6, 2014

May 6, 2014

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: Given I have no knowledge of the windows system, I'm just proxying http://mail.python.org/pipermail/docs/2011-September/005793.html : >>> Under: http://docs.python.org/install/index.html#inst-how-install-works It notes "Windows prefix\Lib\site-packages C:\PythonXY\Lib\site-packages" for default values on Windows. In the paragraph following the table is the text: "prefix and exec-prefix stand for the directories that Python is installed to, and where it finds its libraries at run-time. They are always the same under Windows, and very often the same under Unix and Mac OS X. " I don't know if it's hardcoded into Python distributions to use C, but it's not correct. The correct way to identify what most people think of as C is via the %SYSTEMROOT% environment variable, so the path described would be "%SYSTEMROOT%\PythonXY\Lib\site-packages" (This is still not the correct way to do things on Windows, but it at least shouldn't break on systems with a %SYSTEMROOT% other than C. I've seen configurations like that on systems which boot multiple versions of Windows.) <<< ---------- assignee: docs@python components: Documentation messages: 144422 nosy: brian.curtin, docs@python, sandro.tosi, tim.golden priority: normal severity: normal stage: needs patch status: open title: Be more generic when identifying the Windows main dir in installation doc type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13030> _______________________________________

4 5

[issue17386] Bring Doc/make.bat as close to Doc/Makefile as possible
by Zachary Ware April 29, 2014

April 29, 2014

New submission from Zachary Ware: I have found Doc/make.bat to be very useful, but I have hit a few of its limitations now and then. Thus, I have made extensive modifications to bring it much closer to the way Doc/Makefile works. Among the things changed in the attached patch: - Use pushd/popd to make sure everything is done in the Doc directory. - Allow variables to be set on the command line, e.g.: make html "PYTHON2=python" - Set PYTHON2 and PYTHON3 variables separately; the Sphinx version and associated tools we're currently using want Python 2, which defaults to "py -2". Other tools, like Tools/scripts/serve.py (the make serve target), expect Python 3; setting the default PYTHON3 searches for python(_d).exe in PCbuild(\amd64), and falls back to "py -3" if not found. - Set the HTML Help Workshop default path to %ProgramFiles(x86)%\..., if that variable is defined. (If I understand correctly, that variable is only defined on x64 installations, and in cases where it is not defined on x64, %ProgramFiles% silently copies %ProgramFiles(x86)%.) - Convert target choice to a single for loop, rather than several lines of if. Anything not in the list falls through to the help message. - Expand the help message to match the message given by Doc/Makefile - Add the "clean" target, which does the same as Makefile - Reimplement "update" to match Makefile (call clean, call checkout. I do wonder if maybe it should be done the other way around, though; reimplement Makfile's "update" target to simply update the svn checkouts, rather than re-pull them) - Add separate labels for each target. The old method of sending everything to :build was very clever and kept the file short, but limited flexibility. It's also nice to get a message at the end (matching Makefile), which is much easier to do with separate labels. - Add support for the PAPER environment variable in LaTeX building. - Add coverage, doctest, pydoc-topics, dist, check, and serve targets. "dist" cannot be completed in the same way with default tools on Windows, so all it does is build html, text, latex (a4 and letter), and epub and copy them into the dist directory. - checkout checks for the existence of the checked out packages before checking out - build calls checkout before building, so you can go right to "make html" instead of having to do "make checkout && make html" - Add support for SOURCES and SPHINXOPTS environment variables. Everything seems to work for me, but I've only been able to test on Windows 7 (32 and 64 bit). I don't believe there's anything in there that doesn't exist in XP, though. Also, since this version of the file has a lot of labels, this patch does somewhat rely on resolution of issue 17202. It should probably work without any changes to .hgeol, but that can't be guaranteed. There are a couple of drawbacks to the patched version; it's a much longer file, and it does lose a good chunk of the elegance of the original solution. If anyone has any suggestions for regaining some of that elegance without losing any of the functionality, I am of course all ears :). In particular, I'm not a huge fan of having to have "pushd ." at the beginning of every label, but the only other solutions I came up with involved setting and unsetting a "DISALLOW_POPD" variable in several places, and a condition on the popd at :end, or forgetting the pushd/popd thing entirely. I'm looking forward to hearing what anyone else thinks of this, positive or negative :) ---------- assignee: docs@python components: Build, Documentation, Windows files: win_doc_make.diff keywords: patch messages: 183768 nosy: christian.heimes, docs@python, zach.ware priority: normal severity: normal status: open title: Bring Doc/make.bat as close to Doc/Makefile as possible type: enhancement versions: Python 3.4 Added file: http://bugs.python.org/file29353/win_doc_make.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17386> _______________________________________

4 18

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

April 28, 2014

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

6 8

[issue18243] mktime_tz documentation out-of-date
by Jakub Wilk April 26, 2014

April 26, 2014

New submission from Jakub Wilk: email.utils.mktime_tz documentations says: "Minor deficiency: mktime_tz() interprets the first 8 elements of tuple as a local time and then compensates for the timezone difference. This may yield a slight error around changes in daylight savings time, though not worth worrying about for common use." But now that issue #14653 is fixed, this is no longer true. ---------- assignee: docs@python components: Documentation messages: 191346 nosy: docs@python, jwilk priority: normal severity: normal status: open title: mktime_tz documentation out-of-date _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18243> _______________________________________

5 5

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

April 19, 2014

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

9 21

[issue18229] attribute headers of http.server.BaseHTTPRequestHandler sometimes does not exists
by Jordan Szubert April 16, 2014

April 16, 2014

New submission from Jordan Szubert: it seems that problem is someone connecting to port 8080 with non-http client, could not find warning in documentation ---fragment of `less access.log`------------ 81.172.30.254 - - [16/Jun/2013 11:36:58] "^SBitTorrent protocol^@^@^@^@^@^X^@^Ej 81.172.30.254 - - [16/Jun/2013 11:38:11] "^N<U+008E>^@f¸ãÄòQ;³x<U+0092>b^C^HÄA7 81.172.30.254 - - [16/Jun/2013 11:39:22] "^SBitTorrent protocol^@^@^@^@^@^X^@^Ej 81.172.30.254 - - [16/Jun/2013 11:40:35] "Ã<U+008D>¬0æz<U+0093>zr^D<U+009B>2]WQ Exception happened during processing of request from ('81.172.30.254', 63650) Traceback (most recent call last): File "c:\Python33\lib\socketserver.py", line 306, in _handle_request_noblock self.process_request(request, client_address) File "c:\Python33\lib\socketserver.py", line 332, in process_request self.finish_request(request, client_address) File "c:\Python33\lib\socketserver.py", line 345, in finish_request self.RequestHandlerClass(request, client_address, self) File "c:\Python33\lib\socketserver.py", line 666, in __init__ self.handle() File "c:\Python33\lib\http\server.py", line 400, in handle self.handle_one_request() File "c:\Python33\lib\http\server.py", line 380, in handle_one_request if not self.parse_request(): File "c:\Python33\lib\http\server.py", line 283, in parse_request self.send_error(400, "Bad request version (%r)" % version) File "c:\Python33\lib\http\server.py", line 428, in send_error self.send_response(code, message) File "c:\Python33\lib\http\server.py", line 443, in send_response self.log_request(code) File "c:\Users\joru\Dropbox\programowanie\demoniszcze\server\_lowerHTTP.py", line 30, in log_request xff=req.headers.get('X-Forwarded-For') AttributeError: '_HNDL_3' object has no attribute 'headers' # _HNLD_3 derives from http.server.BaseHTTPRequestHandler ---------- assignee: docs@python components: Documentation messages: 191264 nosy: docs@python, joru priority: normal severity: normal status: open title: attribute headers of http.server.BaseHTTPRequestHandler sometimes does not exists type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18229> _______________________________________

5 7

[issue15840] Ambiguity with regard to the effect of accessing a closed IOBase instance
by Alexander Konovalenko April 16, 2014

April 16, 2014

New submission from Alexander Konovalenko: Two pieces of the documentation for io.IOBase seem to contradict each other: At http://docs.python.org/library/io.html#io.IOBase: "Note that calling any method (even inquiries) on a closed stream is undefined. Implementations may raise IOError in this case." At http://docs.python.org/library/io.html#io.IOBase.close: "Once the file is closed, any operation on the file (e.g. reading or writing) will raise a ValueError." Perhaps the confusion arises in part because it is not clear when a requirement for all IOBase implementations is documented and when the docs merely describe the default behavior of IOBase that implementations are free to override. Those passages are inconsistent on two points: 1) IOError and ValueError are not subclasses one of another. So what should we expect an IOBase implementation to raise? 2) Undefined behavior means literally anything can happen. Technically, that means calling read() or readable() on a closed file (or other kind of stream) could wreak havoc in a totally unrelated part of the system or segfault the Python interpreter. That is definitely a thing to carefully avoid in any production systems. On the other hand, raising an exception, even if we don't know in advance whether it will be ValueError or IOError, is pretty much defined behavior. An exception is easy to deal with and to contain inside a module. So please clarify how dangerous it actually is to access an IOBase stream after it has been closed. ---------- assignee: docs@python components: Documentation messages: 169660 nosy: alexkon, docs@python priority: normal severity: normal status: open title: Ambiguity with regard to the effect of accessing a closed IOBase instance versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15840> _______________________________________

8 12

[issue16278] os.rename documentation slightly inaccurate
by David Benjamin April 14, 2014

April 14, 2014

New submission from David Benjamin: This is somewhat of a nitpick. os.rename's documentation says "If dst is a directory, OSError will be raised". On Unix, this isn't completely true. If the source is a directory and the destination is an empty directory, it'll overwrite the former with the latter. (Actually if the source is a directory the inverse is true; if dst is a file, OSError will be raised.) In [1]: import os In [2]: os.mkdir("aaa") In [3]: open("aaa/blah", "w").close() In [4]: os.mkdir("bbb") In [5]: os.rename("aaa", "bbb") In [6]: os.listdir("bbb") Out[6]: ['blah'] ---------- assignee: docs@python components: Documentation messages: 173285 nosy: David.Benjamin, docs@python priority: normal severity: normal status: open title: os.rename documentation slightly inaccurate type: enhancement versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16278> _______________________________________

9 44

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

April 14, 2014

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

4 5

[issue15067] sqlite3 docs reference PEP 246, which was rejected
by Zachary Ware April 1, 2014

April 1, 2014

New submission from Zachary Ware <zachary.ware(a)gmail.com>: See: http://hg.python.org/cpython/file/d31e83497c5a/Doc/library/sqlite3.rst#l708 PEP 246 is headed by: """ Rejection Notice I'm rejecting this PEP. Something much better is about to happen; it's too early to say exactly what, but it's not going to resemble the proposal in this PEP too closely so it's better to start a new PEP. GvR. """ I don't know what the "something much better" was/is, so I have no idea how that line in the docs should be replaced, but I don't think the PEP 246 reference is valid. Thanks, Zach ---------- assignee: docs@python components: Documentation messages: 162797 nosy: docs@python, ghaering, zach.ware priority: normal severity: normal status: open title: sqlite3 docs reference PEP 246, which was rejected versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15067> _______________________________________

4 12

[issue12209] Minor edits to faulthandler doc
by Éric Araujo March 25, 2014

March 25, 2014

New submission from Éric Araujo <merwok(a)netwok.org>: I made some grammar fixes in faulthandler.rst and tweaked the example to better show what the module does. I’d like to fix the synopsis too: “dump the Python traceback” is not very clear to me. It is the traceback or the stack trace? Why is it called “the” traceback? Something like “dumping the stack trace on CPython crashes” would be better IMO. ---------- assignee: docs@python components: Documentation files: faulthandler-doc.diff keywords: needs review, patch messages: 137206 nosy: docs@python, eric.araujo, haypo priority: normal severity: normal stage: patch review status: open title: Minor edits to faulthandler doc versions: Python 3.3 Added file: http://bugs.python.org/file22177/faulthandler-doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12209> _______________________________________

3 7

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

March 24, 2014

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

5 5

[issue13437] Provide links to the source code for every module in the documentation
by Julian Berman March 19, 2014

March 19, 2014

New submission from Julian Berman <Julian+Python.org(a)GrayVines.com>: The documentation occasionally contains a link to the source code for a module in the stdlib. See for instance http://docs.python.org/library/urlparse.html and http://docs.python.org/library/collections.html , or many others. With a quick perusal, I couldn't immediately guess as to which ones managed to have one and which ones don't, but it'd be convenient to have a link in as many places as possible, which is certainly more than we have now. (See e.g. http://docs.python.org/library/json.html and http://docs.python.org/library/itertools.html and many others for examples of pages that lack a link). Perhaps putting it in a more conspicuous but still consistent location would be reasonable (the sidebar?). ---------- assignee: docs@python components: Documentation messages: 147973 nosy: Julian, docs@python priority: normal severity: normal status: open title: Provide links to the source code for every module in the documentation type: feature request versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13437> _______________________________________

6 14

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

March 16, 2014

New submission from Ryan Kelly <ryan(a)rfk.id.au>: The docs for HTTPConnection.set_tunnel(host,port) are ambiguous. They simply say "Set the host and the port for HTTP Connect Tunnelling". But should I specify the address of the server *through* which I want to tunnel, or the address of the *endpoint* of the tunnel? Turns out it's the latter, but I just wasted an hour "debugging" thinking it was the former :-( Attached is a simple doc patch to try to clarify this issue. ---------- assignee: docs@python components: Documentation files: set_tunnel_doc.diff keywords: patch messages: 130396 nosy: docs@python, rfk priority: normal severity: normal status: open title: docs for HTTPConnection.set_tunnel are ambiguous versions: Python 3.3 Added file: http://bugs.python.org/file21056/set_tunnel_doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11448> _______________________________________

8 14

[issue16665] doc for builtin hex() is poor
by rurpy the second March 16, 2014

March 16, 2014

New submission from rurpy the second: The documentation of the hex() builtin function is poor. Specifically it does not say (directly) that: 1. The resulting string is prefixed with "0x". 2. Any a-f characters used are lower case. 3. Negative integers are converted by prefixing a minus sign to hex() of the absolute value of the argument. 4. It should have a cross reference to the %x format of the "%" operator with a note that it is more veratile than the hex() builtin. 5. It should have a cross reference to the way of performing the inverse operation: hex->int I am not a good writer but here is an attempt at improving it: -------- Convert an integer number to a hexadecimal string. The resulting string is prefixed with "0x" and any alpha characters a-f are lowercase ascii. Negative integers are converted to hex(abs(x)) prefixed with "-". In all cases the result is a valid Python expression. If x is not a Python int object, it has to define an __index__() method that returns an integer. Note: For another more flexible way of converting an integer to hexadecimal see the "x" and "X" conversion types in link:[4.7.2 - printf-style String Formatting] and link:[6.1.3.1 - Format Specification Mini-Language] Note: To convert a hexadecimal string to an integer, use link:[int()] with a radix argument of 16. Note: To obtain a hexadecimal string representation for a float, use the link:[float.hex()] method. -------- ---------- assignee: docs@python components: Documentation messages: 177352 nosy: docs@python, rurpy2 priority: normal severity: normal status: open title: doc for builtin hex() is poor 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/issue16665> _______________________________________

11 16

[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

[issue16805] when building docs on Debian 7 --> ERROR: Error in "note" directive
by Tshepang Lekhonkhobe March 13, 2014

March 13, 2014

New submission from Tshepang Lekhonkhobe: I am running Debian 7, which has sphinx is1.1.3+dfsg-4. When I run $ python tools/sphinx-build.py -bhtml . build/ I get a whole bunch of errors: Making output directory... Running Sphinx v1.1.3 loading pickled environment... not yet created building [html]: targets for 435 source files that are out of date updating environment: 435 added, 0 changed, 0 removed reading sources... [100%] whatsnew/index /home/wena/src/python/cpython/Doc/c-api/arg.rst:47: ERROR: Error in "note" directive: invalid option block. .. note:: For all ``#`` variants of formats (``s#``, ``y#``, etc.), the type of the length argument (int or :c:type:`Py_ssize_t`) is controlled by defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including :file:`Python.h`. If the macro was defined, length is a :c:type:`Py_ssize_t` rather than an :c:type:`int`. This behavior will change in a future Python version to only support :c:type:`Py_ssize_t` and drop :c:type:`int` support. It is best to always define :c:macro:`PY_SSIZE_T_CLEAN`. /home/wena/src/python/cpython/Doc/c-api/init.rst:547: ERROR: Error in "note" directive: invalid option block. .. note:: When only the main thread exists, no GIL operations are needed. This is a common situation (most Python programs do not use threads), and the lock operations slow the interpreter down a bit. Therefore, the lock is not created initially. This situation is equivalent to having acquired the lock: when there is only a single thread, all object accesses are safe. Therefore, when this function initializes the global interpreter lock, it also acquires it. Before the Python :mod:`_thread` module creates a new thread, knowing that either it has the lock or the lock hasn't been created yet, it calls :c:func:`PyEval_InitThreads`. When this call returns, it is guaranteed that the lock has been created and that the calling thread has acquired it. It is **not** safe to call this function when it is unknown which thread (if any) currently has the global interpreter lock. This function is not available when thread support is disabled at compile time. /home/wena/src/python/cpython/Doc/faq/library.rst:513: ERROR: Error in "note" directive: invalid option block. .. note:: To read and write binary data, it is mandatory to open the file in binary mode (here, passing ``"rb"`` to :func:`open`). If you use ``"r"`` instead (the default), the file will be open in text mode and ``f.read()`` will return :class:`str` objects rather than :class:`bytes` objects. /home/wena/src/python/cpython/Doc/library/fractions.rst:93: ERROR: Error in "note" directive: invalid option block. .. note:: From Python 3.2 onwards, you can also construct a :class:`Fraction` instance directly from a :class:`float`. /home/wena/src/python/cpython/Doc/library/fractions.rst:102: ERROR: Error in "note" directive: invalid option block. .. note:: From Python 3.2 onwards, you can also construct a :class:`Fraction` instance directly from a :class:`decimal.Decimal` instance. /home/wena/src/python/cpython/Doc/library/getopt.rst:12: ERROR: Error in "note" directive: invalid option block. .. note:: The :mod:`getopt` module is a parser for command line options whose API is designed to be familiar to users of the C :c:func:`getopt` function. Users who are unfamiliar with the C :c:func:`getopt` function or who would like to write less code and get better help and error messages should consider using the :mod:`argparse` module instead. /home/wena/src/python/cpython/Doc/library/io.rst:678: ERROR: Error in "warning" directive: invalid option block. .. warning:: :class:`BufferedRWPair` does not attempt to synchronize accesses to its underlying raw streams. You should not pass it the same object as reader and writer; use :class:`BufferedRandom` instead. /home/wena/src/python/cpython/Doc/library/logging.config.rst:144: ERROR: Error in "note" directive: invalid option block. .. note:: Because portions of the configuration are passed through :func:`eval`, use of this function may open its users to a security risk. While the function only binds to a socket on ``localhost``, and so does not accept connections from remote machines, there are scenarios where untrusted code could be run under the account of the process which calls :func:`listen`. Specifically, if the process calling :func:`listen` runs on a multi-user machine where users cannot trust each other, then a malicious user could arrange to run essentially arbitrary code in a victim user's process, simply by connecting to the victim's :func:`listen` socket and sending a configuration which runs whatever code the attacker wants to have executed in the victim's process. This is especially easy to do if the default port is used, but not hard even if a different port is used). To avoid the risk of this happening, use the ``verify`` argument to :func:`listen` to prevent unrecognised configurations from being applied. /home/wena/src/python/cpython/Doc/library/logging.config.rst:747: ERROR: Error in "note" directive: invalid option block. .. note:: Due to the use of :func:`eval` as described above, there are potential security risks which result from using the :func:`listen` to send and receive configurations via sockets. The risks are limited to where multiple users with no mutual trust run code on the same machine; see the :func:`listen` documentation for more information. /home/wena/src/python/cpython/Doc/library/os.rst:263: ERROR: Error in "note" directive: invalid option block. .. note:: On Mac OS X, :func:`getgroups` behavior differs somewhat from other Unix platforms. If the Python interpreter was built with a deployment target of :const:`10.5` or earlier, :func:`getgroups` returns the list of effective group ids associated with the current user process; this list is limited to a system-defined number of entries, typically 16, and may be modified by calls to :func:`setgroups` if suitably privileged. If built with a deployment target greater than :const:`10.5`, :func:`getgroups` returns the current group access list for the user associated with the effective user id of the process; the group access list may change over the lifetime of the process, it is not affected by calls to :func:`setgroups`, and its length is not limited to 16. The deployment target value, :const:`MACOSX_DEPLOYMENT_TARGET`, can be obtained with :func:`sysconfig.get_config_var`. /home/wena/src/python/cpython/Doc/library/pkgutil.rst:148: ERROR: Error in "note" directive: invalid option block. .. note:: Only works for a :term:`finder` which defines an ``iter_modules()`` method. This interface is non-standard, so the module also provides implementations for :class:`importlib.machinery.FileFinder` and :class:`zipimport.zipimporter`. /home/wena/src/python/cpython/Doc/library/pkgutil.rst:186: ERROR: Error in "note" directive: invalid option block. .. note:: Only works for a :term:`finder` which defines an ``iter_modules()`` method. This interface is non-standard, so the module also provides implementations for :class:`importlib.machinery.FileFinder` and :class:`zipimport.zipimporter`. /home/wena/src/python/cpython/Doc/library/socket.rst:728: ERROR: Error in "note" directive: invalid option block. .. note:: :meth:`close()` releases the resource associated with a connection but does not necessarily close the connection immediately. If you want to close the connection in a timely fashion, call :meth:`shutdown()` before :meth:`close()`. /home/wena/src/python/cpython/Doc/library/ssl.rst:609: ERROR: Error in "note" directive: invalid option block. .. note:: To validate a certificate for a particular service, you can use the :func:`match_hostname` function. /home/wena/src/python/cpython/Doc/library/sys.rst:245: ERROR: Error in "note" directive: invalid option block. .. note:: If a :ref:`virtual environment <venv-def>` is in effect, this value will be changed in ``site.py`` to point to the virtual environment. The value for the Python installation will still be available, via :data:`base_exec_prefix`. /home/wena/src/python/cpython/Doc/library/test.rst:201: ERROR: Error in "note" directive: invalid option block. .. note:: :mod:`test.support` is not a public module. It is documented here to help Python developers write tests. The API of this module is subject to change without backwards compatibility concerns between releases. looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] whatsnew/index writing additional files... genindex py-modindex search download index opensearch copying images... [100%] library/turtle-star.png copying static files... done dumping search index... done dumping object inventory... done build succeeded, 16 warnings. ---------- assignee: docs@python components: Documentation messages: 178443 nosy: docs@python, tshepang priority: normal severity: normal status: open title: when building docs on Debian 7 --> ERROR: Error in "note" directive versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16805> _______________________________________

7 27

[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

[issue17727] document that some distributions change site.py defaults
by Georg Brandl Jan. 29, 2014

Jan. 29, 2014

New submission from Georg Brandl: >From the docs@ list: """ Dear all, the first paragraph of the documentation for the site module states that site.py constructs four directories using a head and tail part, and that one of the tail parts would be lib/pythonX.Y/site-packages on UNIX/Mac. However, in my Python 3.2 installation on Ubuntu 12.04 this is actually lib/python3/dist-packages (so no .Y and a different subdirectory) ! This is also stated in the module’s doc string. I don’t know why the Python documentation says something else, but that should be fixed. """ Attached a patch to explain why the defaults may look different on some distributions. Please review. ---------- assignee: docs@python components: Documentation files: site-patch.diff keywords: patch messages: 186897 nosy: barry, docs@python, doko, georg.brandl priority: normal severity: normal stage: patch review status: open title: document that some distributions change site.py defaults type: enhancement versions: Python 2.7, Python 3.3, Python 3.4 Added file: http://bugs.python.org/file29849/site-patch.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17727> _______________________________________

2 2

[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

[issue17811] Improve os.readv() and os.writev() documentation and docstring
by Nikolaus Rath Jan. 19, 2014

Jan. 19, 2014

New submission from Nikolaus Rath: The os.writev and os.readv functions are currently documented as: os.writev(fd, buffers) Write the contents of buffers to file descriptor fd, where buffers is an arbitrary sequence of buffers. Returns the total number of bytes written. os.readv(fd, buffers) Read from a file descriptor into a number of writable buffers. buffers is an arbitrary sequence of writable buffers. Returns the total number of bytes read. This is rather confusing, mostly because it's not clear what can be passed as *buffer* (since buffer objects don't exist in Python 3 anymore), and (as a consequence) how the input will be distributed among the list of buffers. Reading the code, it seems to me that any object that implements the buffer protocol would be fine, but that still doesn't help much in practice. From the memoryview documentation, I can infer that `bytes` implements the buffer protocol, but is also immutable, so how can something be written into it? I'd be happy to write a patch to the documentation, but someone would need to explain to me first what kind of buffers are actually acceptable (and I suspect this will be different for readv and writev). ---------- assignee: docs@python components: Documentation messages: 187526 nosy: Nikratio, docs@python priority: normal severity: normal status: open title: Improve os.readv() and os.writev() documentation and docstring type: enhancement versions: Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17811> _______________________________________

5 9

[issue17814] Popen.stdin/stdout/stderr documentation should mention object type
by Nikolaus Rath Jan. 18, 2014

Jan. 18, 2014

New submission from Nikolaus Rath: The subprocess documentation currently just says that Popen.stdin et all are "file objects", which is linked to the glossary entry. This isn't very helpful, as it doesn't tell whether the streams are bytes or text streams. Suggested patch: diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -677,21 +677,29 @@ .. attribute:: Popen.stdin - If the *stdin* argument was :data:`PIPE`, this attribute is a :term:`file - object` that provides input to the child process. Otherwise, it is ``None``. + If the *stdin* argument was :data:`PIPE`, this attribute is a + :class:`io.BufferedWriter` (if the *universal_newlines* argument + was False) or :class:`io.TextIOWrapper` (if the + *universal_newlines* argument was True) object that provides input + to the child process. Otherwise, it is ``None``. .. attribute:: Popen.stdout - If the *stdout* argument was :data:`PIPE`, this attribute is a :term:`file - object` that provides output from the child process. Otherwise, it is ``None``. + If the *stdout* argument was :data:`PIPE`, this attribute is a + :class:`io.BufferedReader` (if the *universal_newlines* argument + was False) or :class:`io.TextIOWrapper` (if the + *universal_newlines* argument was True) object that provides output + from the child process. Otherwise, it is ``None``. .. attribute:: Popen.stderr - If the *stderr* argument was :data:`PIPE`, this attribute is a :term:`file - object` that provides error output from the child process. Otherwise, it is - ``None``. + If the *stderr* argument was :data:`PIPE`, this attribute is a + :class:`io.BufferedReader` (if the *universal_newlines* argument + was False) or :class:`io.TextIOWrapper` (if the + *universal_newlines* argument was True) object that provides output + from the child process. Otherwise, it is ``None``. .. attribute:: Popen.pid ---------- assignee: docs@python components: Documentation messages: 187535 nosy: Nikratio, docs@python priority: normal severity: normal status: open title: Popen.stdin/stdout/stderr documentation should mention object type type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17814> _______________________________________

6 10

[issue18011] Inconsistency between b32decode() documentation, docstring and code
by Serhiy Storchaka Jan. 8, 2014

Jan. 8, 2014

New submission from Serhiy Storchaka: b32decode() documentation says: "A TypeError is raised if s were incorrectly padded or if there are non-alphabet characters present in the string." b32decode() docstring says: "binascii.Error is raised if the input is incorrectly padded or if there are non-alphabet characters present in the input." Actually binascii.Error (which is a ValueError subtype) is raised if the input is incorrectly padded and TypeError is raised if there are non-alphabet characters present in the input. At least 2 of 3 (documentation, docstring and implementation) should be corrected. Base32 support was originally added in 3cc0d8fd4e2b (TypeError was used everywhere) and then modified in eb45f85c4c79 (TypeError was partially changed to binascii.Error). ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 189571 nosy: barry, docs@python, gvanrossum, serhiy.storchaka priority: normal severity: normal status: open title: Inconsistency between b32decode() documentation, docstring and code type: behavior versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18011> _______________________________________

4 12

[issue17282] document the defaultTest parameter to unittest.main()
by Chris Jerdonek Jan. 2, 2014

Jan. 2, 2014

New submission from Chris Jerdonek: This issue is to document the defaultTest parameter to unittest.main(): http://docs.python.org/dev/library/unittest.html#unittest.main Note that it is not enough simply to say that *defaultTest* is a "default test name or iterable of test names." The documentation should also say when *defaultTest* is used based on the value of the *module* and *argv* arguments, etc. This issue is an offshoot of issue 15132. ---------- assignee: docs@python components: Documentation keywords: easy messages: 182839 nosy: chris.jerdonek, docs@python, ezio.melotti, michael.foord priority: normal severity: normal stage: needs patch status: open title: document the defaultTest parameter to unittest.main() type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17282> _______________________________________

5 5

[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

[issue18326] Not Clear Docs
by icedream91 Nov. 22, 2013

Nov. 22, 2013

New submission from icedream91: I think the documents talking about list.sort() in page http://docs.python.org/3/library/stdtypes.html#list.sort is not clear enough. What asterisk means in "sort(*, key=None, reverse=None)", may be cmp argument from Python 2, or anything else? Or it is a typo? I think document should explain what this asterisk means. Thanks. ---------- assignee: docs@python components: Documentation messages: 192034 nosy: docs@python, icedream91 priority: normal severity: normal status: open title: Not Clear Docs versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18326> _______________________________________

6 14

[issue18032] set methods should specify whether they consume iterators "lazily"
by Abafei Nov. 19, 2013

Nov. 19, 2013

New submission from Abafei: It says here (http://docs.python.org/2/library/stdtypes.html#set-types-set-frozenset) that some of the set methods take iterables as a parameter. Usually, the expected behavior is for a iterator consumer to consume only as much data as it needs. For example, for the code `any(itertools.repeat(True))`, the code will complete speedily, in contrast to when all() is used instead of any(), in which case the code will go forever. A least some of the set methods have semantics such that they can consume only some of the input; for example, "issubset" only needs to make sure that all of the items in the set are in the iterable, and once this is the case, it can return "True". However in such a case, the methods will *still* go forever. The docs should specify that this is the case, to disambiguate the semantics. (Tested on Python 3.2.3 and 2.7.3). ---------- assignee: docs@python components: Documentation messages: 189806 nosy: Abafei, docs@python priority: normal severity: normal status: open title: set methods should specify whether they consume iterators "lazily" type: behavior versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18032> _______________________________________

5 5

[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

[issue17827] Document codecs.encode and codecs.decode
by Nick Coghlan Nov. 4, 2013

Nov. 4, 2013

New submission from Nick Coghlan: The codecs module has long offered encode() and decode() convenience functions (since 2004: http://hg.python.org/cpython-fullhistory/rev/8ea2cb1ec598), but they're not documented (except through docstrings). We should fix that. >From the docstrings: ========== encode(obj, [encoding[,errors]]) -> object Encodes obj using the codec registered for encoding. encoding defaults to the default encoding. errors may be given to set a different error handling scheme. Default is 'strict' meaning that encoding errors raise a ValueError. Other possible values are 'ignore', 'replace' and 'xmlcharrefreplace' as well as any other name registered with codecs.register_error that can handle ValueErrors. ========== decode(obj, [encoding[,errors]]) -> object Decodes obj using the codec registered for encoding. encoding defaults to the default encoding. errors may be given to set a different error handling scheme. Default is 'strict' meaning that encoding errors raise a ValueError. Other possible values are 'ignore' and 'replace' as well as any other name registered with codecs.register_error that is able to handle ValueErrors. ========== Note that the difference between the convenience functions in the codecs module and the methods on str, bytes and bytearray is that the latter have additional type checks to limit their usage to text encodings. str.encode expects a str->bytes conversion, while bytes.decode and bytearray.decode both expect the codec to produce a str object. codecs.encode and codecs.decode are both arbitrary object->object conversions, limited only by whatever the chosen codec supports. ---------- assignee: docs@python components: Documentation messages: 187700 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Document codecs.encode and codecs.decode versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17827> _______________________________________

7 16

[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

[issue17221] Resort Misc/NEWS
by Serhiy Storchaka Oct. 18, 2013

Oct. 18, 2013

New submission from Serhiy Storchaka: The proposed patch moves some Misc/NEWS entities to more appropriate sections (IDLE, C-API, Tests, Documentation, Tools/Demos). Please review. ---------- assignee: docs@python components: Documentation files: NEWS-3.4.patch keywords: patch messages: 182282 nosy: docs@python, eric.araujo, ezio.melotti, georg.brandl, serhiy.storchaka priority: normal severity: normal stage: patch review status: open title: Resort Misc/NEWS type: enhancement versions: Python 3.4 Added file: http://bugs.python.org/file29107/NEWS-3.4.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17221> _______________________________________

9 23

[issue16253] Docs for PyArg_ParseTupleAndKeywords say it doesn't accept nested tuples
by Roger Upole Oct. 13, 2013

Oct. 13, 2013

New submission from Roger Upole: The docs for this function state "Nested tuples cannot be parsed when using keyword arguments!" but this restriction was removed some time ago. ---------- assignee: docs@python components: Documentation messages: 173081 nosy: docs@python, rupole priority: normal severity: normal status: open title: Docs for PyArg_ParseTupleAndKeywords say it doesn't accept nested tuples _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16253> _______________________________________

2 1

[issue17375] Add docstrings to methods in the threading module
by Raymond Hettinger Oct. 13, 2013

Oct. 13, 2013

New submission from Raymond Hettinger: It should be an easy task fill-in the missing docstrings using the verbiage in the regular docs. ---------- assignee: docs@python components: Documentation keywords: easy messages: 183645 nosy: docs@python, rhettinger priority: normal severity: normal status: open title: Add docstrings to methods in the threading module versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17375> _______________________________________

6 11

[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

[issue18177] Typo in Documents
by icedream91 Oct. 12, 2013

Oct. 12, 2013

New submission from icedream91: In library.pdf file(Release 3.3.2, June 09, 2013), I found a typo in page 149: I think the quotation marks are wrong in "datetime.isoformat(sep=’T’)" sentence, they should both be "'". But it's right in online documents (http://docs.python.org/3/library/datetime.html#datetime.datetime.isoformat). Thanks. ---------- assignee: docs@python components: Documentation messages: 190882 nosy: docs@python, icedream91 priority: normal severity: normal status: open title: Typo in Documents versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18177> _______________________________________

6 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

typo in http://docs.python.org/2/howto/argparse.html
by Jason Sachs Oct. 8, 2013

Oct. 8, 2013

minor grammatical typo: “how it works simply by reading it’s help text”: “it’s” should be “its”

2 1

Bugs in Python3 division and right-shift docs
by Albert Hofkamp Oct. 8, 2013

Oct. 8, 2013

While reporting a doc bug in the right-shift operator, I found another one in the division description. I combined them both below. http://docs.python.org/3/reference/expressions.html?highlight=shift#binary-… A quote: " ... The / (division) and // (floor division) operators yield the quotient of their arguments. The numeric arguments are first converted to a common type. Integer division yields a float, while floor division of integers results in an integer; ..." The term "Integer division" does not get defined here. Perhaps "Division of integers yields ..." would be better? http://docs.python.org/3/reference/expressions.html?highlight=shift#shiftin… A quote from 6.7 (Shifting operations) of the python 3 language reference: "...These operators accept integers as arguments. They shift the first argument to the left or right by the number of bits given by the second argument. A right shift by n bits is defined as division by pow(2,n). A left shift by n bits is defined as multiplication with pow(2,n). ..." By the latter sentence, I can interpret 2 >> 5 as 2 / pow(2, 5), which is 0.0625. On the other hand, 2 >> 5 is 0 according to Python 3.3 . Perhaps it should say "floor division" in the explanation above? Albert

2 1

Invalid link in "SystemExit" documentation (2.x, Section 6)
by Bock, Harry Oct. 8, 2013

Oct. 8, 2013

Hi, I stumbled upon a bug in the "SystemExit" exception documentation for Python 2.x: http://docs.python.org/2/library/exceptions.html#exceptions.SystemExit The line "Instances have an attribute code" has a reference to the "code" module: http://docs.python.org/2/library/code.html#module-code Which is not what the SystemExit attribute is referring to. The cross-reference should be removed, and no other change is needed. The documentation explains the attribute well. Thanks for the great documentation! Keep up the great work. [cid:image001.gif@01CE14D1.DB643160] Harry Bock Firmware Test Engineer ZEBRA TECHNOLOGIES CORPORATION 1 Albion Road Suite 100 Lincoln, RI 02865-3703 T: +1 401 276 5720 hbock(a)zebra.com www.zebra.com<http://www.zebra.com/> ________________________________ - CONFIDENTIAL- This email and any files transmitted with it are confidential, and may also be legally privileged. If you are not the intended recipient, you may not review, use, copy, or distribute this message. If you receive this email in error, please notify the sender immediately by reply email and then delete this email.

2 1

The delimiter '->' is missing in section 2.6 documentation
by Harding, James Oct. 8, 2013

Oct. 8, 2013

Hello, A minor quibble. I do not see the token '->' used with function annotations listed among the delimiters in section 2.6 of the reference manual for Python v3.3.0. Thank you, James Harding

2 1

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

Oct. 8, 2013

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

6 8

[issue15863] Fine-grained info about Python versions which support changes introduced in micro releases
by Alexander Konovalenko Oct. 8, 2013

Oct. 8, 2013

New submission from Alexander Konovalenko: Some security fixes and bug fixes that are simultaneously issued for multiple Python versions require changes to the documentation. I'm now looking at the hash randomization vulnerability that was fixed in 2.6.8 and 2.7.3. The docs always mention the release in which a new feature was added. That's great. But for a security fix such as the bug in question, the set of versions which support it doesn't look like "2.x.y or later". The documentation for the -R command-line option and the PYTHONHASHSEED environment variable says "New in version 2.6.8". A reader who is not familiar with the context would infer that those feature are supported in Python 2.7 through 2.7.2, which is not the case. The docs should say "New in version 2.6.8 and 2.7.3". http://docs.python.org/using/cmdline.html#cmdoption-R http://docs.python.org/using/cmdline.html#envvar-PYTHONHASHSEED The documentation for the sys.flags.hash_randomization attribute says "New in version 2.7.3". Again, that leaves out the version 2.6.8 and future versions in the 2.6.x branch, which presumably support the new attribute. The docs should say "New in version 2.6.8 and 2.7.3". http://docs.python.org/library/sys.html#sys.flags Disclaimer: I did not test the relevant micro releases to see whether they actually support those features. Just checked the release dates and applied common sense. If you know of any other micro release bugfixes that were mentioned in the docs, the same considerations apply to them. Please verify the docs are correct, fix them or file appropriate bugs. ---------- assignee: docs@python components: Documentation messages: 169841 nosy: alexkon, docs@python priority: normal severity: normal status: open title: Fine-grained info about Python versions which support changes introduced in micro releases versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________

4 6

[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

/3/library/argparse.html#module-argparse
by Micheal Wells Oct. 6, 2013

Oct. 6, 2013

An observation: In example 16.4.1, a script named 'prog.py' is given, and the user is told that they may execute it from the command line like so: $ prog.py My issue with this, is that it doesn't mention that the script starts with a shebang or is made executable with chmod +x, and even then the command would be $ ./prog.py. A minor gripe, but I think that too much is assumed of the reader. For reference: Assuming the Python code above is saved into a file called prog.py, it can be run at the command line and provides useful help messages: $ prog.py -h

2 1

Trivial os.path documentation bug
by Neil Bushong Oct. 6, 2013

Oct. 6, 2013

Tiny typo: in the Python 3.3 os.makedirs documentation at http://docs.python.org/3.3/library/os.html#os.makedirs, the sentence saying "If exist*s*_ok is False (the default), an OSError is raised..." refers to the keyword argument as "exists_ok" (with an "s"), while the other parts refer to the keyword parameter as "exist_ok" (without the "s"). Thanks for providing and maintaining all the excellent documentation. Neil

2 1

bug in ipaddress module documentation
by Tom Kalt Oct. 6, 2013

Oct. 6, 2013

There is a slight problem with the documentation for the ipaddress module (http://docs.python.org/3.4/library/ipaddress.html). In section 21.28.2.3.1, operators such as <, <=, ==, != are called "logical operators." They should be called "relational operators." http://en.wikipedia.org/wiki/Relational_operator. Alternatively, sometimes they are called "comparison operators." By contrast, "logical operator" refers to and, or, xor, etc. I hope this helps. Tom Kalt ________________________________ This transmission may contain information that is privileged, confidential, and/or exempt from disclosure under applicable law. If you are not the intended recipient, you are hereby notified that any disclosure, copying, distribution, or use of the information contained herein (including any reliance thereon) is STRICTLY PROHIBITED. If you received this transmission in error, please immediately contact the sender and destroy the material in its entirety, whether in electronic or hard copy format.

2 1

2.7.3 documentation: "6.4.1. Importing * From a Package" sounds/ should be sound/
by John Bokma Oct. 6, 2013

Oct. 6, 2013

http://docs.python.org/2/tutorial/modules.html "the file sounds/effects/__init__.py " ^ should be sound, not sounds. Regards, John

2 1

platform.win32_ver() returns more than (version, csd, ptype)
by Andrew Berg Oct. 6, 2013

Oct. 6, 2013

http://docs.python.org/3.3/library/platform.html#platform.win32_ver The documentation explicitly states that platform.win32_ver() returns (version, csd, ptype), but in fact, it returns (release, version, csd, ptype). On Windows 8 (Python 3.3 of course): >>> platform.win32_ver() ('post2008Server', '6.2.9200', '', 'Multiprocessor Free')

2 1

Typo in example code for operator.attrgetter
by Jonathan Kamens Oct. 6, 2013

Oct. 6, 2013

At http://docs.python.org/2/library/operator.html#operator.attrgetter, the example code in one instance "resolve_att" where it should be "resolve_attr". Regards, Jonathan Kamens

2 1

[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

[issue17725] English mistake in Extending and Embedding Python doc page.
by Kyle Simpson Oct. 6, 2013

Oct. 6, 2013

New submission from Kyle Simpson: The second sentence in http://docs.python.org/3/extending/index.html says: Those modules can define new functions but also new object types and their methods. The word "but" doesn't make sense here. I suppose that the author meant to write: Those modules can not only define new functions but also new object types and their methods. ---------- assignee: docs@python components: Documentation messages: 186886 nosy: Kyle.Simpson, docs@python priority: normal severity: normal status: open title: English mistake in Extending and Embedding Python doc page. _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17725> _______________________________________

2 3

hashlib - Missing FAQ section for hash collisions
by Christina Meono Oct. 6, 2013

Oct. 6, 2013

Hello Python.org: I was reading the docs for hashlib and there is a reference to algorithm hash collisions, which the document specified would be addressed in an FAQ at the end of the doc, but said FAQ section cannot be found. Check it out here: http://docs.python.org/2/library/hashlib.html Please let me know if you have any questions. Chris Meono chrismeono1022(a)gmail.com

2 1

quick note on ftplib for python
by Jeremy Orchard Oct. 6, 2013

Oct. 6, 2013

Hello, Quick note, ftplib gives example host ftp.cwi.nl In its documentation which is a url which is no longer active. when you try the dummy example, ftplib doesn't really output a clear error so it might be worth updating the host, (though most programmers should assume this quickly), Python 2.7 > documentation for ftplib which introduced the feature FTP_TLS gives the examplehost ftp.python.org which is possibly the ideal candidate for the change. Not really a bug, thought id save you the trouble by reporting just incase, it was something worth changing. Cheers

4 4

[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

Typo in distutils document
by Bo Bayles Oct. 6, 2013

Oct. 6, 2013

Hello, I noticed a typo in the distutils module's documentation, e.g. at: http://docs.python.org/3/library/distutils.html It currently reads: " If also contains instructions for end-users..." It should read: "It also contains instructions for end-users..." Best regards, -Bo

2 1

I suspect a reversal
by Edward Welbourne Oct. 6, 2013

Oct. 6, 2013

Hi doc-team, On http://docs.python.org/3/library/codecs.html under codecs.register, I see the description: <quote> streamreader and streamwriter: These have to be factory functions providing the following interface: factory(stream, errors='strict') The factory functions must return objects providing the interfaces defined by the base classes StreamWriter and StreamReader, respectively. </quote> and am instantly suspicious: apparently, streamreader should have the interface of StreamWriter and streamwrite that of StreamReader. This is either a doc bug or a horribly bad choice of names for the .register() function's parameters ! Eddy.

2 1

[BUG]About `add_mutually_exclusive_group' in argparse module doc
by Tanky Woo Oct. 6, 2013

Oct. 6, 2013

Today, I read the argparse doc and find the Mutual exclusion section(http://docs.python.org/2/library/argparse.html#mutual-exclusion) has a problem The function `*add_mutually_exclusive_group*' in the section is : *argparse.add_mutually_exclusive_group(required=False)* but add_mutually_exclusive_group belongs to *ArgumentParser* object, not direct to *argparse*, maybe this is a bug?

2 1

Tutorial bug
by Leonardo Pereira Oct. 6, 2013

Oct. 6, 2013

http://docs.python.org/3.3/tutorial/datastructures.html does not list .clear() and .copy() methods introduced in 3.3

2 1

bug in re documentation (python 3.3.2)
by Alexander Heger Oct. 6, 2013

Oct. 6, 2013

http://docs.python.org/3.3/library/re.html 6.2.1. Regular Expression Syntax (way down) it says: \number Matches the contents of the group of the same number. Groups are numbered starting from 1. For example, (.+) \1 matches 'the the' or '55 55', but not 'the end' (note the space after the group). This special sequence can only be used to match one of the first 99 groups. If the first digit of number is 0, or number is 3 octal digits long, it will not be interpreted as a group match, but as the character with octal value number. Inside the '[' and ']' of a character class, all numeric escapes are treated as characters. The example of what does not work is wrong In [1]: import re In [2]: re.findall(r'(.+) \1','the end') Out[2]: ['e'] It probably should be \number Matches the contents of the group of the same number. Groups are numbered starting from 1. For example, (.+) \1 matches 'the the' or '55 55', but not 'thethe' (note the space after the group). This special sequence can only be used to match one of the first 99 groups. If the first digit of number is 0, or number is 3 octal digits long, it will not be interpreted as a group match, but as the character with octal value number. Inside the '[' and ']' of a character class, all numeric escapes are treated as characters. -Alexander

2 1

venv 3.3.2 docs - "create_directories" should be "ensure_directories"
by Michael Rand Oct. 6, 2013

Oct. 6, 2013

To whom it may concern, When subclassing venv.EnvBuilder and customizing create(), the docs say that one should use "self.create_directories(env_dir)". This call raises an AttributeError. When looking at the subclass, I don't see "create_directories" but instead I see the method "ensure_directories", which has the following docstring: "Create the directories for the environment". It seems like either the docs should be fixed to reflect "ensure_directories" as the appropriate method name or the method should be renamed "create_directories". Apologies if I'm mistaken on this ... this is my first doc bug report. Thanks, Mike Rand

2 1

Wrong toolkit for PythonCAD
by Helge Stenström Oct. 6, 2013

Oct. 6, 2013

According to http://docs.python.org/2/library/othergui.html, PythonCAD is written in pygtk, but according to the project page, http://sourceforge.net/projects/pythoncad/, it uses PyQt. Kind regardss, Helge Stenström

2 1

Bug in last httplib example in Python 2.7.5 docs in section 20.7.3
by Alex MacAulay Oct. 6, 2013

Oct. 6, 2013

On the following page in the Python 2.7.5 docs: http://docs.python.org/2/library/httplib.html In section 20.7.3, the last example has: >>> response = conn.getresponse()>>> print resp.status, response.reason However it should be: >>> response = conn.getresponse()>>> print response.status, response.reason Hope it helps! Alex.

2 1

binascii.b2a_base64 can convert data length more than 57
by Chen, Liying Oct. 6, 2013

Oct. 6, 2013

Hi, In the document binascii.b2a_base64(data) said the data length should less than 57.But I can use it for more than 57.Can you give me an explain? >>> import struct >>> import binascii >>> payload = struct.pack('>hhiii',4,0,0,0,0) >>> payload = payload*10 >>> len(payload) 160 >>> binascii.b2a_base64(payload) 'AAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAA==\n' >>> a = binascii.b2a_base64(payload) >>> len(a) 217 >>> Thanks Chen Liying

2 1

Should say 'REAL' not 'FLOAT' as the SQLite datatype in 11.13.1 of sqlite3.
by Richard Kelsall Oct. 6, 2013

Oct. 6, 2013

Hello Python Docs, TLDR: I think it should probably say 'REAL' not 'FLOAT' as the SQLite datatype in 11.13.1 of sqlite3. I am reading the sqlite3 page http://docs.python.org/2/library/sqlite3.html for Python v2.7.5. It says in 11.13.1: "SQLite natively supports only the types TEXT, INTEGER, FLOAT, BLOB and NULL." This made me wonder, is this a double or single FLOAT? (I have not used this database or this Python module before.) And I looked in the SQLite documentation here http://sqlite.org/datatype3.html This says that SQLite version 3 uses an 8 byte (i.e. double) float and has this as type REAL. So I go back to the python page thinking maybe this is an earlier version of SQLite - maybe Python 2 provides SQLite 2 for backwards compatibility and the module name 'sqlite3' does not follow the SQLite version number for some reason. I cannot see on this page mention of what version of SQLite this module provides, maybe I missed that? But I see in 11.13.5.1: "SQLite natively supports the following types: NULL, INTEGER, REAL, TEXT, BLOB." So this internal contradiction makes me think section 11.13.1 is incorrect. I feel posting to this public list, of unknown proportions, may be a rather loud way of reporting such a minor problem, but the documentation page seems to ask me to do this. A wiki might have been an easier and less noisy way to suggest corrections. I expect many people would not go to the trouble of emailing a public mailing list to get a detail like this corrected and that there are many similar bugs which are found but not immediately reported for this reason. Richard.

2 1

Typo in collections.Counter class example
by Михаил Голубев Oct. 6, 2013

Oct. 6, 2013

Hello, It seems that I found micro bug in Python documentation describing collections.Counter class<http://docs.python.org/3.3/library/collections.html#counter-objects> . There is the following snippet of code c.most_common()[:-n:-1] # n least common elements Actually this expression returns not *n* least common elements, but rather *n - 1,* beacuse second boundary is not included (as usual with slices). You probably meant c.most_common()[-n:] or c.most_common()[:-n-1:-1] if reverse ordering is nesessary. -- Best regards Mikhail Golubev

2 1

I found bugs in the Queue documentation
by 오진균 Oct. 6, 2013

Oct. 6, 2013

http://docs.python.org/2/library/queue.html There are two typing errors in this document http://docs.python.org/2/library/queue.html#Queue.Queue.put http://docs.python.org/2/library/queue.html#Queue.Queue.get there is a same sentence within this two function descriptions, If optional args *block* is true and *timeout* is None (the default) In this sentence, I think it should be "True" not "true" because it stands for actual python Boolean value. Thanks.

2 1

bytearray and language usage.
by Mark Janssen Oct. 6, 2013

Oct. 6, 2013

Looking at the Python docs for v2.7.5. Section 2. bytearray([source[, encoding[, errors]]]) " Return a new array of bytes. The bytearray type is a mutable sequence of integers in the range 0 <= x < 256." This should not be called a "mutable sequence of integers", because to call them "integers" already casts raw bits into a particular *type*. They could, hypothetically be very short floats, for example. More accurately, they are merely "uninterpreted bits presented to the user in 8-bit chunks, with a consistent starting boundary" (held by the machine storage address). -- MarkJ Tacoma, Washington

2 2

[issue16195] Difficult or impossible to figure out how garbage collector and weak references should interact for user-defined extension types
by Jean-Paul Calderone Oct. 5, 2013

Oct. 5, 2013

New submission from Jean-Paul Calderone: There appears to be very little, if any, documentation about how to handle the list at tp_weaklistoffset for types supporting being weak referenced, particularly with respect to garbage collection. Who owns the list? Who owns the objects in the list? Should the list be traversed by the extension type's tp_traverse? Should it ever be INCREF'd or DECREF'd? Does tp_dealloc have any responsibilities with respect to it? >From looking at CPython's own source, it appears that tp_traverse should not touch it (Yhg1s confirmed this on #python). Cython, at least, appears to have come to an alternate conclusion though - it generates tp_traverse functions which visit the list (and provoke gc assertions to fail on Python 2.7 in debug mode). Some documentation about what is correct to do would be excellent, and would make it easier to explain to Cython developers what they're doing wrong (or confirm that they're doing something right, in which case there are some more bugs to file against the CPython stdlib, since they do something different from Cython). ---------- assignee: docs@python components: Documentation messages: 172639 nosy: docs@python, exarkun priority: normal severity: normal status: open title: Difficult or impossible to figure out how garbage collector and weak references should interact for user-defined extension types _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16195> _______________________________________

6 5

[issue17326] Windows build docs still referring to VS 2008 in 3.3
by Christoph Zwerschke Sept. 29, 2013

Sept. 29, 2013

New submission from Christoph Zwerschke: The first paragraph in PCbuild/readme.txt of Python 3.3 still talks about Visual C++ 2008 Express and Visual Studio 2008. It says that VS 2008 is required at the very least (which may be still true, I'm not sure), but then it also says "the official Python releases are built with this [i.e. the 2008] version of VS", while it seems they have been built with VS 2010 in reality (as the title is also indicating). ---------- assignee: docs@python components: Documentation messages: 183259 nosy: cito, docs@python priority: normal severity: normal status: open title: Windows build docs still referring to VS 2008 in 3.3 type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17326> _______________________________________

4 4

[issue17777] Unrecognized string literal escape sequences give SyntaxErrors
by Reynir Reynisson Sept. 24, 2013

Sept. 24, 2013

New submission from Reynir Reynisson: Strings like "\u" trigger a SyntaxError. According to the language reference "all unrecognized escape sequences are left in the string unchanged"[0]. The string "\u" clearly doesn't match any of the escape sequences (in particular \uxxxx). This may be intentional, but it is not clear from the language reference that this is the case. If it is intentional it should probably be stated more explicit in the language reference. I think this may be confusing for new users since the syntax errors may lead them to believe the interpreter will give syntax error for all unrecognized escape sequences. [0]: http://docs.python.org/3/reference/lexical_analysis.html#literals ---------- assignee: docs@python components: Documentation, Unicode messages: 187173 nosy: docs@python, ezio.melotti, reynir priority: normal severity: normal status: open title: Unrecognized string literal escape sequences give SyntaxErrors type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17777> _______________________________________

5 5

[issue18206] There is no license.html on www.python.org
by py.user Sept. 14, 2013

Sept. 14, 2013

New submission from py.user: [guest@localhost ~]$ python3 Python 3.3.0 (default, Sep 29 2012, 22:07:38) [GCC 4.7.2 20120921 (Red Hat 4.7.2-2)] on linux Type "help", "copyright", "credits" or "license" for more information. >>> license() See http://www.python.org/3.3/license.html >>> 404 answer from webmaster(a)python.org: Hello, When I use the version of Python distributed by python.org and type "license()" I get the full license text and not the url. It seems like this might be a change made by Red Hat? Either way, the proper place to discuss issues like this is on the Python bug tracker: http://bugs.python.org/ Feel free to report an issue there and the developers can look at it. This email address is actually for reporting problems with the Python.org website! All the best, Michael Foord in Lib/site.py: [guest@localhost cpython]$ sed -n '453,456p' Lib/site.py builtins.license = _Printer( "license", "See http://www.python.org/%.3s/license.html" % sys.version, ["LICENSE.txt", "LICENSE"], [os.path.join(here, os.pardir), here, os.curdir]) [guest@localhost cpython]$ ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 191095 nosy: docs@python, py.user priority: normal severity: normal status: open title: There is no license.html on www.python.org type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18206> _______________________________________

8 18

[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

[issue18313] In itertools recipes repeatfunc() defines a non-keyword argument as keyword
by py.user Sept. 9, 2013

Sept. 9, 2013

New submission from py.user: http://docs.python.org/3/library/itertools.html#itertools-recipes "def repeatfunc(func, times=None, *args):" >>> repeatfunc(lambda x: x, times=None, 1) File "<stdin>", line 1 SyntaxError: non-keyword arg after keyword arg >>> >>> repeatfunc(lambda x: x, 1, times=None) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: repeatfunc() got multiple values for argument 'times' >>> ---------- assignee: docs@python components: Documentation messages: 191930 nosy: docs@python, py.user priority: normal severity: normal status: open title: In itertools recipes repeatfunc() defines a non-keyword argument as keyword type: enhancement versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18313> _______________________________________

5 10

[issue18301] In itertools.chain.from_iterable() there is no cls argument
by py.user Sept. 9, 2013

Sept. 9, 2013

New submission from py.user: http://docs.python.org/2/library/itertools.html#itertools.chain.from_iterab… >>> class A: ... @classmethod ... def from_iterable(iterables): ... for it in iterables: ... for element in it: ... yield element ... >>> A.from_iterable(['ABC', 'DEF']) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: from_iterable() takes 1 positional argument but 2 were given >>> ---------- assignee: docs@python components: Documentation files: issue.diff keywords: patch messages: 191874 nosy: docs@python, py.user priority: normal severity: normal status: open title: In itertools.chain.from_iterable() there is no cls argument type: enhancement versions: Python 3.3, Python 3.4 Added file: http://bugs.python.org/file30702/issue.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18301> _______________________________________

7 12

[issue18033] Example for Profile Module shows incorrect method
by Jough Dempsey Sept. 8, 2013

Sept. 8, 2013

New submission from Jough Dempsey: The example on this page: http://docs.python.org/2/library/profile.html?highlight=pstats#profile.Prof… Shows: import cProfile, pstats, io pr = cProfile.Profile() pr.enable() ... do something ... pr.disable() s = io.StringIO() ps = pstats.Stats(pr, stream=s) ps.print_results() Where "ps.print_results()" should be "ps.print_stats()" ---------- assignee: docs@python components: Documentation messages: 189823 nosy: docs@python, jough priority: normal severity: normal status: open title: Example for Profile Module shows incorrect method type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18033> _______________________________________

8 9

[issue17902] Document that _elementtree C API cannot use custom TreeBuilder for iterparse or IncrementalParser
by Aaron Oakley Aug. 27, 2013

Aug. 27, 2013

New submission from Aaron Oakley: It would really help to document that the C API can only use the default xml.etree.ElementTree.TreeBuilder for targets with iterparse (and by extension, IncrementalParser). I got a nice surprise about that when I went from 3.2 to 3.3 and started getting "TypeError: event handling only supported for ElementTree.TreeBuilder targets". I included a patch to add notes to iterparse and IncrementalParser, but I'm not sure what to refer to the C module as since xml.etree.cElementTree is deprecated. ---------- assignee: docs@python components: Documentation, XML files: elementtree.rst-340a0.patch keywords: patch messages: 188329 nosy: Aaron.Oakley, docs@python priority: normal severity: normal status: open title: Document that _elementtree C API cannot use custom TreeBuilder for iterparse or IncrementalParser type: behavior versions: Python 3.4 Added file: http://bugs.python.org/file30119/elementtree.rst-340a0.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17902> _______________________________________

4 8

[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

[issue15939] make *.rst files in Doc/ parseable by doctest
by Chris Jerdonek Aug. 17, 2013

Aug. 17, 2013

New submission from Chris Jerdonek: Currently, when trying to parse the *.rst files in the Doc/ folder (i.e. not actually running them but simply generating unittest.TestCase instances from them by passing them to doctest.DocFileSuite()), five files yield errors. This issue is to make it so that all of the *.rst files in our Doc/ folder are at least parseable by doctest without error. I will submit a patch. Below are the errors that currently occur: (1) test fdoc:library/ctypes.rst crashed -- Traceback (most recent call last): ... ValueError: line 55 of the doctest for ctypes.rst has an invalid option: '+WINDOWS' (2) test fdoc:library/doctest.rst crashed -- Traceback (most recent call last): ... ValueError: line 1592 of the docstring for doctest.rst has inconsistent leading whitespace: ' """))' (3) test fdoc:library/multiprocessing.rst crashed -- Traceback (most recent call last): ... ValueError: line 1016 of the docstring for multiprocessing.rst lacks blank after >>>: '>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>' (4) test fdoc:whatsnew/2.4.rst crashed -- Traceback (most recent call last): ... ValueError: line 1422 of the docstring for 2.4.rst lacks blank after >>>: ' >>>"""' (5) test fdoc:whatsnew/2.7.rst crashed -- Traceback (most recent call last): ... ValueError: line 1531 of the docstring for 2.7.rst lacks blank after .: ' ...' ---------- assignee: docs@python components: Documentation messages: 170441 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: make *.rst files in Doc/ parseable by doctest versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15939> _______________________________________

2 11

[issue16190] Misleading warning in random module docs
by Christian Heimes Aug. 16, 2013

Aug. 16, 2013

New submission from Christian Heimes: The documentation [1] of the random module contains a misleading warning --- Warning: The generators of the random module should not be used for security purposes. Use ssl.RAND_bytes() if you require a cryptographically secure pseudorandom number generator. --- The warning should point users to os.urandom() and random.SystemRandom rather than ssl.RAND_bytes(). On Linux os.urandom() wraps /dev/urandom [2], on Windows it uses CryptGenRandom() [3]. Both are suitable for most cryptographic purposes except for long-lived keys (SSL, SSH, GPG certs etc.). ssl.RAND_bytes() should only be used for such long-lived data and not for salts, session ids and similar. I like to see the warning box in Python 2.7, too. It's still the default for docs.python.org. My inquiry is motivated by #16184. [1] http://docs.python.org/py3k/library/random.html [2] http://linux.die.net/man/4/urandom [3] http://msdn.microsoft.com/en-us/library/windows/desktop/aa379942%28v=vs.85%… ---------- assignee: docs@python messages: 172589 nosy: christian.heimes, docs@python priority: normal severity: normal status: open title: Misleading warning in random module docs type: security versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16190> _______________________________________

9 13

[issue17701] Improving strftime documentation
by David Wolever Aug. 12, 2013

Aug. 12, 2013

New submission from David Wolever: The current strftime documentation isn't very helpful. It doesn't have examples, and the ordering is unhelpful. I've also moved some format-specific notes into the notes below the format-string-table, because the format string table is what 98%* of people care about. TODO before this can be merged: - Clean up note order - Check that it works with the Python 3 docs *: based on a sample size of 1 ---------- assignee: docs@python components: Documentation files: strftime-docs.diff keywords: needs review, patch messages: 186601 nosy: docs@python, wolever priority: normal severity: normal status: open title: Improving strftime documentation type: enhancement versions: Python 2.7 Added file: http://bugs.python.org/file29784/strftime-docs.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17701> _______________________________________

4 18

[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

[issue18267] xmlrpc.client documentation multicall example missleading for division behaviour of python3
by Bernhard Reiter Aug. 8, 2013

Aug. 8, 2013

New submission from Bernhard Reiter: http://docs.python.org/3.4/library/xmlrpc.client.html as of 2013-06-19 20:35 UTC has a divide example and the output can misslead the learning reader towards the new behaviour of python3 with the '/' binary operator for division. server code: def divide(x, y): return x/y client code: multicall.divide(7,3) [..] print("7+3=%d, 7-3=%d, 7*3=%d, 7/3=%d" % tuple(result)) The client call results into: python3 client.py 7+3=10, 7-3=4, 7*3=21, 7/3=2 This is missleading because '7/3' is now resulting to a float in python3 (see PEP238).The example probably was copied over from the python2 documentation where '7/3' result to int. The implicit conversion from float to int is done in the string formatting. Proposal replace the print line with print("7+3=%d, 7-3=%d, 7*3=%d, 7/3=%g" % tuple(result)) to get 7+3=10, 7-3=4, 7*3=21, 7/3=2.33333 or print(repr(tuple(result))) to get (10, 4, 21, 2.3333333333333335) ---------- assignee: docs@python components: Documentation messages: 191495 nosy: ber, docs@python priority: normal severity: normal status: open title: xmlrpc.client documentation multicall example missleading for division behaviour of python3 versions: Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18267> _______________________________________

3 4

[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

[issue16937] -u (unbuffered I/O) command line option documentation mismatch for sys.stdin
by Martijn Pieters July 25, 2013

July 25, 2013

New submission from Martijn Pieters: Run `python3.3 -h` and the `-u` option is documented as: > -u : unbuffered binary stdout and stderr; also PYTHONUNBUFFERED=x > see man page for details on internal buffering relating to '-u' Note that only `stdout` and `stderr` are mentioned. The online documentation at http://docs.python.org/3/using/cmdline.html#cmdoption-u doesn't agree: > ... the binary layer of the stdin, stdout and stderr streams ... nor does `man python3.3`, which claims: > -u Force the binary I/O layers of stdin, stdout and stderr to be unbuffered. The text I/O layer will still > be line-buffered. So, is `stdin` going to be unbuffered, or not, when using `-u`? Running a simple test shows that `stdin` is firmly being buffered regardless of the `-u` switch: $ python3.3 -c 'import sys; print(sys.stdin.buffer, sys.stdout.buffer)' <_io.BufferedReader name='<stdin>'> <_io.BufferedWriter name='<stdout>'> $ python3.3 -u -c 'import sys; print(sys.stdin.buffer, sys.stdout.buffer)' <_io.BufferedReader name='<stdin>'> <_io.FileIO name='<stdout>' mode='wb'> I'll presume here that `stdin` is deliberately buffered, regardless, and that the documentation and man page are out of date here (in python 2, `-u` does include `stdin`). ---------- assignee: docs@python components: Documentation messages: 179718 nosy: docs@python, mjpieters priority: normal severity: normal status: open title: -u (unbuffered I/O) command line option documentation mismatch for sys.stdin versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16937> _______________________________________

6 5

[issue17987] test.support.captured_stderr, captured_stdin not documented
by Fred L. Drake, Jr. July 11, 2013

July 11, 2013

New submission from Fred L. Drake, Jr.: The captured_stderr and captured_stdin context managers aren't documented, and should be. ---------- assignee: docs@python components: Documentation keywords: easy messages: 189311 nosy: docs@python, fdrake priority: normal severity: normal stage: needs patch status: open title: test.support.captured_stderr, captured_stdin not documented type: enhancement versions: Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17987> _______________________________________

6 20

[issue18044] Email headers do not properly decode to unicode.
by Tim Rawlinson July 11, 2013

July 11, 2013

New submission from Tim Rawlinson: In Python 3.3 decoding of headers to unicode is supposed to be automatic but fails in several cases, including one shown as successful in the documentation: >>> msg = message_from_string('Subject: =?utf-8?q?=C3=89ric?=\n\n', policy=default) >>> msg['Subject'] '=?utf-8?q?=C3=89ric?=' >>> msg = message_from_string('To: =?utf-8?q?=C3=89ric <foo(a)example.com>\n\n', policy=default) >>> msg['To'] '=?utf-8?q?=C3=89ric?= <foo(a)example.com>' Although the following works: >>> msg = message_from_string('Subject: =?utf-8?q?Eric?=\n\n', policy=default) >>> msg['Subject'] 'Eric' Though this does not: >>> msg = message_from_string('To: =?utf-8?q?Eric?= <foo(a)example.com>\n\n', policy=default) >>> msg['To'] '=?utf-8?q?Eric?= <foo(a)example.com>' And just to prove some things are working as they should: >>> msg = message_from_string("Subject: =?gb2312?b?1eLKx9bQzsSy4srUo6E=?=\n\n", policy=default) >>> msg['Subject'] '这是中文测试！' ---------- assignee: docs@python components: Documentation, email messages: 189862 nosy: Tim.Rawlinson, barry, docs@python, r.david.murray priority: normal severity: normal status: open title: Email headers do not properly decode to unicode. type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18044> _______________________________________

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

[issue18231] What's new in Python should explain what's new in UCD
by Alexander Belopolsky July 7, 2013

July 7, 2013

New submission from Alexander Belopolsky: At the minimum, we should refer to unicode.org: http://www.unicode.org/versions/Unicode6.1.0/#Database_Changes (for Python 3.3), http://www.unicode.org/versions/Unicode6.2.0/#Database_Changes (for Python 3.4). We may also want to highlight changes that directly affect python programs. For example addition of new characters accepted as decimal digits in UCD 6.1.0. ---------- assignee: docs@python messages: 191278 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: What's new in Python should explain what's new in UCD versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18231> _______________________________________

3 8

[issue17860] subprocess docs lack info how to use output result
by anatoly techtonik July 7, 2013

July 7, 2013

New submission from anatoly techtonik: http://docs.python.org/3/library/subprocess.html A common confusion is that result from subprocess calls in Python 3 is bytes, not string, and needs to be converted. The problem is complicated because you need to know the encoding of input/output streams. This should be documented at least. http://stackoverflow.com/questions/606191/convert-byte-array-to-python-stri… ---------- assignee: docs@python components: Documentation messages: 187982 nosy: docs@python, techtonik priority: normal severity: normal status: open title: subprocess docs lack info how to use output result versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17860> _______________________________________

9 17

[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

[issue12211] Better document math.copysign behavior.
by Terry J. Reedy June 30, 2013

June 30, 2013

Changes by Terry J. Reedy <tjreedy(a)udel.edu>: ---------- versions: +Python 3.4 -Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12211> _______________________________________

1 0

[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

[issue18237] unittest.assertRaisesRegex(p) example is wrong in docs
by Jeff Tratner June 29, 2013

June 29, 2013

New submission from Jeff Tratner: One of the examples for assertRaisesRegex(p) is wrong by one character. Current is: self.assertRaisesRegexp(ValueError, 'invalid literal for.*XYZ$', int, 'XYZ') The $ at the end is wrong because the actual error message is "ValueError: invalid literal for int() with base 10: 'XYZ'" (with a ``'`` at the end). Two options for fixing. Option 1 - remove $ self.assertRaisesRegexp(ValueError, 'invalid literal for.*XYZ', int, 'XYZ') Option 2 - add ' self.assertRaisesRegexp(ValueError, 'invalid literal for.*XYZ\'$', int, 'XYZ') Same example is shown for assertRaisesRegex, so applies to both. And for completeness...here's something you can run to see the error [couldn't figure out how to attach two files]: import unittest class MyTest(unittest.TestCase): def test_example(self): # this fails self.assertRaisesRegexp(ValueError, 'invalid literal for.*XYZ$', int, 'XYZ') def test_option1(self): self.assertRaisesRegexp(ValueError, 'invalid literal for.*XYZ', int, 'XYZ') def test_option2(self): self.assertRaisesRegexp(ValueError, 'invalid literal for.*XYZ\'$', int, 'XYZ') unittest.main() ---------- assignee: docs@python components: Documentation files: unittest.patch keywords: patch messages: 191306 nosy: docs@python, jtratner priority: normal severity: normal status: open title: unittest.assertRaisesRegex(p) example is wrong in docs versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 Added file: http://bugs.python.org/file30615/unittest.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18237> _______________________________________

4 4

[issue16418] argparse with many choices can generate absurdly long usage message
by paul j3 June 29, 2013

June 29, 2013

Changes by paul j3 <ajipanca(a)gmail.com>: ---------- nosy: +paul.j3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16418> _______________________________________

1 0

[issue18315] bufsize parameter not documented in 2.7.5
by Terrel Shumway June 28, 2013

June 28, 2013

New submission from Terrel Shumway: for line in fileinput.input(files,inplace,backup,"rU"): File "/usr/lib/python2.7/fileinput.py", line 253, in next line = self.readline() File "/usr/lib/python2.7/fileinput.py", line 346, in readline self._buffer = self._file.readlines(self._bufsize) TypeError: an integer is required According to the documentation, my code was correct. But somewhere along the line, someone added a 'bufsize' parameter and didn't update the docstrings. It's an easy fix, but I'll have to investigate when this broke. ---------- assignee: docs@python components: Documentation messages: 191952 nosy: Terrel.Shumway, docs@python priority: normal severity: normal status: open title: bufsize parameter not documented in 2.7.5 type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18315> _______________________________________

4 12

Comparison of sequences
by Matthew Gilson June 28, 2013

June 28, 2013

It seems to me that the documentation on comparison for sequences could be improved slightly. (reference) http://docs.python.org/3/reference/expressions.html#not-in """ Tuples and lists are compared lexicographically using comparison of corresponding elements. This means that to compare equal, each element must compare equal and the two sequences must be of the same type and have the same length. If not equal, the sequences are ordered the same as their first differing elements. For example, [1,2,x] <= [1,2,y] has the same value as x <= y. If the corresponding element does not exist, the shorter sequence is ordered first (for example, [1,2] < [1,2,3]). """ The first paragraph is clear -- if you compare two sequences (lists/tuples) which are of different type then they aren't equal. However, the second paragraph is not quite as clear what the result of rich comparisons should be if you compare a list and a tuple. e.g. what should the result of `[2] > (1,)` be? In python3.x, this results in a TypeError (presumably because the rich comparison methods aren't overloaded to allow that behavior -- But documentation reader doesn't really have a good way of knowing that), but on python2.x the ordering is not based on their elements as implied by the documentation but are instead ordered based on their type. I propose that the documentation should say something like this: Python3.x: "If not equal, the sequences are ordered the same as their first differing elements if they have the same type. Otherwise the comparison results in a `TypeError`". Python2.7: "If not equal, the sequences are ordered the same as their first differing elements if they have the same type. Otherwise the result is the same as comparing the sequence types."

1 0

[issue18311] Typo in SSL documentation
by mp June 26, 2013

June 26, 2013

New submission from mp: Under http://docs.python.org/3.4/library/ssl.html#ssl.SSLContext.set_npn_protocols "avertise" should be "advertise". This is in documentation for both 3.4 and 3.3 ---------- assignee: docs@python components: Documentation messages: 191913 nosy: docs@python, pfista priority: normal severity: normal status: open title: Typo in SSL documentation versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18311> _______________________________________

3 2

[issue18297] In range.sample() correct the ValueError message for negative k
by py.user June 25, 2013

June 25, 2013

New submission from py.user: >>> random.sample('ABC', -1) Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/lib64/python3.3/random.py", line 302, in sample raise ValueError("Sample larger than population") ValueError: Sample larger than population >>> ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 191832 nosy: docs@python, py.user priority: normal severity: normal status: open title: In range.sample() correct the ValueError message for negative k type: enhancement versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18297> _______________________________________

3 6

Typo on "3. An Informal Introduction to Python" [version 3.2.2]
by Hamid Eftekhari June 25, 2013

June 25, 2013

Hi there, I believe there's a tiny typo on this page, section 3.1.2. Strings, where string slicing is introduced. There we read: >>> word[0:2] # characters from position 0 (included) to 2 (excluded) 'Py' >>> word[2:5] # characters from position 2 (included) to 4 (excluded) 'tho'I think the second comment must read: # characters from position 2 (included) to 5 (excluded) Thanks, Regards.

1 0

[issue12633] sys.modules doc entry should reflect restrictions
by Eric Snow June 25, 2013

June 25, 2013

Eric Snow added the comment: issue17953 addressed part of this. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12633> _______________________________________

1 0

[issue1040439] Missing documentation on how to link with libpython
by Ned Deily June 24, 2013

June 24, 2013

Ned Deily added the comment: I've now backported the 3.x update to the 2.7 docs in Issue18164 (I hadn't noticed that this issue was still open). As Eli noted, if any updates are needed to cover Windows, a separate issue should be opened. I'm closing this one. ---------- nosy: +ned.deily resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue1040439> _______________________________________

1 0

[issue18277] Queue is empty right after put from the same process/thread
by Richard Oudkerk June 24, 2013

June 24, 2013

Changes by Richard Oudkerk <shibturn(a)gmail.com>: ---------- assignee: -> docs@python components: +Documentation -IO, Interpreter Core nosy: +docs@python resolution: -> fixed stage: -> committed/rejected status: open -> closed type: behavior -> _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18277> _______________________________________

1 0

[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

[issue18179] SMTP.local_hostname is undocumented
by Jonas H. June 23, 2013

June 23, 2013

New submission from Jonas H.: The Sphinx docs don't contain any explanation for `local_hostname`. ---------- assignee: docs@python components: Documentation messages: 190898 nosy: docs@python, jonash priority: normal severity: normal status: open title: SMTP.local_hostname is undocumented versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18179> _______________________________________

5 6

[issue18220] In itertools.islice() make prototype like in help()
by py.user June 22, 2013

June 22, 2013

New submission from py.user: http://docs.python.org/3/library/itertools.html#itertools.islice " itertools.islice(iterable, stop) itertools.islice(iterable, start, stop[, step])" >>> print(itertools.islice.__doc__) islice(iterable, [start,] stop [, step]) --> islice object ... ---------- assignee: docs@python components: Documentation files: issue.patch keywords: patch messages: 191199 nosy: docs@python, py.user priority: normal severity: normal status: open title: In itertools.islice() make prototype like in help() type: enhancement versions: Python 3.3, Python 3.4 Added file: http://bugs.python.org/file30599/issue.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18220> _______________________________________

6 10