Mailman 3 May 2017 - docs

[issue29179] Py_UNUSED is not documented
by Petr Viktorin Nov. 8, 2017

Nov. 8, 2017

New submission from Petr Viktorin: The Py_UNUSED macro, which was added in Python 3.4, is not documented. Is this an omission, or is it undocumented on purpose? I can prepare a patch if it's the former. The macro was added in: http://bugs.python.org/issue19976 and referenced in: http://bugs.python.org/issue26179 Usage on Github: https://github.com/search?q=py_unused&type=Code ---------- assignee: docs@python components: Documentation messages: 284821 nosy: docs@python, encukou priority: normal severity: normal status: open title: Py_UNUSED is not documented versions: Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29179> _______________________________________

3 6

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

Nov. 8, 2017

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

6 7

[issue18669] curses.chgat() moves cursor, documentation says it shouldn't
by productivememberofsociety666 Nov. 4, 2017

Nov. 4, 2017

New submission from productivememberofsociety666: According to docs.python.org/2/library/curses.html#chgat (or any other version), curses.chgat() is not supposed to move the cursor at all. This is true if you don't give it x,y coordinates, but if you do, the cursor does in fact move to those coordinates, since it then uses C curses's mvchgat() internally and doesn't correct the position afterwards. See included file for demonstration: Expected output is: one two Actual output is: two Fix the documentation or fix the code :-) ---------- assignee: docs@python components: Documentation, Extension Modules files: chgat-bug.py messages: 194552 nosy: docs@python, productivememberofsociety666 priority: normal severity: normal status: open title: curses.chgat() moves cursor, documentation says it shouldn't type: behavior versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 Added file: http://bugs.python.org/file31175/chgat-bug.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18669> _______________________________________

6 10

[issue20064] PyObject_Malloc is not documented
by R. David Murray Oct. 31, 2017

Oct. 31, 2017

New submission from R. David Murray: At least, a doc ref to :c:func:`PyObject_Malloc` does not turn into a link, and I can't find anything in the docs that it looks like it should link to. ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 206910 nosy: docs@python, r.david.murray priority: normal severity: normal stage: needs patch status: open title: PyObject_Malloc is not documented type: behavior versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20064> _______________________________________

8 14

[issue17418] Documentation Bug
by Gurmeet Singh Oct. 28, 2017

Oct. 28, 2017

New submission from Gurmeet Singh: Incompletely explained documentation at 2 places: 1. http://docs.python.org/3/library/functions.html#open The buffering argument is not correctly explained when setting to a positive argument in binary mode. 2. http://docs.python.org/3/library/os.html#os.open It is not very clear where to find descriptions of the arguments of this function. Where to find the required information and where to find C run-time documentation could be explained in following preferably: (Python/C API Reference Manual) http://docs.python.org/3/c-api/index.html and / or (The Python Standard Library) http://docs.python.org/3/library and / or (Python Runtime Services) http://docs.python.org/3/library/python.html A hyperlink may be added if so felt. ---------- assignee: docs@python components: Documentation messages: 184166 nosy: docs@python, gsingh priority: normal severity: normal status: open title: Documentation Bug versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17418> _______________________________________

4 6

[issue29933] asyncio: set_write_buffer_limits() doc doesn't specify unit of the parameters
by STINNER Victor Oct. 25, 2017

Oct. 25, 2017

New submission from STINNER Victor: The asyncio set_write_buffer_limits() documentation doesn't specify unit of high and low parameters. Moreover, it would to explain better the effect of high and low: * pause_writing() is called when the buffer size becomes larger or equal to high * (if writing is pause) resume_writing() is called when the buffer size becomes smaller or equal to low ---------- assignee: docs@python components: Documentation, asyncio keywords: easy messages: 290712 nosy: docs@python, haypo, yselivanov priority: normal severity: normal status: open title: asyncio: set_write_buffer_limits() doc doesn't specify unit of the parameters versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29933> _______________________________________

4 13

[issue26546] Provide translated french translation on docs.python.org
by Julien Oct. 10, 2017

Oct. 10, 2017

New submission from Julien: Hi, The [french translation of the Python documentation](https://github.com/afpy/python_doc_fr) just hit a 21% coverage in terms of pageviews (According to statistics [nicely provided by EWDurbin](https://github.com/AFPy/python_doc_fr/issues/32#issuecomment-1950…). (It's 14% of the total strings to translate). I think it may be a good time to push the translation to *docs.python.org*, so french speaking people will be able to find it naturally, and more translators will be aware of it, increasing the translation speed. Also it will probably motivate other translations (http://docs.python.jp/3/, http://docs.python.org.ar/tutorial/3/index.html, others ?) to work in a more standardized ways, and make their translations more discoverable. So there's two discussions to have: The URL, and the "how". # URL I think the only reasonable possibility is *docs.python.org/{country_code}/* Having a CCTLD per translation is near impossible (a LOT or work and highly time consuming) as some domains are unavailable like python.fr and some other have high restrictions like having a physical presence in the country (like python.ca, python.pt.br) or having a commercial relation with a local company like for python.com.tr). Also it allows localization via *docs.python.org/fr_FR/* even if I don't think we need it soon. If you have other ideas, better than *docs.python.org/fr/*, that's why this issue is opened. # How to We have a [Makefile](https://github.com/AFPy/python_doc_fr/blob/master/Makefile) which like [docsbuild-scripts](https://github.com/python/docsbuild-scripts) delegates naturally most of its work to the sphinx Makefile in *Doc/Makefile*, and is capable of building french versions of 2.7, 3.3, 3.4, and 3.5 in a simple invocation of `make build_all MODE=autobuild-stable` (cloning itself from the github repository, applying various patches (typically to configure sphinx to generate french). 3.2 is also possible but not built by default (no autobuild-html in its sphinx Makefile). I think docsbuild-scripts may delegate the french generation by simply cloning/updating our repository and calling our makefile. A patch (attached) will be necessary in docsbuild-scripts to copy generated doc to /fr/ and send purges to the CDN. Finally, once all this is running, we'll start a discussion about cross-linking both documentations, probably reopening https://github.com/sphinx-doc/sphinx/issues/1246. ---------- assignee: docs@python components: Documentation files: build_doc_fr.patch keywords: patch messages: 261654 nosy: benjamin.peterson, docs@python, sizeof priority: normal severity: normal status: open title: Provide translated french translation on docs.python.org type: enhancement Added file: http://bugs.python.org/file42150/build_doc_fr.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26546> _______________________________________

7 16

[issue27484] Some Examples in Format String Syntax are incorrect or poorly worded
by Rufus V. Smith Oct. 2, 2017

Oct. 2, 2017

New submission from Rufus V. Smith: In section 6.1.3 Format String Syntax, some examples have incorrect or poorly worded comments: Original: "Harold's a clever {0!s}" # Calls str() on the argument first "Bring out the holy {name!r}" # Calls repr() on the argument first "More {!a}" # Calls ascii() on the argument first Suggested Changes: "Harold's a clever {0!s}" # Calls str() on first positional argument "Bring out the holy {name!r}" # Calls repr() on the named argument 'name' "More {!a}" # Calls ascii() on first positional argument (v. 3.1 and later) ---------- assignee: docs@python components: Documentation messages: 270189 nosy: RufusVS, docs@python priority: normal severity: normal status: open title: Some Examples in Format String Syntax are incorrect or poorly worded _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27484> _______________________________________

4 4

[issue27385] itertools.groupby has misleading doc string
by Grant Mathews Sept. 25, 2017

Sept. 25, 2017

New submission from Grant Mathews: The itertools.groupby function is generally well-documented, but the fact that it only groups consecutive occurrences of keys is not mentioned in the doc string, which is where that information is most needed. ---------- assignee: docs@python components: Documentation files: groupby_doc.patch keywords: patch messages: 269211 nosy: docs@python, gmathews priority: normal severity: normal status: open title: itertools.groupby has misleading doc string versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6 Added file: http://bugs.python.org/file43531/groupby_doc.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27385> _______________________________________

6 11

[issue23702] docs.python.org/3/howto/descriptor.html still refers to "unbound methods"
by Paul Sokolovsky Sept. 25, 2017

Sept. 25, 2017

New submission from Paul Sokolovsky: Under https://docs.python.org/3/howto/descriptor.html#functions-and-methods , there're several references to unbound methods (including in expected output from the interpreter). As known, unbound methods are gone in Python3, so seeing those are confusing. (I didn't sharply know that unbound methods are gone from Py3, so was pretty confused by the examples there, comparing them with actual output of Cpython 3.4). ---------- assignee: docs@python components: Documentation messages: 238468 nosy: docs@python, pfalcon priority: normal severity: normal status: open title: docs.python.org/3/howto/descriptor.html still refers to "unbound methods" versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23702> _______________________________________

8 15