Mailman 3 December 2016 - docs

[issue29092] Sync os.stat's doc and doc string
by Xiang Zhang Jan. 22, 2017

Jan. 22, 2017

New submission from Xiang Zhang: The accepted types of parameter *path* are different between os.stat's doc and doc string. In doc, it mentions Pathlike, string and file descriptor. In doc string, it mentions string, bytes and file descriptor. (3.5 only lack bytes in doc). ---------- assignee: docs@python components: Documentation files: doc-os-stat.patch keywords: patch messages: 284167 nosy: docs@python, xiang.zhang priority: normal severity: normal stage: patch review status: open title: Sync os.stat's doc and doc string versions: Python 3.5, Python 3.6, Python 3.7 Added file: http://bugs.python.org/file46061/doc-os-stat.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29092> _______________________________________

3 4

[issue15997] NotImplemented needs to be documented
by Max Jan. 22, 2017

Jan. 22, 2017

New submission from Max: Quoting from http://docs.python.org/reference/datamodel.html#the-standard-type-hierarchy: NotImplemented This type has a single value. There is a single object with this value. This object is accessed through the built-in name NotImplemented. Numeric methods and rich comparison methods may return this value if they do not implement the operation for the operands provided. (The interpreter will then try the reflected operation, or some other fallback, depending on the operator.) Its truth value is true. This is not a sufficient description of NotImplemented behavior. What does it mean "reflected operation" (I assume it is other.__eq__(self), but it needs to be clarified), and what does it mean "or some other fallback" (wouldn't developers need to know?). It also doesn't state what happens if the reflected operation or the fallback again return NotImplemented. The rest of the documentation doesn't seem to talk about this either, despite several mentions of NotImplemented, with references to other sections. This is particularly serious problem because Python's behavior changed in this respect not that long ago. ---------- assignee: docs@python components: Documentation messages: 170860 nosy: docs@python, max priority: normal severity: normal status: open title: NotImplemented needs to be documented type: enhancement versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15997> _______________________________________

6 9

[issue28785] Clarify the behavior of NotImplemented
by Max Jan. 22, 2017

Jan. 22, 2017

New submission from Max: Currently, there's no clear statement as to what exactly the fallback is in case `__eq__` returns `NotImplemented`. It would be good to clarify the behavior of `NotImplemented`; at least for `__eq__`, but perhaps also other rich comparison methods. For example: "When `NotImplemented` is returned from a rich comparison method, the interpreter behaves as if the rich comparison method was not defined in the first place." See http://stackoverflow.com/questions/40780004/returning-notimplemented-from-eq for more discussion. ---------- assignee: docs@python components: Documentation messages: 281616 nosy: docs@python, max priority: normal severity: normal status: open title: Clarify the behavior of NotImplemented type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28785> _______________________________________

2 4

[issue29062] Documentation link error
by Frank Millman Jan. 14, 2017

Jan. 14, 2017

New submission from Frank Millman: If you call up online documentation for Python3.6, and select modules>h>hashlib, it takes you to 15.2. hashlib — BLAKE2 hash functions It should take you to 15.1. hashlib — Secure hashes and message digests ---------- assignee: docs@python components: Documentation messages: 283930 nosy: docs@python, frankmillman priority: normal severity: normal status: open title: Documentation link error type: behavior versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29062> _______________________________________

7 27

[issue15527] Double parents in functions references
by Serhiy Storchaka Jan. 14, 2017

Jan. 14, 2017

New submission from Serhiy Storchaka: :c:func:`PyMem_Malloc(n)` on Doc/c-api/memory.rst:109 rendered in HTML as <tt class="xref c c-func docutils literal"><span class="pre">PyMem_Malloc(1)()</span></tt> (note double parents). There are many other examples on this and other pages. The issue is actual for all modern versions of Python. ---------- assignee: docs@python components: Documentation messages: 167137 nosy: docs@python, storchaka priority: normal severity: normal status: open title: Double parents in functions references versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15527> _______________________________________

6 22

[issue28130] Document that time.tzset updates time module constants
by Alexander Belopolsky Jan. 12, 2017

Jan. 12, 2017

New submission from Alexander Belopolsky: Reported by MAL in #22798 (msg251840): "The fact that tzset() does update the module globals is not documented." The documentation should explicitly list timezone, daylight, altzone and tzname as the globals that are updated when time.tzset() is called. ---------- assignee: docs@python components: Documentation keywords: easy messages: 276294 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: Document that time.tzset updates time module constants versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28130> _______________________________________

5 9

[issue29002] typing.AnyStr doc is unclear about python2 unicode support
by Alex Jurkiewicz Jan. 7, 2017

Jan. 7, 2017

New submission from Alex Jurkiewicz: The typing.AnyStr documentation: https://docs.python.org/3/library/typing.html#typing.AnyStr It gives some examples using u-strings (u'foo') but doesn't make explicit some subtleties about behaviour with Python 2. Specifically, with Python 2 all the given examples work, and even this works: concat("foo", u"bar") Which seems contrary to the goal of AnyStr being "used for functions that may accept any kind of string without allowing different kinds of strings to mix". I think the documentation should call out that for Python 2, AnyStr doesn't distinguish between str & unicode, and mention that in python 2, b'str' is equivalent to 'str' (I know this is mentioned elsewhere, but it seems useful to repeat it here). ---------- assignee: docs@python components: Documentation messages: 283524 nosy: aj, docs@python priority: normal severity: normal status: open title: typing.AnyStr doc is unclear about python2 unicode support type: enhancement versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29002> _______________________________________

4 4

[issue16026] csv.DictReader argument names documented incorrectly
by Peter Eisentraut Jan. 7, 2017

Jan. 7, 2017

New submission from Peter Eisentraut: The documentation for the csv.DictReader constructor is .. class:: DictReader(csvfile, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds) but the implementation is def __init__(self, f, fieldnames=None, restkey=None, restval=None, dialect="excel", *args, **kwds): The name of the first argument is documented incorrectly, leading to surprise errors when attempting to use key word arguments. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 171161 nosy: docs@python, petere priority: normal severity: normal status: open title: csv.DictReader argument names documented incorrectly type: behavior versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________

9 15

[issue29023] Results of random.seed() call with integer argument should be claimed deterministic.
by Jakub Mateusz Kowalski Jan. 7, 2017

Jan. 7, 2017

New submission from Jakub Mateusz Kowalski: In https://docs.python.org/2/library/random.html#random.seed I can find that "If a hashable object is given, deterministic results are only assured when PYTHONHASHSEED is disabled." Both int and long are hashable. However, tests on the random module as well as C source code of random_seed (as indicated in http://stackoverflow.com/a/41228062/4879688) suggest that behaviour of the module is deterministic when seeded with an integer. ---------- assignee: docs@python components: Documentation messages: 283686 nosy: Jakub.Mateusz.Kowalski, docs@python priority: normal severity: normal status: open title: Results of random.seed() call with integer argument should be claimed deterministic. versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29023> _______________________________________

3 6

[issue29012] __bases__ is a tuple (possibly empty or a singleton)
by Jim Fasarakis-Hilliard Jan. 3, 2017

Jan. 3, 2017

New submission from Jim Fasarakis-Hilliard: The following statement is in the Language Reference for Custom classes: > __bases__ is a tuple (possibly empty or a singleton) containing the base classes AFAIK, ``object.__bases__`` is the only object for which ``__bases__`` is empty and it isn't a *custom* class. Attempts to create a class and assign __bases__ to an empty tuple is checked to enforce inheritance from ``object``. This *seems* to be something that slipped through when the docs were created for Python 3.0? I'm curious to see if this can actually be empty, if not, attached patch removes ''empty'' from the sentence. ---------- assignee: docs@python components: Documentation files: fixbasesdoc.patch keywords: patch messages: 283595 nosy: Jim Fasarakis-Hilliard, docs@python priority: normal severity: normal status: open title: __bases__ is a tuple (possibly empty or a singleton) versions: Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 Added file: http://bugs.python.org/file45962/fixbasesdoc.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29012> _______________________________________

5 7