Mailman 3 March 2017 - docs

[issue24896] It is undocumented that re.UNICODE affects re.IGNORECASE
by Leif Arne Storset Nov. 16, 2017

Nov. 16, 2017

New submission from Leif Arne Storset: A non-ASCII string does not match a regular expression case-insensitively unless the UNICODE flag is set. This seems reasonable, but the documentation seems to imply that this is not the case. The example: import re # Does not match re.compile(u"неоднозначность", re.IGNORECASE) \ .findall(u"Неоднозначность") # Matches re.compile(u"неоднозначность", re.IGNORECASE | re.UNICODE) \ .findall(u"Неоднозначность") (In Python 3, it does not match if re.ASCII is given.) The documentation (2.7) says: re.UNICODE Make \w, \W, \b, \B, \d, \D, \s and \S dependent on the Unicode character properties database. (https://docs.python.org/2/library/re.html#re.UNICODE) My regex does not use any of those escapes, yet the regex changes behavior with the UNICODE flag. This leads to confusion when the regex doesn't match. The documentation is very specific about the behavior that changes with the flag, implying that behavior not mentioned is unaffected. Of course, it's easy to guess the correct (hopefully) solution. Still, I suggest changing the documentation to mention that re.IGNORECASE is affected. Looking at the source code, there seems to be further consequences (it mentions "Unicode locale") which may also warrant a mention. If you do want to avoid specifics, however, even a hand-wavy reference to something like "match according to Unicode" would help, because it implies that not only the escapes change behavior. In Python 3, there is a counterpart to the 2.7 problem: re.ASCII makes our Cyrillic string not match. Again, this behavior makes intuitive sense, but the documentation seems to indicate something different: re.ASCII Make \w, \W, \b, \B, \d, \D, \s and \S perform ASCII-only matching instead of full Unicode matching. This is only meaningful for Unicode patterns, and is ignored for byte patterns. … re.IGNORECASE Perform case-insensitive matching; expressions like [A-Z] will match lowercase letters, too. This is not affected by the current locale and works for Unicode characters as expected. re.ASCII does appear to affect re.IGNORECASE. Since this is the non-default case, however, I'm not sure it's worth calling it out. I'd be happy even if only the 2.7 docs change. ---------- assignee: docs@python components: Documentation messages: 248829 nosy: Leif Arne Storset, docs@python priority: normal severity: normal status: open title: It is undocumented that re.UNICODE affects re.IGNORECASE versions: Python 2.7, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24896> _______________________________________

8 14

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

Nov. 9, 2017

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

3 4

[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