Mailman 3 June 2018 - docs

[issue32603] Deprecation warning on strings used in re module
by Cheryl Sabella Jan. 20, 2019

Jan. 20, 2019

New submission from Cheryl Sabella <chekat2(a)gmail.com>: I apologize if this is a duplicate question, but I couldn't find another issue about this. It's hard to search on 're'. In 3.7, I get a deprecation warning when using a regular string with re escape characters: >>> s = '123abcd' >>> re.findall('\d', s) <stdin>:1: DeprecationWarning: invalid escape sequence \d ['1', '2', '3'] Of course, this works: >>> s = '123abcd' >>> re.findall(r'\d', s) ['1', '2', '3'] I know that the documentation strongly suggests using raw strings with re, but I didn't see anywhere mentioning that it would be a requirement. I would think this would break a lot of 're' code. ---------- assignee: docs@python components: Documentation messages: 310300 nosy: csabella, docs@python priority: normal severity: normal status: open title: Deprecation warning on strings used in re module type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32603> _______________________________________

4 6

[issue33995] test_min_max_version in test_ssl.py fails when Python is built against LibreSSL; {min,max}imum_version behavior differs from OpenSSL
by Alan Huang Jan. 18, 2019

Jan. 18, 2019

New submission from Alan Huang <Alan.Huang(a)utdallas.edu>: LibreSSL's implementation of the function used to get the minimum and maximum SSL versions supported differs from OpenSSL's. In short, the issue is in the implementations of `SSL_CTX_new` - OpenSSL initializes variables `ret->{min,max}_proto_version` to 0, while LibreSSL initializes corresponding variables to those of the `SSL_METHOD` given. As such, when Python is built with LibreSSL, the default values for an instance of ssl.SSLContext are, in the case of ssl.SSLContext(), ctx.minimum_version = <TLSVersion.TLSv1: 769>; ctx.maximum_version = <TLSVersion.TLSv1_2: 771>. This is NOT what test_ssl.py expects; it expects OpenSSL's behavior of initializing the version variables to zero, which _ssl.c then translates to PY_PROTO_{MIN,MAX}IMUM_SUPPORTED -> ssl.TLSVersion.{MIN,MAX}IMUM_SUPPORTED. Additionally, LibreSSL, when `SSL_CTX_set_{min,max}_proto_version` is called with `version` equal to zero, explicitly sets the minimum / maximum values equal to the minimum / maximum values for the `SSL_METHOD` it was called with (namely, 769/770/771, in the case of `TLS_method()`), not the minimum / maximum values supported by the library. I have sent an email to the LibreSSL mailing list asking for clarification on this point, namely, if this is intended behavior. If it is, there are two ways that come to mind to work around this behavior. Both ways would only be necessary if `IS_LIBRESSL`. 1. Skip `test_min_max_version`. 2. Instead of testing that ctx is equal *to* the extremes after it's been set to one of the extremes, test that it's equal to the actual constants. There are two ways this could be accomplished as well: a. Use PY_PROTO_{MIN,MAX}IMUM_AVAILABLE, defined in _ssl.c (this may require the addition of another call to `PyModule_AddIntConstant` to provide access to the constant from _ssl). The downside to this approach is that it assumes that `TLS_method()`, or whatever `SSL_METHOD` test_ssl.py uses has lower and upper bounds equal to PY_PROTO_{MIN,MAX}IMUM_AVAILABLE, which may not always be the case. b. Access and store the values for ctx.{min,max}imum_value on creation, then reference them after setting. Either of these approaches would likely also have the benefit of removing the need for `self.assertIn(ctx.minimum_version, {ssl.TLSVersion.TLSv1_2, ssl.TLSVersion.TLSv1_3})`. The test that failed was: ====================================================================== FAIL: test_min_max_version (test.test_ssl.ContextTests) ---------------------------------------------------------------------- Traceback (most recent call last): File "/home/alan/src/cpython/Lib/test/test_ssl.py", line 1066, in test_min_max_version ctx.minimum_version, ssl.TLSVersion.MINIMUM_SUPPORTED AssertionError: <TLSVersion.TLSv1: 769> != <TLSVersion.MINIMUM_SUPPORTED: -2> Addendum: I found the documentation for ssl.TLSVersion.{MAX,MIN}IMUM_SUPPORTED confusing at first - it took me quite a while to realize what the purpose of the constants were; I would have expected them to contain the maximum and minimum protocol versions supported by the library; I see why it was phrased that way, after having boned up on ssl.py, _ssl.c, and OpenSSL/LibreSSL, but think it could could be made clearer. ---------- assignee: docs@python components: Documentation, SSL, Tests messages: 320703 nosy: Alan.Huang, alex, christian.heimes, docs@python, dstufft, janssen priority: normal severity: normal status: open title: test_min_max_version in test_ssl.py fails when Python is built against LibreSSL; {min,max}imum_version behavior differs from OpenSSL type: behavior versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33995> _______________________________________

2 4

[issue23156] Update tix install information in tkinter tix chapter of doc
by Terry J. Reedy Jan. 18, 2019

Jan. 18, 2019

New submission from Terry J. Reedy: Update tix install info in doc. "Using tix" starts with 3 lines for testing one's tix install and continues '''If this fails, you have a Tk installation problem which must be resolved before proceeding. Use the environment variable TIX_LIBRARY to point to the installed Tix library directory, and make sure you have the dynamic object library (tix8183.dll or libtix8183.so) in the same directory that contains your Tk dynamic object library (tk8183.dll or libtk8183.so). The directory with the dynamic object library should also have a file called pkgIndex.tcl (case sensitive), which contains the line: package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix]''' Almost nothing above matches my working-with-tix 3.4.2 Win 7 install. I do have a tix library directory: python34/tcl/tix8.4.3, but the version number is much newer. Since it is in the right place, TIX_LIBRARY is not needed and there is none. python34/DLLs contains tcl86t.dll and tk86t.dll and NO tix####.dll. Is the once separate tix dll now part of tk dll? I cannot find pkgIndex.tcl; it is certainly not in the DLLs directory nor in the /tcl. The current doc seems useless to people who do not have tix working. See, for example, https://stackoverflow.com/questions/27751923/tix-widgets-installation-issue which is a semi-repeat question and which claims seeing similar reports elsewhere on the net. ---------- assignee: docs@python components: Documentation, Tkinter messages: 233368 nosy: docs@python, serhiy.storchaka, terry.reedy, zach.ware priority: normal severity: normal stage: needs patch status: open title: Update tix install information in tkinter tix chapter of doc type: behavior versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23156> _______________________________________

5 13

[issue30487] DOC: automatically create a venv and install Sphinx when running make
by Caleb Hattingh Jan. 6, 2019

Jan. 6, 2019

New submission from Caleb Hattingh: Under guidance from zware during Pycon sprints, I've changed the Doc/ Makefile to automatically create a virtual environment and install Sphinx, all as part of the `make html` command. ---------- assignee: docs@python components: Documentation messages: 294556 nosy: cjrh, docs@python, willingc, zach.ware priority: normal pull_requests: 1909 severity: normal status: open title: DOC: automatically create a venv and install Sphinx when running make versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30487> _______________________________________

5 19

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

Jan. 4, 2019

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

4 12

[issue29886] links between binascii.{un, }hexlify / bytes.{, to}hex
by chrysn Dec. 26, 2018

Dec. 26, 2018

New submission from chrysn: The function binascii.{un,}hexlify and bytes.{,to}hex do almost the same things (plus/minus details of whether they accept whitespace, and whether the hex-encoded data is accepted/returned as strings or bytes). I think that it would help users to point that out in the documentation, eg. by adding a "Similar functionality is provided by the ... function." lines at the ends of the functions' documentations. ---------- assignee: docs@python components: Documentation messages: 290050 nosy: chrysn, docs@python priority: normal severity: normal status: open title: links between binascii.{un,}hexlify / bytes.{,to}hex type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29886> _______________________________________

4 8

[issue32070] Clarify the behavior of the staticmethod builtin
by Jesse SHapiro Dec. 25, 2018

Dec. 25, 2018

New submission from Jesse SHapiro <jesse(a)jesseshapiro.net>: It looks like the original staticmethod docstring might have been based on the classmethod docstring, and it seems like the current description might not be accurate. Current string: ...It can be called either on the class (e.g. C.f()) or on an instance (e.g. C().f()); the instance is ignored except for its class... Proposed change: It can be called either on the class (e.g. C.f()) or on an instance (e.g. C().f()). Both the class and the instance are ignored, and neither is passed implicitly as the first argument to the method. ---------- assignee: docs@python components: Documentation messages: 306489 nosy: docs@python, haikuginger priority: normal pull_requests: 4391 severity: normal status: open title: Clarify the behavior of the staticmethod builtin type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32070> _______________________________________

3 3

[issue18085] Verifying refcounts.dat
by Serhiy Storchaka Dec. 20, 2018

Dec. 20, 2018

New submission from Serhiy Storchaka: I found one error in Doc/data/refcounts.dat (see issue9369, second argument of PyObject_CallMethodObjArgs is `PyObject*`, not `char*`). Perhaps there are other errors. How this file was generated first? Is it possible to write a tool which will automatically verify at least signatures of functions? ---------- assignee: docs@python components: Documentation messages: 190236 nosy: docs@python, serhiy.storchaka, skip.montanaro priority: normal severity: normal status: open title: Verifying refcounts.dat type: behavior versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18085> _______________________________________

8 24

[issue32077] Documentation: Some Unicode object functions don't indicate whether they return a new reference
by Mathew M. Dec. 19, 2018

Dec. 19, 2018

New submission from Mathew M. <mathew1800(a)gmail.com>: This is just something I've noticed when browsing the C API documentation for Unicode objects. For example, the documentation entry for PyUnicode_DecodeMBCSStateful lacks the "Return value: New reference", etc. ---------- assignee: docs@python components: Documentation messages: 306516 nosy: Mathew M., docs@python priority: normal severity: normal status: open title: Documentation: Some Unicode object functions don't indicate whether they return a new reference type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32077> _______________________________________

3 9

[issue33460] ... used to indicate many different things in chapter 3, some are confusing
by Lew Kurtz Dec. 19, 2018

Dec. 19, 2018

New submission from Lew Kurtz <lew.kurtz(a)icloud.com>: https://docs.python.org/3/tutorial/introduction.html uses ... to mean 5 or 6 different things. Since ... is continuation prompt, some of these other uses on that page are confusing - at least they were to this newbie. The most confusing are where it is used to hide output in the error messages. If someone has the patience to send me pointers on how to fix this, I would love to fix this myself. -Lew ps. the section headers in chapter 3 also need some work, 3.1.1 is the only section that is really about python being a calculator 3.1.2 and 3.1.3 don't seem very 'calculator-y' - Id like to fix this too. ---------- assignee: docs@python components: Documentation messages: 316381 nosy: docs@python, lew18 priority: normal severity: normal status: open title: ... used to indicate many different things in chapter 3, some are confusing type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33460> _______________________________________

5 7