Mailman 3 November 2019 - docs

[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

[issue38423] Event loop implementation docs advertise set_event_loop
by Hrvoje Nikšić 27 Jan '20

27 Jan '20

New submission from Hrvoje Nikšić <hniksic(a)gmail.com>: The docs of SelectorEventLoop and ProactorEventLoop contain examples that call asyncio.set_event_loop: selector = selectors.SelectSelector() loop = asyncio.SelectorEventLoop(selector) asyncio.set_event_loop(loop) But this won't have any effect on code that uses asyncio.run(), because asyncio.run() creates a fresh event loop. Since asyncio.run() is the recommended way to execute async code and is used consistently throughout the documentation, this might be confusing to someone who tries to e.g. use the proactor loop on Windows. I propose the following: * add a disclaimer that instantiating the event loop won't affect calls to asyncio.run(), and that loop.run_until_complete() must be used; and * link to asyncio.set_event_loop_policy(), which does work with asyncio.run(), but doesn't allow fine-tuning the details, such as which selector to use for the SelectorEventLoop. ---------- assignee: docs@python components: Documentation, asyncio messages: 354288 nosy: asvetlov, docs@python, hniksic, yselivanov priority: normal severity: normal status: open title: Event loop implementation docs advertise set_event_loop versions: Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38423> _______________________________________

3 4

[issue36654] Add example to tokenize.tokenize
by Windson Yang 25 Jan '20

25 Jan '20

New submission from Windson Yang <wiwindson(a)outlook.com>: > The tokenize() generator requires one argument, readline, which must be a callable object which provides the same interface as the io.IOBase.readline() method of file objects. Each call to the function should return one line of input as bytes. Add an example like this should be easier to understand: # example.py def foo: pass # tokenize_example.py import tokenize f = open('example.py', 'rb') token_gen = tokenize.tokenize(f.readline) for token in token_gen: # Something like this # TokenInfo(type=1 (NAME), string='class', start=(1, 0), end=(1, 5), line='class Foo:\n') # TokenInfo(type=1 (NAME), string='Foo', start=(1, 6), end=(1, 9), line='class Foo:\n') # TokenInfo(type=53 (OP), string=':', start=(1, 9), end=(1, 10), line='class Foo:\n') print(token) ---------- assignee: docs@python components: Documentation messages: 340467 nosy: Windson Yang, docs@python priority: normal severity: normal status: open title: Add example to tokenize.tokenize type: enhancement versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36654> _______________________________________

5 10

[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

[issue37955] mock.patch incorrect reference to Mock
by Paulo Henrique Silva 25 Jan '20

25 Jan '20

New submission from Paulo Henrique Silva <ph.silva(a)gmail.com>: When explaining the usage of keyword arguments on mock.patch: ``` patch() takes arbitrary keyword arguments. These will be passed to the Mock (or new_callable) on construction. ``` default new_callable is MagicMock and it should be mentioned here instead of Mock (even tough MagickMock inherits from it). ---------- assignee: docs@python components: Documentation messages: 350537 nosy: docs@python, phsilva priority: normal severity: normal status: open title: mock.patch incorrect reference to Mock versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37955> _______________________________________

2 3

[issue11553] Docs for: import, packages, site.py, .pth files
by Graham Wideman 24 Jan '20

24 Jan '20

New submission from Graham Wideman <initcontact(a)grahamwideman.com>: The overall scope of this issue is that current Python documentation gives vague, sometimes incorrect, information about the set of Python features involved in modularizing functionality. This issue presents an obstacle to programmers making smooth transitions from a single module, to collections of modules and packages, then on to neatly organized common packages shared between projects. The problem affects documentation of: import and from...import statements ------------------------------------ The Language Reference is way too complicated for the mainstream case. Exactly what variants of arguments are possible, and what are their effects? What are the interactions with package features, such as whether or not modules have been explicitly imported into package __init_.py? sys.path --------- Typical consituents; range of alternatives for adding more dirs Module site.py -------------- Multiple serious errors in the file docstring, relating to site-packages directories and .pth files .pth files ----------- Incorrectly described in site.py, and then vaguely described in other docs. Are .pth files processed everywhere on sys.path? Can they be interative? (No to both). package structure ----------------- Details of package structure have evidently changed over Python versions. Current docs are unclear on points such as: -- is __init__.py needed on subpackage directories? -- the __all__ variable: Does it act generally to limit visibility of a module or package's attributes, or does pertain only to the 'from...import *' statement? Details: ========= Language Reference ------------------- http://docs.python.org/py3k/reference/simple_stmts.html#the-import-statement The description of the import statement is extensive, but dauntingly complicated for the reader trying to understand the mainstream case of simply importing modules or packages that are on sys.path. This is because the algorithm for finding modules tries numerous esoteric strategies before falling back on the plain-old-file-system method. (Even now that I have a good understanding of the plain-old-file variations of import, I reread this and find it hard to comprehend, and disorganized and incomplete in presenting the available variations of the statement.) Grammar issue: the grammar shown for the import statement shows: relative_module ::= "."* module | "."+ ... which implies that relative module could have zero leading dots. I believe an actual relative path is required to have at least one dot (PEP 328). Evidently, in this grammar, 'relative_module' really means "relative or absolute path to module or package", so it would be quite helpful to change to: relative_path ::= "."+ module | "."+ from_path ::= (relative_path | module) etc. (Really 'module' is not quite right here either since it's used to mean module-or-package.) site.py: -------- Module site.py implements the site-package related features. The docstring has multiple problems with consequences in other docs. 1. Does not mention user-specific site-package directories (implemented by addusersitepackages() ) 2. Seriously misleading discussion of .pth files. In the docstring the example shows using pth files, called "package configuration files" in their comments, to point to actual package directories bar and foo located within the site-packages directory. This is an absolutely incorrect use of pth files: If foo and bar are packages in .../site-packages/, they do not need to be pointed to, they are already on sys.path. If the package dirs ARE pointed to by foo.pth and bar.pth, the modules inside them will be exposed directly to sys.path, possibly precipitating name collisions. Further, programmers following this example will create packages in which import statements will appear to magically perform relative imports without leading dots, leading to confusion over how the import statement is supposed to work. It may be that this discussion is held over from a time when "package" perhaps meant "Just a Bunch of Files in a Directory"? 3. The docstring (or other docs) should make clear that .pth files are ONLY processed within site-package directories (ie: only by site.py). 4. Bug: Minor: In addsitepackages(), the library directory for Windows (the else clause) is shown as lower-case 'lib' instead of 'Lib'. This has some possibility of causing problems when running from a case-sensitive server. In any case, if read as documentation it is misleading. Tutorial --------- 6. Modules: http://docs.python.org/py3k/tutorial/modules.html 1. Discussion (6.1.2. The Module Search Path) is good as far as it goes, but it doesn't mention the site-package directories. 2. Section 6.4. Packages: Discussion of __init__.py does describe the purpose of these files. However, the discussion in relation to subpackages should mention that for subdirectories to be accessible they must in fact be made into subpackages. I.e.: there is not form of import that can reach into a subdir of a package *unless* it's flagged as a subpackage using __init__.py. I have read elsewhere that there were some versions of Python where __init__.py was not needed on subdirs within a package. 3. Section 6.4. Packages: The discussion of __all__ should note that it works *only* in conjunction with 'from...import *', and is not a general mechanism for limiting visibility of attributes. Attributes not in the __all__ list are still accessible using other forms of import. 4. Section 6.4. Packages: "Note that when using from package import item" and following. Draws a contrast between: from package import item vs import item.subitem.subsubitem However, this muddles the roles of the arguments to import, and notably uses 'item' in two different ways. Instead the discussion can be presented as a comparison of: from PackageOrModule import ModuleOrAttribute vs import PackageOrModule ... where it can be pointed out that the PackageOrModule 'dotted path' argument follows the *same* rules in both cases (except for relative paths). The *salient* contrast is that only the 'from' form has a *second* argument which can be an attribute. 5. Footnote: (somewhat unrelated, but...) says "the execution of a module-level function enters the function name in the module’s global symbol table." This is surely incorrect -- it is the execution of the function's *def* that enters the function name in the symbol table. Standard Library Reference --------------------------- 1) 27.13. site — Site-specific configuration hook http://docs.python.org/py3k/library/site.html This is documentation for site.py, and is a page that might well come up in a search for '.pth'. 1a) This page may simply be importing the docstring from site.py? In any case it repeats the ommissions and errors noted above for site.py. 2) 27.1. sys — System-specific parameters and functions http://docs.python.org/py3k/library/sys.html Documentation for sys.path. OK as far as it goes, but: 2a) Could helpfully point to a discussion of the typical items to be found in sys.path under normal circumstances 2b) It does point to the site.py module documentation as the authoritative info on using .pth files (which is seriously flawed as noted above). 3) 29.3. pkgutil — Package extension utility. http://docs.python.org/py3k/library/pkgutil.html 3a) The info for pkgutil.extend_path() describes how .pkg files are similar to .pth files, and their entries should point to package directories. As I noted above, so far as I can see, package directories should be within a directory on sys,path, but should not themselves be included in the path, otherwise it breaks their capability to work properly as packages. 'Installing Python Modules' document: -------------------------------------- http://docs.python.org/py3k/install/index.html This may well be consulted for info on how to organize source files, though it is basically the doc for Distutils. 1. Main problem is that it seems quite out-of-date; "Windows has no concept of a user’s home directory, " and so on. 2. 'How installation works' > table. For Windows suggests 'prefix' (default: C:\Python) as an installation directory. This is indeed one of the possible 'site-package' directories, but surely it is deprecated in favor of C:\Python\Lib\site-packages, which this section does not mention. 3. Does not mention user-specific site-package directories. 4. 'Modifying Python's Search Path' > "The most convenient way is to add a path configuration file to a directory that’s already on Python’s path". This is incorrect. (a) .pth files are only processed in site-package directories. (b) Clarifying an additional point of confusion -- as a consequence of (a) .pth files cannot be chained. 5. Points to docs for site.py... with it's flaws noted above. PEP 302 New Import Hooks ------------------------ Given the vagueness elsewhere in the docs, one might go hunting for ground truth in the PEPs. One must allow for PEPs having been superceeded, but nonetheless, outdated info that is now wrong is an additional stumbling block for learners. 1. Section 'Specification part 1: The importer Protocol'. Discussion says that in an import statement, a path (with no leading '.') is first treated as relative. This is now incorrect (as spelled out in PEP 328.) It would be helpful to insert a note in PEP 302 pointing out that the later revision invalidates this passage. ---------- assignee: docs@python components: Documentation messages: 130964 nosy: docs@python, gwideman priority: normal severity: normal status: open title: Docs for: import, packages, site.py, .pth files type: behavior versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11553> _______________________________________

6 14

[issue36892] "Modules" section in Tutorial contains incorrect description about __init__.py
by musou1500 20 Jan '20

20 Jan '20

New submission from musou1500 <musou1500(a)gmail.com>: "Modules" section in the tutorial says that https://docs.python.org/3/tutorial/modules.html "The __init__.py files are required to make Python treat directories containing the file as packages. " But, thanks to PEP 420, __init__.py is not required after Python 3.3. https://www.python.org/dev/peps/pep-0420/ ---------- assignee: docs@python components: Documentation messages: 342228 nosy: docs@python, musou1500 priority: normal severity: normal status: open title: "Modules" section in Tutorial contains incorrect description about __init__.py type: enhancement versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36892> _______________________________________

4 3

[issue36417] unicode.isdecimal bug in online Python 2 documentation
by PEW's Corner 19 Jan '20

19 Jan '20

New submission from PEW's Corner <pewscorner(a)gmail.com>: The online Python 2 documentation for unicode.isdecimal (https://docs.python.org/2/library/stdtypes.html#unicode.isdecimal) incorrectly states: "Decimal characters include digit characters". This is wrong (decimal characters are actually a subset of digit characters), and u'\u00b3' is an example of a character that is a digit but not a decimal. Issue 26483 (https://bugs.python.org/issue26483) corrected the same bug in the Python 3 documentation, and a similar correction should be applied to the Python 2 documentation. ---------- assignee: docs@python components: Documentation messages: 338736 nosy: docs@python, pewscorner priority: normal severity: normal status: open title: unicode.isdecimal bug in online Python 2 documentation type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36417> _______________________________________

4 4

[issue19557] ast - docs for every node type are missing
by anatoly techtonik 12 Jan '20

12 Jan '20

New submission from anatoly techtonik: http://docs.python.org/2/library/ast.html AST module doc is incomplete. To write node visitor, you need to know possible types of parameters and expected values for every node type. They are different. http://hg.python.org/cpython/file/1ee45eb6aab9/Parser/Python.asdl For example, visit_Assign expects: Assign(targets, value) `targets` can be List, Tuple or Name When there is List, and when there is Tuple? It should be documented. ---------- assignee: docs@python components: Devguide, Documentation messages: 202675 nosy: docs@python, ezio.melotti, techtonik priority: normal severity: normal status: open title: ast - docs for every node type are missing _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19557> _______________________________________

6 11

[issue23139] syntax diagram after EBNF description?
by Friedrich Spee von Langenfeld 11 Jan '20

11 Jan '20

New submission from Friedrich Spee von Langenfeld: In our full grammar specification (10th chapter of the language reference, https://docs.python.org/3/reference/grammar.html), the grammar of Python is comprehensively notated. What would you think of adding a picture with an equivalent syntax diagram (e. g. produced with the help of http://www.bottlecaps.de/rr/ui) to open a new way of understanding for readers? ---------- assignee: docs@python components: Documentation messages: 233236 nosy: Friedrich.Spee.von.Langenfeld, docs@python priority: normal severity: normal status: open title: syntax diagram after EBNF description? _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23139> _______________________________________

2 1