docs October 2020

docs@python.org

14 participants
351 discussions

[issue35083] Fix documentation for __instancecheck__
by Joy Diamond 15 Dec '20

15 Dec '20

New submission from Joy Diamond <python.gem(a)gmail.com>: This is a request to fix the documentation for __instancecheck__. Please add the following: """ (Note that any object `x` is always considered to be an instance of `type(x)`, and this cannot be overridden.) """ Consider the following program: class M(type): def __instancecheck__(m, t): print('instancecheck(%s, %s)' % (m, t)) return False # LIE! Test = M('Test', ((object,)), {}) something = Test() print('Does *NOT* call __instancecheck__:') print('isinstance(something, Test): %s' % isinstance(something, Test)) print() print('Does call __instancecheck__:') print('isinstance(0, Test): %s' % isinstance(0, Test)) Under python 2, python 3, and pypy, in all cases, the first examples does *NOT* call __instancecheck__. You can see the optimization here: https://github.com/python/cpython/blob/master/Objects/abstract.c#L2397-L2405 Which reads: int PyObject_IsInstance(PyObject *inst, PyObject *cls) { _Py_IDENTIFIER(__instancecheck__); PyObject *checker; /* Quick test for an exact match */ if (Py_TYPE(inst) == (PyTypeObject *)cls) return 1; I'm fine with the optimization -- I am not suggesting to get rid of it. I just want the documentation to match the actual implementation. The following documentation needs to be fixed: https://docs.python.org/2/reference/datamodel.html https://docs.python.org/3/reference/datamodel.html https://www.python.org/dev/peps/pep-3119/ It took me half an hour to figure out why my version of __instancecheck__ was not working, as I tried to test it using the super simple code above ... One of the best things about python is how accurate and consistent the documentation is. This request is to keep these high standards. ---------- assignee: docs@python components: Documentation messages: 328658 nosy: docs@python, joydiamond priority: normal severity: normal status: open title: Fix documentation for __instancecheck__ type: enhancement versions: Python 2.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35083> _______________________________________

5 6

[issue41879] Outdated description of async iterables in documentation of async for statement
by Nick Gaya 12 Dec '20

12 Dec '20

New submission from Nick Gaya <nicholasgaya+github(a)gmail.com>: The documentation for the `async for` statement incorrectly states that "An asynchronous iterable is able to call asynchronous code in its iter implementation". Actually, this behavior was deprecated in Python 3.6 and removed in Python 3.7. As of Python 3.7, the `__aiter__()` method must return an asynchronous iterator directly. Suggested fix: Update the `async for` statement description for Python 3.7+ to match the "Asynchronous Iterators" section in the data model documentation. > An :term:`asynchronous iterator` can call asynchronous code in its *next* method. Relevant documentation: - https://docs.python.org/3/reference/compound_stmts.html#the-async-for-state… - https://docs.python.org/3/reference/datamodel.html#asynchronous-iterators ---------- assignee: docs@python components: Documentation messages: 377621 nosy: docs@python, nickgaya priority: normal severity: normal status: open title: Outdated description of async iterables in documentation of async for statement versions: Python 3.10, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41879> _______________________________________

4 8

[issue26451] CSV documentation doesn't open with an example
by Alex LordThorsen 12 Dec '20

12 Dec '20

New submission from Alex LordThorsen: Had a friend get stuck on the CSV documentation. They didn't know what a CSV was (to start with) and couldn't find an example that made sense to them. they went to other sources to figure out how to read CSV files in the end. I made this patch in the hope that starting out with a very minimal example file format followed by an example python read will make landing on the CSV docs easier to follow for new programmers. ---------- assignee: docs@python components: Documentation files: csv_documentation.patch keywords: patch messages: 260960 nosy: Alex.LordThorsen, docs@python priority: normal severity: normal status: open title: CSV documentation doesn't open with an example versions: Python 3.6 Added file: http://bugs.python.org/file42040/csv_documentation.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26451> _______________________________________

2 2

[issue24110] zipfile.ZipFile.write() does not accept bytes arcname
by July Tikhonov 08 Dec '20

08 Dec '20

New submission from July Tikhonov: In documentation of zipfile.ZipFile.write() there is following notice: "There is no official file name encoding for ZIP files. If you have unicode file names, you must convert them to byte strings in your desired encoding before passing them to write()." I understand it as that 'arcname' argument to write() shouldn't be of type str, but rather bytes. But it is str that works, and bytes that does not: $ ./python Python 3.5.0a4+ (default:6f6e78931875, May 1 2015, 23:18:40) [GCC 4.8.4] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import zipfile >>> zf = zipfile.ZipFile('foo.zip', 'w') >>> zf.write('python', 'a') >>> zf.write('python', b'b') Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/home/july/source/python/Lib/zipfile.py", line 1442, in write zinfo = ZipInfo(arcname, date_time) File "/home/july/source/python/Lib/zipfile.py", line 322, in __init__ null_byte = filename.find(chr(0)) TypeError: a bytes-like object is required, not 'str' (ZipInfo ostensibly attempts to find a zero byte in the filename, but searches instead for a unicode character chr(0). There are several other places in ZipInfo class that assume filename being str rather than bytes.) I consider this a documentation issue: the notice is misleading. Although maybe there is someone who wants to fix the behavior of ZipInfo to allow bytes filename. ---------- assignee: docs@python components: Documentation messages: 242355 nosy: docs@python, july priority: normal severity: normal status: open title: zipfile.ZipFile.write() does not accept bytes arcname type: behavior versions: Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24110> _______________________________________

6 9

[issue41910] Document that object.__eq__ implements `a is b`
by Brett Cannon 08 Dec '20

08 Dec '20

New submission from Brett Cannon <brett(a)python.org>: If you look at the data model `for object.__eq__` (https://docs.python.org/3.8/reference/datamodel.html#object.__eq__) you will see that it doesn't mention any actual implementation (unlike for __ne__). But https://github.com/python/cpython/blob/v3.8.3/Objects/typeobject.c#L3834-L3… shows that object.__eq__ actually does have an implementation of `a is b`/`id(a) == id(b)`. ---------- assignee: docs@python components: Documentation messages: 377816 nosy: brett.cannon, docs@python priority: low severity: normal status: open title: Document that object.__eq__ implements `a is b` versions: Python 3.10, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41910> _______________________________________

3 16

[issue25573] traceback documentation example is lying about FrameSummary repr()
by Alexandre Macabies 07 Dec '20

07 Dec '20

New submission from Alexandre Macabies: https://docs.python.org/3.5/library/traceback.html#traceback-examples See second code sample and its sample output. According to the docs, the call: print(repr(traceback.extract_tb(exc_traceback))) is supposed to print something that looks like an array with only strings; that is what the doc sample output states: [('<doctest...>', 10, '<module>', 'lumberjack()'), But actually, in 3.5+, this call outputs the repr() of a list of FrameSummary instances that do not go further in repr()esenting their state: [<FrameSummary file <ipython-input-61-3e63d7daea82>, line 10 in <module>>, By looking at the docs I thought I was able to get a nice string representation of a FrameSummary. I actually have to format it myself. It should be reflected in the doc sample output. ---------- assignee: docs@python components: Documentation messages: 254224 nosy: Alexandre Macabies, docs@python priority: normal severity: normal status: open title: traceback documentation example is lying about FrameSummary repr() versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25573> _______________________________________

7 16

[issue38843] Document argparse behaviour when custom namespace object already has the field set
by Ivan Kurnosov 07 Dec '20

07 Dec '20

New submission from Ivan Kurnosov <zerkms(a)zerkms.com>: At this moment it's impossible to explain the behaviour of this script using documentation. Given it was explicitly coded to behave like that - it should be somehow noted in the documentation, that as long as a `CliArgs.foo` field has a default value set already - it won't be overwritten with a default argparse argument value. ``` import argparse class CliArgs(object): foo: str = 'not touched' parser = argparse.ArgumentParser() parser.add_argument('--foo', default='bar') args = CliArgs() parser.parse_args(namespace=args) print(args.foo) # 'not touched' print(parser.parse_args()) # 'bar' ``` ---------- assignee: docs@python components: Documentation messages: 356939 nosy: docs@python, zerkms priority: normal severity: normal status: open title: Document argparse behaviour when custom namespace object already has the field set _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38843> _______________________________________

5 11

[issue26582] asyncio documentation links to wrong CancelledError
by awilfox 04 Dec '20

04 Dec '20

New submission from awilfox: In the 3.5 and 3.6a0 documentation for asyncio, "CancelledError" is linked to the concurrent.futures.CancelledError. This led me to try catching that exception and finding that it did not work correctly at all. Only after searching for asyncio example code and seeing how other people caught asyncio.CancelledError did I realise the issue. The fact asyncio.CancelledError even exists isn't actually documented, and I believe that is why the :exc: reference is linking to the wrong module. ---------- assignee: docs@python components: Documentation messages: 261911 nosy: awilfox, docs@python priority: normal severity: normal status: open title: asyncio documentation links to wrong CancelledError versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26582> _______________________________________

8 9

[issue32830] tkinter documentation suggests "from tkinter import *", contradicting PEP8
by ChrisRands 01 Dec '20

01 Dec '20

New submission from ChrisRands <chrisrands0(a)gmail.com>: Issue arose from this SO post: https://stackoverflow.com/questions/48746351/documentation-is-contradicting… The tkinter documentation suggests: from tkinter import * https://docs.python.org/3/library/tkinter.html But this obviously contradicts PEP8: "Wildcard imports (from <module> import *) should be avoided" https://www.python.org/dev/peps/pep-0008/#imports Is tkinter a valid exception or is this a documentation bug? The commit of this line to the documentation is >10 years old (at least Python 2.4 I think): https://github.com/python/cpython/commit/116aa62bf54a39697e25f21d6cf6799f7f… ---------- assignee: docs@python components: Documentation messages: 312045 nosy: ChrisRands, docs@python priority: normal severity: normal status: open title: tkinter documentation suggests "from tkinter import *", contradicting PEP8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32830> _______________________________________

4 6

[issue15104] abusive language in __name__ description
by anatoly techtonik 01 Dec '20

01 Dec '20

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/__main__.html "It is this environment in which the idiomatic “conditional script” stanza causes a script to run" ?!? ---------- assignee: docs@python components: Documentation messages: 163140 nosy: docs@python, techtonik priority: normal severity: normal status: open title: abusive language in __name__ description _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

12 28

← Newer
1
...
9
10
11
12
13
14
15
...
36
Older →

Jump to page:

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

docs October 2020