Mailman 3 October 2019 - docs

[issue36868] New behavior of OpenSSL hostname verification not exposed, incorrectly documented
by Josh Rosenberg April 17, 2021

April 17, 2021

New submission from Josh Rosenberg <shadowranger+python(a)gmail.com>: The What's New in 3.7 docs mention the change from #31399 to use OpenSSL's built-in hostname verification ( https://docs.python.org/3/whatsnew/3.7.html#ssl ), but aside from that, information about the change is largely undiscoverable and/or wrong. Specific problems: 1. The What's New docs repeatedly mention SSLContext.host_flags as the means of modifying behavior. The actual property is underscore prefixed though, … [View More]as SSLContext._host_flags. Since SSLContext supports the creation of arbitrary names via __dict__, assigning to context.host_flags silently "works", it just fails to *do* anything (nothing ever reads it). 2. None of the flags are documented anywhere; the only way to discover them is to import _ssl (they're not exposed on ssl itself, just the internal C extension), then scan through the exposed names (they're all prefixed with HOSTFLAG_ AFAICT) 3. All of the flags are raw numeric values, but it seems like they should be IntEnums, like the other flags exposed by SSL (among other things, it would make it much easier to interpret the default _host_flags (currently it's just 4, when it could display as <HostFlags.HOSTFLAG_NO_PARTIAL_WILDCARDS: 4>) 4. Nothing about this change, _host_flags/host_flags, or the values of the flags themselves is mentioned on the ssl docs at all. 5. This unintentionally made a behavioral change (one that bit me, and may bite other folks using docker swarm, NETBIOS hostnames, etc.). Python's match_hostname implementation was fine with host names containing underscores (e.g. if the cert was wildcarded to *.example.com, it would match a_b_c.example.com just fine); they're not technically legal by the strict reading of the specs for host names (they're apparently legal for domain names, but not host names, which differ in ways I don't fully understand), but stuff like docker swarm names their services that way automatically, most (all?) browsers support visiting them, etc. It looks like OpenSSL (at least the 1.1.0g my Python 3.7.2 was built against) treats underscores as unmatchable, so any attempt to connect to such a host name in Python 3.7.2 dies with a SSLCertVerificationError, claiming a "Hostname mismatch, certificate is not valid for 'name_with_underscores.example.com'." I discovered all this because 3.7 broke some scripts I use to connect to docker swarm services. Before I realized the issue was underscores, I was trying to figure out how to tweak the host name checks (assuming maybe something was broken with wildcard matching), and stumbled across all the other issues with the docs, the lack of flag definition exposure, etc. For the record, I think it's reasonable to require legal host names (it was easy enough to fix for my case; I just updated our docker DNS server to provide aliases using only hyphens and changed the script to use the alias host names), but it would be nice if it was explicitly documented, and ideally, that Python itself recognize that underscores won't work and explicitly raise an exception saying why, rather than letting OpenSSL perform the rejection with a (to someone who doesn't know about the underscore issue) confusing error message. ---------- assignee: docs@python components: Documentation, Extension Modules, Library (Lib), SSL keywords: 3.6regression messages: 341990 nosy: christian.heimes, docs@python, josh.r, vstinner priority: normal severity: normal status: open title: New behavior of OpenSSL hostname verification not exposed, incorrectly documented type: behavior versions: Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36868> _______________________________________ [View Less]

5 8

[issue34078] Broken CRL functionality in ssl.py
by Joe N April 17, 2021

April 17, 2021

New submission from Joe N <nettijoe(a)gmail.com>: CRLs in ssl.py or at the documentation is broken. Specifically I think the documentation here is wrong: https://docs.python.org/3/library/ssl.html#ssl.SSLContext.load_verify_locat… Here is a stackoverflow post: https://stackoverflow.com/questions/51196492/how-to-use-crls-in-pyopenssl?n… I made a very user friendly test suite of files to show how it is broken. Run the code in here (follow readme instructions) to see the bug. https://… [View More]

2 2

[issue22128] patch: steer people away from codecs.open
by Frank van Dijk April 16, 2021

April 16, 2021

New submission from Frank van Dijk: stackoverflow.com has a zillion answers recommending the use of codecs.open() as a unicode capable drop in replacement for open(). This probably means that there is still a lot of code being written that uses codecs.open(). That's bad thing because of codecs.open()'s lack of newline conversion. A lot of that code will - have compatibility issues when it is moved between unix and windows - silently break text files on windows, leading to issues further … [View More]

7 11

[issue37741] importlib.metadata docs not showing up in the module index
by Brett Cannon April 15, 2021

April 15, 2021

New submission from Brett Cannon <brett(a)python.org>: If you look at https://docs.python.org/3.9/py-modindex.html#cap-i you will see that importlib.metadata isn't listed (same goes for the 3.8 docs). Or are you leaving it out due to it being provisional? ---------- assignee: docs@python components: Documentation messages: 348872 nosy: barry, brett.cannon, docs@python, jaraco priority: normal severity: normal status: open title: importlib.metadata docs not showing up in the module … [View More]

7 19

[issue28197] range.index mismatch with documentation
by Vedran Čačić April 14, 2021

April 14, 2021

New submission from Vedran Čačić: Look at this: >>> from collections.abc import Sequence >>> help(Sequence.index) index(self, value, start=0, stop=None) S.index(value, [start, [stop]]) -> integer -- return first index of value. Raises ValueError if the value is not present. >>> issubclass(range, Sequence) True >>> help(range.index) index(...) rangeobject.index(value, [start, [stop]]) -> integer -- … [View More]

6 17

[issue20364] Rename & explain sqlite3.Cursor.execute 'parameters' param
by Terry J. Reedy April 14, 2021

April 14, 2021

New submission from Terry J. Reedy: "execute(sql[, parameters]) Executes an SQL statement. The SQL statement may be parametrized (i. e. placeholders instead of SQL literals). The sqlite3 module supports two kinds of placeholders: question marks (qmark style) and named placeholders (named style)." Experimental facts based on experiments with the code example in the doc, using 3.4.b2: 'parameters' is a single subscriptable collection parameter, sequence or dict, that might be called … [View More]

7 12

[issue34398] Docs search does not index glossary
by Jonathan Fine April 2, 2021

April 2, 2021

New submission from Jonathan Fine <jfine2358(a)gmail.com>: The docs contain a very useful page https://docs.python.org/3.5/glossary.html. However, the search feature does not index the glossary. Thus, the search https://docs.python.org/3.5/search.html?q=iterable does not produce the helpful glossary entry === iterable An object capable of returning its members one at a time. Examples of iterables include all sequence types (such as list, str, and tuple) and some non-sequence types like … [View More]

6 12

[issue35026] Winreg's documentation lacks mentioning required permission at some points
by George Fischhof March 28, 2021

March 28, 2021

New submission from George Fischhof <george(a)fischhof.hu>: Winreg's documentation lacks mentioning required permission at some points Hi there, on page https://docs.python.org/3/library/winreg.html it is not mentioned in the description of the following functions: winreg.DeleteKey winreg.DeleteKeyEx winreg.DeleteValue that they require KEY_SET_VALUE when the registry key is opened. It is mentioned for example at: winreg.SetValue with the following text: The key identified by the … [View More]

4 4

[issue21297] skipinitialspace in the csv module only skips spaces, not "whitespace" in general
by Daniel Andersson March 25, 2021

March 25, 2021

New submission from Daniel Andersson: Regarding the `skipinitialspace` parameter to the different CSV reader dialects in the `csv` module, the official documentation asserts: When True, whitespace immediately following the delimiter is ignored. and the `help(csv)` style module documentation says: * skipinitialspace - specifies how to interpret whitespace which immediately follows a delimiter. It defaults to False, which means that whitespace immediately following a … [View More]

6 9

[issue37405] socket.getsockname() returns string instead of tuple
by Brent Gardner March 23, 2021

March 23, 2021

New submission from Brent Gardner <bggardner(a)gmail.com>: In Python 3.5.3, a socket with type AF_CAN returns a tuple in the form `(interface, )` from getsockname(). In Python 3.7.3, getsockname() returns a string (the name of the interface). The documentation states "a tuple is used for the AF_CAN address family". The string will break code that worked in 3.5.3 by raising errors such as "Value Error: too many values to unpack (expected 2)". Example: #3.5.3 import socket s = socket.… [View More]

6 11