Mailman 3 March 2013 - docs

[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

[issue17231] Mark __del__ not being called in cycles as an impl detail
by Maciej Fijalkowski 06 Mar '20

06 Mar '20

New submission from Maciej Fijalkowski: Here: http://docs.python.org/2/reference/datamodel.html, as per python-dev discussion ---------- assignee: docs@python components: Documentation messages: 182364 nosy: docs@python, fijall priority: normal severity: normal status: open title: Mark __del__ not being called in cycles as an impl detail type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17231> _______________________________________

5 5

[issue8824] Improve documentation of exec
by Terry J. Reedy 28 Feb '20

28 Feb '20

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: This doc improvement suggestion is inspired by #991196 (and subsequent duplicates) and the current discussion on py-dev in the thread 'variable name resolution in exec is incorrect' (which is not a correct claim). I believe there is consensus that the doc for exec needs improving. My suggestion (which others may amend) is that the following paragraph (from the 3.x builtin functions exec entry) "In all cases, if the optional parts are omitted, the code is executed in the current scope. If only globals is provided, it must be a dictionary, which will be used for both the global and the local variables. If globals and locals are given, they are used for the global and local variables, respectively. If provided, locals can be any mapping object." have these two sentences added: "If only globals is provided or if onedict is provided as both globals and locals, the code is executed in a new top-level scope. If different objects are given as globals and locals, the code is executed as if it were in a class statement in a new top-level scope." ---------- assignee: docs@python components: Documentation messages: 106552 nosy: docs@python, tjreedy priority: normal severity: normal status: open title: Improve documentation of exec versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8824> _______________________________________

6 19

[issue15474] Differentiate decorator and decorator factory in docs
by Éric Araujo 26 Feb '20

26 Feb '20

New submission from Éric Araujo <merwok(a)netwok.org>: Some of the confusion encountered when writing decorators arise from the difference between a decorator (@something) and a decorator factory (@something(args)). It would help to adopt this clearer terminology in our docs: a decorator takes the decorated function as argument and does its business, a decorator factory takes some arguments and returns a decorator which wraps the decorated function. (I think it was Nick who suggested this in a recent-ish mailing list thread.) ---------- assignee: docs@python components: Documentation messages: 166600 nosy: docs@python, eric.araujo, ncoghlan priority: normal severity: normal status: open title: Differentiate decorator and decorator factory in docs versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15474> _______________________________________

8 14

[issue9056] Adding additional level of bookmarks and section numbers in python pdf documents.
by pengyu.ut 18 Feb '20

18 Feb '20

New submission from pengyu.ut <pengyu.ut(a)gmail.com>: Current pdf version of python documents don't have bookmarks for sussubsection. For example, there is no bookmark for the following section in python_2.6.5_reference.pdf. Also the bookmarks don't have section numbers in them. I suggest to include the section numbers. Could these features be added in future release of python document. 3.4.1 Basic customization ---------- assignee: docs@python components: Documentation messages: 108334 nosy: docs@python, pengyu.ut priority: normal severity: normal status: open title: Adding additional level of bookmarks and section numbers in python pdf documents. versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9056> _______________________________________

7 9

[issue9305] Don't use east/west of UTC in date/time documentation
by Alexander Belopolsky 14 Feb '20

14 Feb '20

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: I am opening this to supersede issue7229. See discussion following msg107148. In many places offsets representing the difference between local time and UTC are described as minutes or seconds east or west of UTC. This is not correct because UTC is not a place and minutes and seconds don't measure distance in this context. Replacing UTC with the Prime Meridian will not fix that because some regions in the western hemisphere use positive offsets from UTC. or example, Madrid is at 3° 42' West, but uses Central European Time which is UTC+1. I believe geographical references in the python documentation are irrelevant. What users are interested in is how to convert local time to UTC and UTC to local time rather than what is the sign of time.timezone in Madrid. I suggest the following wording for time.timezone description: time.timezone: The number of seconds one must add to the local time to arrive at UTC. Similarly, tzinfo.utcoffset() can be defined as "Returns timedelta one must add to UTC to arrive at local time." ---------- assignee: docs@python components: Documentation keywords: easy messages: 110774 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: Don't use east/west of UTC in date/time documentation type: feature request versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

15 30

[issue13826] Having a shlex example in the subprocess.Popen docs is confusing
by Julian Berman 10 Feb '20

10 Feb '20

New submission from Julian Berman <Julian+Python.org(a)GrayVines.com>: The example at http://docs.python.org/dev/library/subprocess.html#popen-constructor seems a bit misplaced, as it seems to suggest that one should use the shlex module. Most of the other examples in the module seem to use a list to provide the args, so if there was a need to just point out that shlex could be used for a corner case perhaps it'd be better suited as a footnote or another subsection somewhere. ---------- assignee: docs@python components: Documentation messages: 151624 nosy: Julian, docs@python priority: normal severity: normal status: open title: Having a shlex example in the subprocess.Popen docs is confusing type: enhancement versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13826> _______________________________________

9 14

[issue16776] Document PyCFunction_New and PyCFunction_NewEx functions
by Andrew Svetlov 10 Feb '20

10 Feb '20

New submission from Andrew Svetlov: c-api docs has no documentation for those public API functions. ---------- assignee: docs@python components: Documentation keywords: easy messages: 178115 nosy: asvetlov, docs@python priority: normal severity: normal status: open title: Document PyCFunction_New and PyCFunction_NewEx functions type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16776> _______________________________________

7 8

[issue15867] It's hard to decypher how to build off of the provided objects from the importlib docs
by Julian Berman 28 Jan '20

28 Jan '20

New submission from Julian Berman: I find that the importlib documentation is a bit too low level. Import hooks are not that common, so requiring a bit of reading is OK with me, but I somewhat *understand* PEP 302, so I have a general idea of *what* I want to do and what kind of objects can accomplish that, and still find it hard to figure out how to take the pieces provided by importlib and use them to do what I want. If I provide a specific example, I want to create a path hook that "just" does the usual import behavior, but before executing the module, does some transformation on the source code, say. In trying to figure out the best way to do that I had a hard time using the docs to figure out which pieces I should assemble to do that. I'm going to just describe the rough series of steps I went through, and hopefully that will help give a picture of where in the docs I had trouble. `importlib.abc` has a few things that would appear to help. None of the things seem like an exact match, so immediately I'm confused -- after reading PEP 302 I'd have expected to need to find an object to implement one or both of `get_code` or `get_source` on, or one that has that implemented that I can subclass and extend. The closest thing there that I find is PyPycLoader, which seems to be saying it implements the standard import behavior, but the docs say its deprecated and to use SourceLoader. At this point, after checking out `SourceLoader` and seeing that it has me implementing two methods whose purpose I don't quite understand, even after reading the short descriptions of them, at least not in the context of what I want to do, I begin to suspect that what I really want is to combine SourceLoader with some things from the `imp` module, or maybe `importlib.__import__`, but am left wondering again how much I need to implement before I just can use that. I then notice `importlib.util.module_for_loader`, and add that to the simple loader I've written which I'm still waiting to plug `imp` into, before realizing that that decorator eats the `fullname` attribute and *only* passes along the module, which confuses me, since now I don't know how to retrieve the source for the module object that I'm being passed -- so I save the path name in `__init__` for the class, and assume that's what I should be doing, despite not seeing an example doing that. Assuming that's even correct as-is, it took me quite a bit to put those pieces together. So I apologize for rambling -- I think essentially what'd improve things is providing more examples, or perhaps a HOWTO entry, that targeted assembling the pieces provided in the module into a few clear, complete examples of finders, loaders and importers. ---------- assignee: docs@python components: Documentation messages: 169901 nosy: Julian, docs@python priority: normal severity: normal status: open title: It's hard to decypher how to build off of the provided objects from the importlib docs versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15867> _______________________________________

8 11

[issue15243] Misleading documentation for __prepare__
by William Schwartz 25 Jan '20

25 Jan '20

New submission from William Schwartz <wkschwartz(a)gmail.com>: Section 3.3.3.2. "Preparing the class namespace" of the documentation (http://docs.python.org/dev/reference/datamodel.html#preparing-the-class-nam…) states that "If the metaclass has a __prepare__ attribute, it is called as ``namespace = metaclass.__prepare__(name, bases, **kwds)``...." This isn't quite true. By just defining a ``__prepare__`` method in a metaclass, the interpreter calls it as it would a static method -- there is no implicit first argument referring to ``metaclass`` as the documentation implies. The documentation should be amended to say that users can decorate ``__prepare__`` as a class method to get ``metaclass`` passed in as the implicit first argument. ---------- assignee: docs@python components: Documentation, Tests messages: 164606 nosy: William.Schwartz, docs@python priority: normal severity: normal status: open title: Misleading documentation for __prepare__ type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________

11 22