Mailman 3 December 2012 - docs

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

Jan. 24, 2020

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

[issue15718] Possible OverflowError in __len__ method undocumented (when called via len() function)
by Rostyslav Dzinko Jan. 10, 2020

Jan. 10, 2020

New submission from Rostyslav Dzinko: I've encountered that OverflowError which can happen in __len__ method is still undocumented, though one issue on this problem: http://bugs.python.org/issue12159 ended up with "need to be documented" comment. Link to documentation: http://docs.python.org/reference/datamodel.html#object.__len__ I think it must be clarified that __len__ return value is constrained to upper boundary (Py_ssize_t c type) when you plan to call it via len() built-in function. ---------- assignee: docs@python components: Documentation messages: 168439 nosy: Rostyslav.Dzinko, docs@python priority: normal severity: normal status: open title: Possible OverflowError in __len__ method undocumented (when called via len() function) versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15718> _______________________________________

7 18

[issue13562] Notes about module load path
by Nam Nguyen Oct. 22, 2019

Oct. 22, 2019

New submission from Nam Nguyen <bitsink(a)gmail.com>: A doc patch to remind Python embedder to set sys.path prior to Py_Initialize. This is to ensure a controlled module load path to work around these issues: http://bugs.python.org/issue12989 http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983 ---------- assignee: docs@python components: Documentation files: module.load.path.diff keywords: patch messages: 149071 nosy: Nam.Nguyen, docs@python priority: normal severity: normal status: open title: Notes about module load path type: feature request versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file23888/module.load.path.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13562> _______________________________________

4 6

[issue13474] Mention of "-m" Flag Missing From Doc on Execution Model
by Eric Snow Sept. 12, 2019

Sept. 12, 2019

New submission from Eric Snow <ericsnowcurrently(a)gmail.com>: The doc on code execution[1] leaves out mention of the -m flag. Seems like it belongs there too. [1] Doc/reference/executionmodel.rst ---------- assignee: docs@python components: Documentation messages: 148288 nosy: docs@python, eric.snow priority: normal severity: normal status: open title: Mention of "-m" Flag Missing From Doc on Execution Model versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13474> _______________________________________

8 10

[issue9938] Documentation for argparse interactive use
by Jay T Sept. 12, 2019

Sept. 12, 2019

New submission from Jay T <jaytula(a)gmail.com>: I want to create a custom interactive shell where I continually do parse_args. Like the following: parser = argparse.ArgumentParser() command = raw_input() while(True): args = parser.parse_args(shlex.split(command)) # Do some magic stuff command = raw_input() The problem is that if I give it invalid input, it errors and exits with a help message. I learned from argparse-users group that you can override the exit method like the following: class MyParser(ArgumentParser): def exit(self, status=0, message=None): # do whatever you want here I would be nice to have this usage documented perhaps along with best practices for doing help messages in this scenario. ---------- assignee: docs@python components: Documentation messages: 117287 nosy: docs@python, jayt priority: normal severity: normal status: open title: Documentation for argparse interactive use type: feature request versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9938> _______________________________________

16 28

[issue16438] Numeric operator predecence confusing
by Yongzhi Pan Sept. 11, 2019

Sept. 11, 2019

New submission from Yongzhi Pan: http://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-comp… "All numeric types (except complex) support the following operations, sorted by ascending priority." It list '-' after '+', '/' after '*'. That is to mean '-' has higher precedence than '+'. That is wrong, and is contradicting with here: http://docs.python.org/3/reference/expressions.html#summary This should be made clear. ---------- assignee: docs@python components: Documentation messages: 175163 nosy: docs@python, fossilet priority: normal severity: normal status: open title: Numeric operator predecence confusing versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16438> _______________________________________

13 23

[issue12077] Harmonizing descriptor protocol documentation
by Davide Rizzo Aug. 29, 2019

Aug. 29, 2019

New submission from Davide Rizzo <sorcio(a)gmail.com>: There are three sources of information for the descriptor protocol: - Data model reference (Doc/reference/datamodel.rst) - Descriptor HowTo guide (Doc/howto/descriptor.rst) - PEP 252 A developer who already knows descriptor tipically reads the first one: object.__get__(self, instance, owner) "... owner is always the owner class ..." Reading a bit further there are the ways a descriptor can be called, and the "direct call" is x.__get__(a). That is, without the third argument (owner) specified. The how-to definition is slightly different: descr.__get__(self, obj, type=None) --> value Here the arguments have different names ("type" shadowing the type bultin) and it seems to be implied that the third argument is optional. The ClassMethod example at the end of the document seems to confirm this: def __get__(self, obj, klass=None): (though another example doesn't). And the method contains an explicit check on klass being None. Also it could be confusing that through the examples in the same document many different names are used for the same argument (type, objtype, klass), and all different than the name used in the reference. Lastly the PEP is more explicit: __get__(): a function callable with one or two arguments. [...] When X is None, the optional second argument, T, should be meta-object. [...] When both X and T are specified ... One more quirk: the reference explains the distinction between data and non-data descriptors, though says nothing about __set__ raising AttributeError for read-only data descriptors. My proposal: - use the same names for __get__ arguments throughout the documentation (both the reference and the tutorial), e.g. __get__(self, instance, owner) - decide whether the third argument should be optional, or state the common usage in the reference, and fix accordingly the examples in the howto - explain data, non-data and read-only descriptors in the __set__ reference, or more simply, how the defintion of __set__ affects these things. ---------- assignee: docs@python components: Documentation messages: 135974 nosy: davide.rizzo, docs@python priority: normal severity: normal status: open title: Harmonizing descriptor protocol documentation versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________

9 17

[issue15542] Documentation incorrectly suggests __init__ called after direct __new__ call
by Aaron Staley Aug. 26, 2019

Aug. 26, 2019

New submission from Aaron Staley: The documentation for __new__ at http://docs.python.org/reference/datamodel.html#object.__new__ is: """ object.__new__(cls[, ...]) Called to create a new instance of class cls. __new__() is a static method (special-cased so you need not declare it as such) that takes the class of which an instance was requested as its first argument. The remaining arguments are those passed to the object constructor expression (the call to the class). The return value of __new__() should be the new object instance (usually an instance of cls). Typical implementations create a new instance of the class by invoking the superclass’s __new__() method using super(currentclass, cls).__new__(cls[, ...]) with appropriate arguments and then modifying the newly-created instance as necessary before returning it. If __new__() returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to __new__(). If __new__() does not return an instance of cls, then the new instance’s __init__() method will not be invoked. __new__() is intended mainly to allow subclasses of immutable types (like int, str, or tuple) to customize instance creation. It is also commonly overridden in custom metaclasses in order to customize class creation. """ The problem is in this line: "If __new__() returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to __new__()." This is only true in the context of a constructor. In particular, directly calling cls.__new__(cls) will NOT call __init__. If I define a class: class C(object): def __new__(*args, **kwargs): print 'new', args, kwargs return object.__new__(*args,**kwargs) def __init__(self): print 'init' C() will result in __new__ and __init__ being both executed, but C.__new__(C) will only create the instance of C; it will not call __init__! The original documentation described in http://bugs.python.org/issue1123716 was more correct: "__new__ must return an object... If you return an existing object, the constructor call will still call its __init__ method unless the object is an instance of a different class..." That is __init__ is only being called in the context of an external constructor call. Proposed phrasing: "If __new__() is invoked during object construction (cls()) and it returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to the object constructor." ---------- assignee: docs@python components: Documentation messages: 167267 nosy: Aaron.Staley, docs@python priority: normal severity: normal status: open title: Documentation incorrectly suggests __init__ called after direct __new__ call versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15542> _______________________________________

6 9

[issue14112] tutorial intro talks of "shallow copy" concept without explanation
by Tshepang Lekhonkhobe Aug. 24, 2019

Aug. 24, 2019

New submission from Tshepang Lekhonkhobe <tshepang(a)gmail.com>: Relevant line: http://hg.python.org/cpython/file/e2eccc906354/Doc/tutorial/introduction.rs… When the concept is introduced, it appears like there's an assumption that the reader would know what it means. I'm curious if it's that common a term that it should be taken for granted, or if it deserves a definition. ---------- assignee: docs@python components: Documentation messages: 154151 nosy: docs@python, tshepang priority: normal severity: normal status: open title: tutorial intro talks of "shallow copy" concept without explanation versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

10 22

[issue12634] Random Remarks in class documentation
by Ashutosh Swain Aug. 23, 2019

Aug. 23, 2019

New submission from Ashutosh Swain <ats.engg(a)gmail.com>: URL: http://docs.python.org/tutorial/classes.html section: 9.4 Random Remarks The first sentense is bit confusing: "Data attributes override method attributes with the same name" Is it possible to change the sentense something like this: "Data attributes set through instance override method attributes with the same name" ---------- assignee: docs@python components: Documentation messages: 141073 nosy: ats.engg, docs@python priority: normal severity: normal status: open title: Random Remarks in class documentation type: feature request versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12634> _______________________________________

9 18