docs January 2020

docs@python.org

27 participants
430 discussions

[issue34078] Broken CRL functionality in ssl.py

by Joe N

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://github.com/nettijoe96/bugInSSL ---------- assignee: christian.heimes components: SSL messages: 321343 nosy: Joe N, christian.heimes, docs@python priority: normal severity: normal status: open title: Broken CRL functionality in ssl.py type: behavior versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34078> _______________________________________

6 months

[issue22128] patch: steer people away from codecs.open

by Frank van Dijk

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 downstream (confusing other tools, messing up revision control histories) The problem has been fixed with io.open() in 2.x and open() in 3.x. Unfortunately the 2.7 unicode HOWTO still recommends the use of codecs.open(). The 2.7 and the 3.x documentation of codecs.open() doesn't refer the reader to better alternatives. The attached patches fix that. The only downside I see is that newly written code that uses the better alternatives would be incompatible with 2.5 and older. However croaking on a small minority of systems is better than silently disrupting workflows, causing platform incompatibilities, and inviting flaky workarounds. The 2.7 patch makes the unicode HOWTO recommend io.open() instead of codecs.open(). Both patches change the codecs.open() documentation to refer to io.open() or (on 3.x) open(). Additionally I removed the "data loss" explanation from codecs.open()'s note about its lack of newline conversion. It is not particularly helpful information and it is not entirely correct (data loss could also have been avoided by doing newline conversion before encoding and after decoding) ---------- assignee: docs@python components: Documentation files: codecsopen2.patch keywords: patch messages: 224632 nosy: Frank.van.Dijk, docs@python priority: normal severity: normal status: open title: patch: steer people away from codecs.open type: behavior versions: Python 2.7, Python 3.4, Python 3.5 Added file: http://bugs.python.org/file36234/codecsopen2.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22128> _______________________________________

6 months, 1 week

[issue37741] importlib.metadata docs not showing up in the module index

by Brett Cannon

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 index versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37741> _______________________________________

6 months, 1 week

[issue28197] range.index mismatch with documentation

by Vedran Čačić

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 -- return index of value. Raise ValueError if the value is not present. So far, so good. But: >>> range(9).index(2, 1, 5) TypeError: index() takes exactly one argument (3 given) Of course it's not essential, but the docs shouldn't lie. And if range _is_ a Sequence, then it should have the complete interface of a Sequence. Including start and end arguments for .index: they are optional from the point of call, not from the point of implementation. :-) ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 276908 nosy: docs@python, veky priority: normal severity: normal status: open title: range.index mismatch with documentation type: behavior versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28197> _______________________________________

6 months, 1 week

[issue20364] Rename & explain sqlite3.Cursor.execute 'parameters' param

by Terry J. Reedy

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 seq_dict. It is positional only, so whatever name is used is a dummy. Only one placeholder style can be used in a given SQL statement string. If question marks are used, seq_dict must be a sequence. If names are used, seq_dict can be either a sequence or dict or subclass thereof. A UserDict is treated as a sequence and raises KeyError(0). Possible text that encompasses the above, replacing the last sentence: "A statement may use one of two kinds of placeholders: question marks (qmark style) or named placeholders (named style). For qmark style, seq_dict must be a sequence. For named style, it can be either a sequence or dict instance. Len(seq_dict) must match the number of placeholders." After cleaning up the test file, I will verify on 2.7 and upload. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 208908 nosy: docs@python, terry.reedy priority: normal severity: normal stage: patch review status: open title: Rename & explain sqlite3.Cursor.execute 'parameters' param type: behavior versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20364> _______________________________________

6 months, 1 week

[issue39125] Type signature of @property not shown in help()

by Nguyễn Gia Phong

New submission from Nguyễn Gia Phong <vn.mcsinyx(a)gmail.com>: Dear Maintainer, I want to request a feature on the generative documentation of type-hinting. As of December 2019, I believe there is no support for generating such information in help(). For demonstration, I have this tiny piece of code class Foo: @property def bar(self) -> int: return 42 @bar.setter def bar(self, value: int) -> None: pass def baz(self, arg: float) -> str: pass whose documentation on CPython 3.7.5 (on Debian testing amd64 if that matters) is generated as class Foo(builtins.object) | Methods defined here: | | baz(self, arg: float) -> str | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables (if defined) | | __weakref__ | list of weak references to the object (if defined) | | bar I expect the documentation for bar to be as informative as bar, i.e. something similar to ``bar: int''. As pointed out by ChrisWarrick on freenode#python, the annotations are already present, yet help() is not making use of them: >>> Foo.bar.fget.__annotations__ {'return': <class 'int'>} >>> Foo.bar.fset.__annotations__ {'value': <class 'int'>, 'return': None} Have a Merry Christmas or other holiday of your choice, Nguyễn Gia Phong ---------- assignee: docs@python components: Documentation messages: 358823 nosy: McSinyx, docs@python priority: normal severity: normal status: open title: Type signature of @property not shown in help() type: enhancement versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39125> _______________________________________

6 months, 1 week

[issue38963] multiprocessing processes seem to "bleed" user information (GID/UID/groups)

by Roman Joost

New submission from Roman Joost <roman(a)bromeco.de>: When running a process which changes UID/GID, some of the following processes will run as the user I change to per process. In order to reproduce (see the attached reproducer): 1. Change the 'USERNAME' to an unprivileged user on your system. 2. Run the reproducer as a user with elevated privileges (e.g. root or some secondary user you have on your system). Mind you, I don't think the user you run as needs elevated privileges, but that's the user I ran as when I observed this behaviour. 3. The reproducer iterates over a list (It stems from a test function which was checking permissions on log files). Observe the print out, which prints the process' GID, UID and secondary groups before we're changing to the users GID, UID and secondary groups. 4. You should observe that at some point the process prints the user information of the user we want to change to not the one which initially started the script. Example output when running locally as root: ('B', (0, 0, [0])) ('A', (0, 0, [0])) ('C', (0, 0, [0])) ('E', (0, 0, [0])) ('D', (0, 0, [0])) ('F', (1002, 1002, [10, 135, 1000, 1002])) ('H', (1002, 1002, [10, 135, 1000, 1002])) ('I', (1002, 1002, [10, 135, 1000, 1002])) ('J', (1002, 1002, [10, 135, 1000, 1002])) ('G', (1002, 1002, [10, 135, 1000, 1002])) ('K', (1002, 1002, [10, 135, 1000, 1002])) ('L', (1002, 1002, [10, 135, 1000, 1002])) ('M', (1002, 1002, [10, 135, 1000, 1002])) ('N', (1002, 1002, [10, 135, 1000, 1002])) I would have expected `0` all the way through. However, if I initialise the Pool with `maxtasksperchild=1` the isolation seems as expected. I don't know whether this is a bug or I'm foolish to invoke multiprocessing like this. I've run out of time to investigate this further. It's certainly strange behaviour to me and I thought I better report it, since reproducing seems fairly deterministic. ---------- assignee: docs@python components: Documentation, Library (Lib) files: reproducer.py messages: 357773 nosy: docs@python, romanofski priority: normal severity: normal status: open title: multiprocessing processes seem to "bleed" user information (GID/UID/groups) type: behavior versions: Python 3.6, Python 3.7 Added file: https://bugs.python.org/file48753/reproducer.py _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38963> _______________________________________

6 months, 2 weeks

[issue34398] Docs search does not index glossary

by Jonathan Fine

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 dict, file objects, and objects of any [...] === #788509 is the only docs issue I could find, whose title contains glossary. It gives insight into the thoughts then about the tutorial. In msg44460 Skip Montaro says (1) that the glossary is "for the tutorial", and (2) he'd like to improve links into the tutorial. I suggest that part of the fix for this issue is on the home page page Glossary in the first grouping "Parts of the documentation." ---------- assignee: docs@python components: Documentation messages: 323503 nosy: docs@python, jfine2358 priority: normal severity: normal status: open title: Docs search does not index glossary type: behavior versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34398> _______________________________________

6 months, 3 weeks

[issue35026] Winreg's documentation lacks mentioning required permission at some points

by George Fischhof

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 key parameter must have been opened with KEY_SET_VALUE access. BR, George ---------- assignee: docs@python components: Documentation messages: 328034 nosy: docs@python, georgefischhof priority: normal severity: normal status: open title: Winreg's documentation lacks mentioning required permission at some points type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35026> _______________________________________

6 months, 3 weeks

[issue39231] Mistaken notion in tutorial

by Robert

New submission from Robert <freshbob1337(a)gmail.com>: https://docs.python.org/3/tutorial/controlflow.html 4.7.8. Function Annotations [...] "The following example has a positional argument, a keyword argument, and the return value annotated:" It is not a "positional argument" but an "optional argument". ---------- assignee: docs@python components: Documentation messages: 359443 nosy: docs@python, r0b priority: normal severity: normal status: open title: Mistaken notion in tutorial type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39231> _______________________________________

6 months, 3 weeks

Jump to page:

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

docs January 2020