Mailman 3 February 2019 - docs

[issue8822] datetime naive and aware types should have a well-defined definition that can be cross-referenced
by anatoly techtonik Dec. 29, 2020

Dec. 29, 2020

New submission from anatoly techtonik <techtonik(a)gmail.com>: 'naive' and 'aware' are key datetime types - they need a proper definition and anchor for crossrefences. If you take a look at http://docs.python.org/library/datetime.html - the definition of distinction between them is too vague and this seeds of uncertainty grow through the rest of the doc. It is not said how to make non-naive object, how to detect if object of naive or aware. All this stuff is very important for troubleshooting datetims issues in Python projects. It needs a proper documentation. ---------- assignee: docs@python components: Documentation messages: 106524 nosy: docs@python, techtonik priority: normal severity: normal status: open title: datetime naive and aware types should have a well-defined definition that can be cross-referenced _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8822> _______________________________________

6 15

[issue32501] Documentation for dir([object])
by Vladislavs Burakovs Dec. 24, 2020

Dec. 24, 2020

New submission from Vladislavs Burakovs <solomonchild(a)gmail.com>: Documentation page [1] says "If the object has a method named __dir__(), this method will be called and must return the list of attributes.". It seems that on Python 3.6 it only works if the *class* has a method named __dir__. Should the documentation be changed? Microsoft Windows [Version 10.0.16299.192] (c) 2017 Microsoft Corporation. All rights reserved. D:\Users\wlad>python Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:04:45) [MSC v.1900 32 bit (Intel)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> class C: pass ... >>> x = C() >>> import types >>> x.__dir__ = types.MethodType(lambda _:[], x) >>> dir(x) ['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__'] >>> C.__dir__ = types.MethodType(lambda _:[], x) >>> dir(x) [] [1] https://docs.python.org/3/library/functions.html ---------- assignee: docs@python components: Documentation messages: 309544 nosy: Vladislavs Burakovs, docs@python priority: normal severity: normal status: open title: Documentation for dir([object]) type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32501> _______________________________________

5 6

[issue35783] incorrect example of fetching messages in imaplib documentation
by Макс Вернер Dec. 22, 2020

Dec. 22, 2020

New submission from Макс Вернер <mvarnar(a)gmail.com>: An example of fetching messages from the mailbox given in "IMAP4 Example" section is incorrect: typ, data = M.fetch(num, '(RFC822)') print('Message %s\n%s\n' % (num, data[0][1])) "fetch" may return server data that was not requested (see "7.4.2. FETCH Response" section of RFC 3501). In that case "data[0][1]" won't return what user expects. This is a bad example, that many people repeat and advise to other developers: https://stackoverflow.com/questions/13210737/get-only-new-emails-imaplib-an… https://gist.github.com/robulouski/7441883 https://stackoverflow.com/questions/51098962/check-if-email-inbox-is-empty-… https://stackoverflow.com/questions/21116498/imaplib-not-getting-all-emails… https://stackoverflow.com/questions/2230037/how-to-fetch-an-email-body-usin… I guess, this peculiarity should be clarified in the documentation. I offer to mark this fetching method is not safe and requests careful fetch result parsing. ---------- assignee: docs@python components: Documentation, email messages: 334048 nosy: barry, docs@python, r.david.murray, Макс Вернер priority: normal severity: normal status: open title: incorrect example of fetching messages in imaplib documentation type: enhancement versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35783> _______________________________________

2 1

[issue35790] Correct a statement about sys.exc_info() values restoration
by Géry Dec. 21, 2020

Dec. 21, 2020

New submission from Géry <gery.ogam(a)gmail.com>: In the documentation of the try statement (https://docs.python.org/3/reference/compound_stmts.html#the-try-statement), I think that the sentence: "sys.exc_info() values are restored to their previous values (before the call) when returning from a function that handled an exception." should be replaced by this sentence: "sys.exc_info() values are restored to their previous values (before the call) when leaving an exception handler." as proven by this code which does not use any "function that handled an exception" and yet restores sys.exc_info() values: >>> try: ... raise ValueError ... except: ... try: ... raise TypeError ... except: ... print(sys.exc_info()) ... print(sys.exc_info()) ... (<class 'TypeError'>, TypeError(), <traceback object at 0x10ca19bc8>) (<class 'ValueError'>, ValueError(), <traceback object at 0x10ca19c08>) ---------- assignee: docs@python components: Documentation messages: 334092 nosy: docs@python, eric.araujo, ezio.melotti, maggyero, mdk, willingc priority: normal severity: normal status: open title: Correct a statement about sys.exc_info() values restoration versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35790> _______________________________________

2 6

[issue23522] Misleading note in Statistics module documentation
by Jake Dec. 19, 2020

Dec. 19, 2020

New submission from Jake: In the statistics module documentation, there is a note that states that "The mean is strongly affected by outliers and is not a robust estimator for central location: the mean is not necessarily a typical example of the data points. For more robust, although less efficient, measures of central location, see median() and mode()" https://docs.python.org/3/library/statistics.html While I appreciate the intention, this is quite misleading. The implication is that the mean, median and mode are different ways to estimate one "central location", however, in reality they are very different things (albeit which refer to a similar notion). The sample mean is an unbiased estimator of the true mean but it need not be unbiased as an estimator of the true median or modes and vice versa for the median and mode. To make this clearer I would rephrase to "The mean is strongly affected by outliers and is not necessarily representative of the central tendency of the data. For cases with large outliers or very low sample size, see median() and mode()" Apologies if this is seen as frivolous, but statistics can be hard enough to remain very clear about even when the words are used precisely. ---------- assignee: docs@python components: Documentation messages: 236612 nosy: Journeyman08, docs@python priority: normal severity: normal status: open title: Misleading note in Statistics module documentation type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23522> _______________________________________

5 11

[issue14586] TypeError: truncate() takes no keyword arguments
by Guy Taylor Dec. 15, 2020

Dec. 15, 2020

New submission from Guy Taylor <thebigguy.co.uk(a)gmail.com>: The Python docs suggest that io.IOBase.truncate' should take a keyword argument of 'size'. However this causes a 'TypeError': TypeError: truncate() takes no keyword arguments Suggest that the docs are changed to 'truncate(size)' or CPython is changed to allow the keyword. http://docs.python.org/py3k/library/io.html?highlight=truncate#io.IOBase.tr… http://docs.python.org/library/io.html?highlight=truncate#io.IOBase.truncate ---------- assignee: docs@python components: Documentation, Interpreter Core files: test.py messages: 158308 nosy: TheBiggerGuy, docs@python priority: normal severity: normal status: open title: TypeError: truncate() takes no keyword arguments type: behavior versions: Python 2.7, Python 3.2 Added file: http://bugs.python.org/file25219/test.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14586> _______________________________________

6 15

[issue26515] Update extending/embedding docs to new way to build modules in C
by Brett Cannon Dec. 15, 2020

Dec. 15, 2020

New submission from Brett Cannon: https://docs.python.org/3/extending/extending.html#a-simple-example uses PyModule_Create() instead of PyModuleDef_Init(). ---------- assignee: docs@python components: Documentation messages: 261398 nosy: brett.cannon, docs@python, eric.snow, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Update extending/embedding docs to new way to build modules in C versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26515> _______________________________________

5 7

[issue35083] Fix documentation for __instancecheck__
by Joy Diamond Dec. 15, 2020

Dec. 15, 2020

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

[issue26451] CSV documentation doesn't open with an example
by Alex LordThorsen Dec. 13, 2020

Dec. 13, 2020

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 Dec. 8, 2020

Dec. 8, 2020

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