Mailman 3 March 2017 - docs

[issue29236] 'an ASCII string of one or more PEM-encoded certificates' needs to be unicode
by Maciej Piechorka 31 May '20

31 May '20

New submission from Maciej Piechorka: In documentation it is specified that cadata parameter in load_verify_locations is 'an ASCII string of one or more PEM-encoded certificates'. However the code is actually determining it based on PyUnicode_Check function so the 'ASCII string' actually needs to be unicode object. In Python 3 it seems to be fixed by checking by PyObject_GetBuffer. ---------- assignee: docs@python components: Documentation, SSL messages: 285176 nosy: docs@python, uzytkownik priority: normal severity: normal status: open title: 'an ASCII string of one or more PEM-encoded certificates' needs to be unicode versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29236> _______________________________________

4 3

[issue29257] Possible error in discussion of Abstract Base Classes and abstract properties
by Gerald Britton 31 May '20

31 May '20

New submission from Gerald Britton: I was rereading the 2.7 docs about abstract base classes the other day. I found this: "This defines a read-only property; you can also define a read-write abstract property using the ‘long’ form of property declaration:" along with an example. so I copied the example and put in a little surrounding code: from abc import ABCMeta, abstractproperty class C: __metaclass__ = ABCMeta def getx(self): pass def setx(self, value): pass x = abstractproperty(getx, setx) class D(C): @property def x(self):self._x d = D() print(d) When I ran this, I expected an exception, since I defined a read/write abstract property but only implemented the read operation. However, the example runs fine. That is the class D can be instantiated without error. Of course I cannot set the property since I didn't implement that part. Now, If I don't implement the property at all, I can' instantiate the class. I get: "TypeError: Can't instantiate abstract class D with abstract methods x" which is what I would expect. What I don't understand is why I don't get a similar error when I implement the read operation for the property but not the write operation. If this actually doesn't work (catching the non-implementation at instantiation time), then why is it documented this way? To me at least the doc implies that it *will* raise on the missing write property implementation. If ABCs are working as intended, can the documentation be changed to reflect that as per my experience above? If the documentation is correct, can the ABC implementation be modified to function that way? ---------- assignee: docs@python components: Documentation messages: 285356 nosy: docs@python, gbritton priority: normal severity: normal status: open title: Possible error in discussion of Abstract Base Classes and abstract properties versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29257> _______________________________________

2 1

[issue29323] Wrong documentation (Library) for unicode and str comparison
by RK-5wWm9h 31 May '20

31 May '20

New submission from RK-5wWm9h: PROBLEM (IN BRIEF): In the currently published 2.7.13 The Python Standard Library (Library Reference manual) section 5.6 "Sequence Types" (https://docs.python.org/2/library/stdtypes.html#sequence-types-str-unicode-…): "to compare equal, ... the two sequences must be of the same type" This an *incorrect (and misleading) statement*, for the unicode and str case. PROPOSED FIX: Current full paragraph: "Sequence types also support comparisons. In particular, tuples and lists are compared lexicographically by comparing corresponding elements. This means that to compare equal, every element must compare equal and the two sequences must be of the same type and have the same length. (For full details see Comparisons in the language reference.)" Proposed replacement text: "Sequence types also support comparisons. In particular, tuples and lists are compared lexicographically by comparing corresponding elements. This means that to compare equal, every element must compare equal and the two sequences must be of the same type and have the same length. (Unicode and str are treated as the same type here; for full details see Comparisons in the language reference.)" DETAILS, JUSTIFICATION, CORRECTNESS, ETC: The current incorrect text is really misleading. The behaviour that a str and a unicode object -- despite being objects of different types -- may compare equal, is explicitly stated in the 2.7.13 The Python Language Reference manual, section 5.9 "Comparisons" (https://docs.python.org/2/reference/expressions.html#comparisons): "* Strings are compared lexicographically using the numeric equivalents (the result of the built-in function ord()) of their characters. Unicode and 8-bit strings are fully interoperable in this behavior. [4]" (Aside: Incidentally an earlier paragraph in the Language Ref fails to cover the unicode and str case; see separately filed bug Issue 29321.) ---------- assignee: docs@python components: Documentation messages: 285792 nosy: RK-5wWm9h, docs@python priority: normal severity: normal status: open title: Wrong documentation (Library) for unicode and str comparison type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29323> _______________________________________

4 5

[issue26433] urllib.urlencode() does not explain how to handle unicode
by Thomas Güttler 31 May '20

31 May '20

New submission from Thomas Güttler: The current docs for Python2, don't explain how to handle unicode: https://docs.python.org/2/library/urllib.html#urllib.urlencode It seems to be a common problem. See http://stackoverflow.com/questions/6480723/urllib-urlencode-doesnt-like-uni… It would be nice to document the most pythonic way to handle unicode in urllib.urlencode() ---------- assignee: docs@python components: Documentation messages: 260845 nosy: Thomas Güttler, docs@python priority: normal severity: normal status: open title: urllib.urlencode() does not explain how to handle unicode versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26433> _______________________________________

2 1

[issue24256] threading.Timer is not a class
by John Runyon 31 May '20

31 May '20

New submission from John Runyon: the documentation (https://docs.python.org/2/library/threading.html#threading.Timer) lists "threading.Timer" as a class. It is not, which means that (for example) you can not use it in isinstance(). "threading._Timer" is a class. "threading.Timer(...).__class__" is a class. "threading.Timer" is a function. >>> import threading >>> threading.Timer <function Timer at 0x7f99cae23848> ---------- assignee: docs@python components: Documentation messages: 243735 nosy: docs@python, jrunyon priority: normal severity: normal status: open title: threading.Timer is not a class versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24256> _______________________________________

5 6

[issue25511] multiprocessing pool blocks SIGTERM from being handled
by David Jones 31 May '20

31 May '20

New submission from David Jones: This is probably related to #21913, but more specifically concerns the documentation. I have a sub process of a larger program that handles a SIGTERM sent by the main process for a clean shutdown. However, if I launch a parallel task in the sub process, via multiprocessing.Pool.imap_unordered, all signals are blocked until pool finishes running the task. If this isn't going to be fixed, then it ought to at least be clearly documented. It took a very long time to diagnose this problem. It requires a programmer to understand the underlying implementation of a high-level construct, thus defeating the purpose of using a high level construct. Also, is there a way to work around this? ---------- assignee: docs@python components: Documentation messages: 253678 nosy: djones, docs@python priority: normal severity: normal status: open title: multiprocessing pool blocks SIGTERM from being handled type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25511> _______________________________________

2 1

[issue22052] Comparison operators called in reverse order for subclasses with no override.
by Mark Dickinson 31 May '20

31 May '20

New submission from Mark Dickinson: As reported in a StackOverflow question [1]: the order in which the special comparison methods are called seems to be contradictory to the docs [2]. In the following snippet, __eq__ is called with reversed operands first: >>> class A: ... def __eq__(self, other): ... print(type(self), type(other)) ... return True ... >>> class B(A): ... pass ... >>> A() == B() <class '__main__.B'> <class '__main__.A'> True However, the docs note that: """If the right operand’s type is a subclass of the left operand’s type and that subclass provides the reflected method for the operation, this method will be called before the left operand’s non-reflected method. This behavior allows subclasses to override their ancestors’ operations.""" ... which suggests that this reversal should only happen when the subclass B *overrides* A's definition of __eq__ (and indeed that's the usual behaviour for arithmetic operations like __add__). Looking more closely, that statement in the docs is in the 'numeric-types' section, so it's not clear that its rules should apply to the comparison operators. But either way, some doc clarification could be useful. [1] http://stackoverflow.com/q/24919375/270986 [2] https://docs.python.org/3.5/reference/datamodel.html#emulating-numeric-types ---------- assignee: docs@python components: Documentation messages: 223778 nosy: docs@python, mark.dickinson priority: normal severity: normal status: open title: Comparison operators called in reverse order for subclasses with no override. versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22052> _______________________________________

4 9

[issue23514] multiprocessing documentation - little more examples for parallel computing
by Cezary Wagner 31 May '20

31 May '20

New submission from Cezary Wagner: I am little confused with multiprocessing documentation since it does not contain enough examples. Parallel computing is not simple by design so documentation can be little improved to make it simpler. No pattern to use pool with classes. No pattern to exchange objects between processes. Understanding usage of Queue and SimpleQueue or JoinableQueue is not very clear. Current documentation in majority is good reference with very rare examples / patterns. ---------- assignee: docs@python components: Documentation messages: 236519 nosy: Cezary.Wagner, docs@python priority: normal severity: normal status: open title: multiprocessing documentation - little more examples for parallel computing _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23514> _______________________________________

3 4

[issue20296] PyArg_ParseTuple 2.X docs mention int for "t#", but "Py_ssize_t" for "w#", etc.
by Rob Browning 31 May '20

31 May '20

New submission from Rob Browning: Here (http://docs.python.org/2/c-api/arg.html), the documentation for "t#" says: t# (read-only character buffer) [char *, int]... while the documentation for "w#" says: w# (read-write character buffer) [char *, Py_ssize_t]... However, from getargs.c, it looks like they're handled the same with respect to the size type. At a minimum, it seems like it might make sense to change these docs to match, and if "w#" and "t#" are actually handled similarly to "s#", it would be even better to just change their docs to match (or refer to) "s#"'s which are more detailed, i.e. they mention the PY_SSIZE_T_CLEAN issues, etc. Thanks ---------- assignee: docs@python components: Documentation messages: 208410 nosy: docs@python, rlb priority: normal severity: normal status: open title: PyArg_ParseTuple 2.X docs mention int for "t#", but "Py_ssize_t" for "w#", etc. versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20296> _______________________________________

3 3

[issue21547] '!s' formatting documentation bug
by Joshua Landau 31 May '20

31 May '20

New submission from Joshua Landau: In the docs for 2.x about the formatting syntax: https://docs.python.org/2/library/string.html#format-string-syntax it says "Two conversion flags are currently supported: '!s' which calls str() on the value, and '!r' which calls repr()." but for unicode formatters, '!s' calls unicode() instead. See http://stackoverflow.com/questions/23773816/why-python-str-format-doesnt-ca… for the question that found this. ---------- assignee: docs@python components: Documentation messages: 218863 nosy: Joshua.Landau, docs@python priority: normal severity: normal status: open title: '!s' formatting documentation bug versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21547> _______________________________________

5 4