Mailman 3 October 2020 - docs

[issue42179] Clarify chaining exceptions in tutorial/errors.rst
by Vladimir Ryabtsev 06 Jan '21

06 Jan '21

New submission from Vladimir Ryabtsev <greatvovan(a)gmail.com>: A new section has been added to the page as a result of https://bugs.python.org/issue37826. The change: https://github.com/python/cpython/commit/dcfe111eb5602333135b8776996332a8dc… The wording it uses (in the beginning of section 8.5), defines chaining as setting __cause__ attribute in an exception, and later states that "Exception chaining happens automatically when an exception is raised inside an exception handler or finally section". This may lead the reader to a wrong idea that re-raising an exception without "from" in "except" and "finally" automatically sets __cause__. In reality it sets only __context__ attribute, which is similar concept to __cause__, but work a bit differently, as explained in library/exceptions.rst. I suggest to mention that difference and provide a link to the main article. ---------- assignee: docs@python components: Documentation messages: 379823 nosy: Vladimir Ryabtsev, docs@python priority: normal severity: normal status: open title: Clarify chaining exceptions in tutorial/errors.rst versions: Python 3.10, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42179> _______________________________________

7 19

[issue38413] Remove or change "Multithreading" section
by Vladimir Ryabtsev 06 Jan '21

06 Jan '21

New submission from Vladimir Ryabtsev <greatvovan(a)gmail.com>: This is regarding the page https://docs.python.org/3.7/library/sqlite3.html. I believe this section on the very bottom of the page has been kept here for pretty long time, during that both SQLite and the sqlite3 module evolved and improved. Now the content contradicts to the description of function "connect()" in the part describing "check_same_thread" parameter. The function description says that using connections from multiple threads is allowed with serialization handled by the user (and it is true), while the bottom "Mutithreading" section says sharing connections is not allowed. I think we can remove "Mutithreading" section entirely unless there is something important to add to what already mentioned. ---------- assignee: docs@python components: Documentation messages: 354227 nosy: Vladimir Ryabtsev, docs@python priority: normal severity: normal status: open title: Remove or change "Multithreading" section versions: Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38413> _______________________________________

6 15

[issue34451] docs: tutorial/introduction doesn't mention toggle of prompts
by Jonathan Fine 06 Jan '21

06 Jan '21

New submission from Jonathan Fine <jfine2358(a)gmail.com>: Interactive code examples need the prompt to be stripped, before copy-and-paste. This is explained in https://docs.python.org/3/tutorial/introduction.html But this page does not tell us about the [>>>] prompt-toggle at top of each interactive code example. This caused a user error, reported in https://mail.python.org/pipermail/python-ideas/2018-August/052869.html. The [>>>] toggle isn't in the Python 2.7 docs, so nothing to fix there! ---------- assignee: docs@python components: Documentation messages: 323839 nosy: docs@python, jfine2358 priority: normal severity: normal status: open title: docs: tutorial/introduction doesn't mention toggle of prompts versions: 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/issue34451> _______________________________________

5 6

[issue41224] Document is_annotated() in the symtable module
by Joannah Nanjekye 31 Dec '20

31 Dec '20

New submission from Joannah Nanjekye <nanjekyejoannah(a)gmail.com>: The function is_annotated() in symtable is not documented. Am using this opportunity to also add docstrings to the methods that didnot have them already. ---------- assignee: docs@python components: Documentation messages: 373200 nosy: docs@python, nanjekyejoannah priority: normal severity: normal status: open title: Document is_annotated() in the symtable module type: enhancement versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41224> _______________________________________

3 12

[issue8595] Unexpected default timeout in http-client-related libraries
by Julian 29 Dec '20

29 Dec '20

New submission from Julian <python_org(a)somethinkodd.com>: Since Python 2.6, httplib has offered a timeout parameter for fetches. As the documentation explains, if this parameter is not provided, it uses the global default. What the document doesn't explain is httplib builds on top of the socket library. The socket library has a default timeout of None (i.e. forever). This may be an appropriate default for general sockets, but it is a poor default for httplib; typical http clients would use a timeout in the 2-10 second range. This problem is propagated up to urllib2, which sits on httplib, and further obscures that the default might be unsuitable. >From an inspection of the manuals, Python 3.0.1 suffers from the same problem except, the names have changed. urllib.response sits on http.client. I, for one, made a brutal mistake of assuming that the "global default" would be some reasonable default for fetching web pages; I didn't have any specific timeout in mind, and was happy for the library to take care of it. Several million successful http downloads later, my server application thread froze waiting forever when talking to a recalcitrant web-server. I imagine others have fallen for the same trap. While an ideal solution would be for httplib and http.client to use a more generally acceptable default, I can see it might be far too late to make such a change without breaking existing applications. Failing that, I would recommend that the documentation for httplib, urllib, urllib2, http.client and urllib.request (+ any other similar libraries sitting on socket? FTP, SMTP?) be changed to highlight that the default global timeout, sans deliberate override, is to wait a surprisingly long time. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 104763 nosy: docs@python, oddthinking priority: normal severity: normal status: open title: Unexpected default timeout in http-client-related libraries type: behavior versions: Python 2.6, Python 2.7, Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8595> _______________________________________

5 8

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

29 Dec '20

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

[issue41450] OSError is not documented in ssl library, but still can be thrown
by Alexander Sibiryakov 27 Dec '20

27 Dec '20

New submission from Alexander Sibiryakov <sixty-one(a)yandex.ru>: See stack trace [07/15/2020 08:51:14.799: ERROR/kafka.producer.sender] Uncaught error in kafka producer I/O thread Traceback (most recent call last): File "/usr/local/lib/python3.6/site-packages/kafka/producer/sender.py", line 60, in run self.run_once() File "/usr/local/lib/python3.6/site-packages/kafka/producer/sender.py", line 160, in run_once self._client.poll(timeout_ms=poll_timeout_ms) File "/usr/local/lib/python3.6/site-packages/kafka/client_async.py", line 580, in poll self._maybe_connect(node_id) File "/usr/local/lib/python3.6/site-packages/kafka/client_async.py", line 390, in _maybe_connect conn.connect() File "/usr/local/lib/python3.6/site-packages/kafka/conn.py", line 426, in connect if self._try_handshake(): File "/usr/local/lib/python3.6/site-packages/kafka/conn.py", line 505, in _try_handshake self._sock.do_handshake() File "/usr/local/lib/python3.6/ssl.py", line 1077, in do_handshake self._sslobj.do_handshake() File "/usr/local/lib/python3.6/ssl.py", line 689, in do_handshake self._sslobj.do_handshake() OSError: [Errno 0] Error See docs https://docs.python.org/3.8/library/ssl.html and see source code: https://github.com/python/cpython/blob/3.8/Modules/_ssl.c Probably the best would be to proceed with using SSLError, but short term OSError could be documented. ---------- assignee: docs@python components: Documentation messages: 374644 nosy: docs@python, sibiryakov priority: normal severity: normal status: open title: OSError is not documented in ssl library, but still can be thrown type: behavior versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41450> _______________________________________

6 7

[issue42042] docs.python.org for 3.10 missing the new refererence record.
by Dong-hee Na 26 Dec '20

26 Dec '20

New submission from Dong-hee Na <donghee.na92(a)gmail.com>: For example https://docs.python.org/3.10/c-api/bool.html?highlight=pydict_new#c.PyDict_… should display `Return value: New reference.` but not, this looks like a regression bug. other version display `Return value: New reference.` very well. ---------- assignee: docs@python components: Documentation messages: 378677 nosy: corona10, docs@python, vstinner priority: normal severity: normal status: open title: docs.python.org for 3.10 missing the new refererence record. versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42042> _______________________________________

8 25

[issue38649] tkinter messagebox is sloppy
by David Lambert 25 Dec '20

25 Dec '20

New submission from David Lambert <b49p23tivg(a)gmail.com>: Does aksokcancel return "true" or True ? The docstring should say True This is pervasive throughout the module. tkinter has such a mishmash of numbers supplied as strings, strings supplied as constants making this carelessness egregious. On the topic of constants, the messagebox module redefines OK. You might argue that the definition didn't change. I suspect this issue applies to all versions of tkinter or Tkinter having the messagebox. # types ABORTRETRYIGNORE = "abortretryignore" OK = "ok" ... # replies ... OK = "ok" def askokcancel(title=None, message=None, **options): "Ask if operation should proceed; return true if the answer is ok" s = _show(title, message, QUESTION, OKCANCEL, **options) return s == OK ---------- assignee: docs@python components: Documentation messages: 355729 nosy: David Lambert, docs@python priority: normal severity: normal status: open title: tkinter messagebox is sloppy type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38649> _______________________________________

3 4

[issue41644] builtin type kwargs
by Joseph Perez 24 Dec '20

24 Dec '20

New submission from Joseph Perez <joperez(a)hotmail.fr>: Class definition can have kwargs which are used by `__init_subclass__` (and `__prepare__`). However, passing these kwargs using `type` builtin function instead of class definition syntax is not documented; kwargs are not mentioned in the function signature. https://docs.python.org/3/library/functions.html#type However, passing kwargs to `type` works: ```python class Foo: def __init_subclass__(cls, **kwargs): print(kwargs) Bar = type("Bar", (Foo,), {}, bar=None) # mypy and Pycharm complain #> {'bar': None} ``` By the way, the possibility to pass kwargs in `type` call is not documented in https://docs.python.org/3/reference/datamodel.html#customizing-class-creati… too. ---------- assignee: docs@python components: Documentation messages: 375936 nosy: docs@python, joperez priority: normal severity: normal status: open title: builtin type kwargs versions: Python 3.10, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41644> _______________________________________

3 3