Mailman 3 September 2018 - docs

[issue13743] xml.dom.minidom.Document class is not documented
by Sandro Tosi 12 Apr '20

12 Apr '20

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: Hello, following up http://mail.python.org/pipermail/docs/2012-January/007026.html I noticed the whole Document class (and relative methods) is not documented. Maybe it is a choice to not document it, or maybe it's just a missing doc, dunno, the's why I'm opening this :) ---------- assignee: docs@python components: Documentation messages: 150935 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: needs patch status: open title: xml.dom.minidom.Document class is not documented versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13743> _______________________________________

6 9

[issue21760] inspect documentation describes module type inaccurately
by Eric Snow 11 Apr '20

11 Apr '20

New submission from Eric Snow: In the documentation for the inspect module, the module type is described with just 2 of its potential 7 attributes. The language reference[2] and importlib docs[3] both provide an accurate list of module attributes. Furthermore, the description for __file__ should be fixed. It should be clear that __file__ reflects the location from which the module was loaded, that location is not necessarily a filename, and the attribute may not exist if the module was not loaded from a specific location (e.g. builtin and frozen modules). The same goes for __cached__ [1] https://docs.python.org/dev/library/inspect.html#types-and-members [2] https://docs.python.org/3/reference/import.html#import-related-module-attri… [3] https://docs.python.org/3/library/importlib.html#importlib.machinery.Module… ---------- assignee: docs@python components: Documentation messages: 220576 nosy: docs@python, eric.snow priority: normal severity: normal stage: needs patch status: open title: inspect documentation describes module type inaccurately versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21760> _______________________________________

4 5

[issue32377] Difference in ressurrection behavior with __del__ in py2 vs. py3
by Eric Cousineau 09 Apr '20

09 Apr '20

New submission from Eric Cousineau <eric.cousineau(a)tri.global>: Due to how `PyObject_CallFinalizer` is written in python3, `__del__` will only *ever* be called once. In my use case, I am experimenting with a feature in `pybind11` to prevent slicing with Python class instances that inherit from pybind11-C++ base classes, which involves detecting when an instance loses all reference in Python (`Py_REFCNT(...) == 0`) but still has reference in C++ (`shared_ptr::count() > 0`), and reviving the Python portion when this situation happens. In python2, I could do this without a hitch, as a resurrected object could have its `__del__` method called multiple times (through `tp_dealloc` I believe?). But in python3, the object is marked with `_PyGC_SET_FINALIZED(...)`, thus preventing `__del__` from being called again. It'd be nice to either (a) somehow allow `__del__` to be called naturally without too much fuss or, at the least, (b) have this reflected in the documentation: https://docs.python.org/3/reference/datamodel.html#object.__del__ See attached `revive_test`. Example execution: ``` $ python2 ./revive_test.py Revive Destroy [ Done ] $ python3 ./revive_test.py Revive [ Done ] ``` ---------- assignee: docs@python components: Documentation files: revive_test.py messages: 308660 nosy: Eric Cousineau, docs@python priority: normal severity: normal status: open title: Difference in ressurrection behavior with __del__ in py2 vs. py3 type: behavior versions: Python 3.4, Python 3.5, Python 3.6 Added file: https://bugs.python.org/file47339/revive_test.py _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32377> _______________________________________

3 11

[issue15140] PEP 384 inconsistent with implementation
by Antoine Pitrou 01 Apr '20

01 Apr '20

New submission from Antoine Pitrou <pitrou(a)free.fr>: In PEP 384, the PyType_Spec struct has a "const char *doc" that is not present in the implementation (Include/object.h). ---------- assignee: docs@python components: Documentation messages: 163449 nosy: docs@python, loewis, pitrou priority: normal severity: normal stage: needs patch status: open title: PEP 384 inconsistent with implementation type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15140> _______________________________________

4 3

[issue15436] __sizeof__ is not documeneted
by Serhiy Storchaka 22 Mar '20

22 Mar '20

New submission from Serhiy Storchaka <storchaka(a)gmail.com>: __sizeof__ is not mentioned on page Doc/reference/datamodel.rst together with other special methods. There is no __sizeof__ in index. ---------- assignee: docs@python components: Documentation messages: 166245 nosy: docs@python, storchaka priority: normal severity: normal status: open title: __sizeof__ is not documeneted versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15436> _______________________________________

14 24

[issue21108] Add doc examples for importlib
by Saimadhav Heblikar 18 Mar '20

18 Mar '20

New submission from Saimadhav Heblikar: The imp module was the defacto module to access the import internals,upto 3.3 It has been deprecated(pending) in 3.4 in favor of importlib. There are plenty of examples on how to use imp around the web, but very little (even in doc.python.org), on how to use importlib. The proposed patch adds couple of examples. These examples are aimed towards people, who were earlier using imp's load_module(). Inspiration for the patch from this SO answer, where user had to go through source code. http://stackoverflow.com/questions/19009932/import-abitrary-python-source-f… ---------- assignee: docs@python components: Documentation files: importlib-example.patch keywords: patch messages: 215220 nosy: docs@python, sahutd priority: normal severity: normal status: open title: Add doc examples for importlib versions: Python 3.4 Added file: http://bugs.python.org/file34675/importlib-example.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21108> _______________________________________

5 6

[issue22014] Add summary table for OS exception <-> errno mapping
by Nick Coghlan 18 Mar '20

18 Mar '20

New submission from Nick Coghlan: It would be handy if the main OS exception docs at https://docs.python.org/3/library/exceptions.html#os-exceptions included a summary table mapping between exception types and errno names, akin to the one in the original PEP (http://www.python.org/dev/peps/pep-3151/#new-exception-classes) ---------- assignee: docs@python components: Documentation keywords: easy messages: 223499 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Add summary table for OS exception <-> errno mapping versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22014> _______________________________________

5 10

[issue20039] Missing documentation for argparse.ArgumentTypeError
by Arnaut Billings 11 Mar '20

11 Mar '20

New submission from Arnaut Billings: There is no documentation for argparse.ArgumentTypeError: http://docs.python.org/3/library/unittest.html Though it does appear in an example and its usage is simple enough to decipher what it means, it would none the less look more professional if there was formal documentation for it. Not only on what it is, but when it should actually be used, etc... ---------- assignee: docs@python components: Documentation messages: 206723 nosy: arnaut-billings, docs@python priority: normal severity: normal status: open title: Missing documentation for argparse.ArgumentTypeError versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20039> _______________________________________

5 6

[issue17422] language reference should specify restrictions on class namespace
by Eric Snow 10 Mar '20

10 Mar '20

New submission from Eric Snow: (related to PEP 422 and issue #17044) The execution namespace from a class definition is passed as the third argument to the metaclass (see builtin___build_class__() in Python/bltinmodule.c). When applicable, which is almost always, the subsequent call to type.__new__() copies that namespace into a new dict which is in turn exposed via the class's __dict__. This matters in the case where a metaclass with __prepare__() gets used (or the PEP 422 equivalent). The language reference[1] should note that the object returned by __prepare__() is copied into a new dict when the class is finally created via the metaclass. [1] http://docs.python.org/3.4/reference/datamodel.html#customizing-class-creat… ---------- assignee: docs@python components: Documentation messages: 184188 nosy: docs@python, eric.snow, ncoghlan priority: normal severity: normal stage: needs patch status: open title: language reference should specify restrictions on class namespace type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17422> _______________________________________

8 25

[issue13077] Unclear behavior of daemon threads on main thread exit
by etuardu 09 Mar '20

09 Mar '20

New submission from etuardu <edonan(a)gmail.com>: The definition of daemon thread in the current documentation reads: «A thread can be flagged as a "daemon thread". The significance of this flag is that the entire Python program exits when only daemon threads are left. [...]» (http://docs.python.org/library/threading.html#thread-objects) I think it's not very clear from this that daemon threads themselves terminate when the program (main thread plus other non-daemon threads) terminates. I think this have to be said more explicitly. I'd propose a change with something like: «A thread can be flagged as a "daemon thread", which means it will get shut down when the overall program terminates. The entire Python program exits when only daemon threads are left.» ---------- assignee: docs@python components: Documentation messages: 144691 nosy: docs@python, etuardu priority: normal severity: normal status: open title: Unclear behavior of daemon threads on main thread exit 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/issue13077> _______________________________________

5 7