New submission from Craig McQueen <python(a)craig.mcqueen.id.au>:
I have just been trying to figure out how string interpolation works for "%s", when Unicode strings are involved. It seems it's a bit complicated, but the Python documentation doesn't really describe it. It just says %s "converts any Python object using str()".
Here is what I have found (I think), and it could be worth improving the documentation of this somehow.
Example 1:
"%s" % test_object
>From what I can tell, in this case:
1. test_object.__str__() is called.
2. If test_object.__str__() returns a string object, then that is substituted.
3. If test_object.__str__() returns a Unicode object (for some reason), then test_object.__unicode__() is called, then _that_ is substituted instead. The output string is turned into Unicode. This behaviour is surprising.
[Note that the call to test_object.__str__() is not the same as str(test_object), because the former can return a Unicode object without causing an error, while the latter, if it gets a Unicode object, will then try to encode('ascii') to a string, possibly generating a UnicodeEncodeError exception.]
Example 2:
u"%s" % test_object
In this case:
1. test_object.__unicode__() is called, if it exists, and the result is substituted. The output string is Unicode.
2. If test_object.__unicode__() doesn't exist, then test_object.__str__() is called instead, converted to Unicode, and substituted. The output string is Unicode.
Example 3:
"%s %s" % (u'unicode', test_object)
In this case:
1. The first substitution causes the output string to be Unicode.
2. It seems that (1) causes the second substitution to follow the same rules as Example 2. This is a little surprising.
----------
assignee: docs@python
components: Documentation
messages: 109516
nosy: cmcqueen1975, docs@python
priority: normal
severity: normal
status: open
title: Improve docs for string interpolation "%s" re Unicode strings
versions: Python 2.7
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9196>
_______________________________________
New submission from INADA Naoki <songofacandy(a)gmail.com>:
* Insert spaces around operators and after commas.
* Split one liner blocks (ex. def foo(x, y): return x + y) to
multi-line blocks.
* Insert empty line after def block for scripts (not interactive mode).
* Use new-style raise (s/ralse KeyboardInterrupt/raise KeyboardInterrupt()/)
* Use x ** 3 instead of x * x * x.
Attached patch is for Python 2.6.
I'll make same changes for Python 3.1 if this patch is accepted.
----------
assignee: docs@python
components: Documentation
files: cleanup_tutorial_codes.patch
keywords: patch
messages: 130225
nosy: docs@python, naoki
priority: normal
severity: normal
status: open
title: Cleanup sample codes in tutorial.
versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3
Added file: http://bugs.python.org/file21027/cleanup_tutorial_codes.patch
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue11425>
_______________________________________
New submission from anatoly techtonik <techtonik(a)gmail.com>:
The abundance of methods and hierarchy depth of various servers from "Internet Protocols and Support" section makes it extremely hard to navigate information. You need a strong OOP background to be able to use this doc effectively, as examples are not intuitive otherwise.
Usually you need a decent IDE (such as Eclipse) to get a picture of class hierarchy and a table of all available methods with a mark where they were inherited from.
Such table (at least Class Hierarchy view screenshot from Eclipse) should be available in reference for descendant classes.
----------
assignee: docs@python
components: Documentation
messages: 107321
nosy: docs@python, techtonik
priority: normal
severity: normal
status: open
title: *HTTPServer need a summary page with API inheritance table
versions: Python 2.7, Python 3.1, Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue8940>
_______________________________________
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>
_______________________________________
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>
_______________________________________
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>
_______________________________________
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>
_______________________________________
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>
_______________________________________
New submission from Nick Coghlan <ncoghlan(a)gmail.com>:
There are currently undocumented PyEval_Call* equivalents to a number of the PyObject_Call* functions.
Since there are resources out there on the web that direct people to use the currently undocumented PyEval functions, it would be good to document those properly, and recommend people typically use the PyObject_Call* variants instead (as the latter include all the stack and interpreter state integrity protection code, while the PyEval variants assume that has all already been handled).
----------
assignee: docs@python
components: Documentation
keywords: easy
messages: 128248
nosy: docs@python, ncoghlan
priority: normal
severity: normal
stage: needs patch
status: open
title: Document PyEval_Call* functions
versions: Python 2.7, Python 3.2, Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue11165>
_______________________________________
New submission from Éric Araujo <merwok(a)netwok.org>:
A patch made for #2504 revealed a bug in gettext.rst, and I’ve found a number of other things to change in the file. This is the first patch of a series of two or three.
Barry, as the original author of the module and doc, I’d like your opinion on points 3, a, and b particularly.
Patch is also uploaded to Rietveld for greater convenience: http://codereview.appspot.com/3333042/ (upload.py rocks)
Summary:
1) Markup: Use modern class/method directives combo (yay DRY). Mark up variable parts in :file: constructs (e.g. :file:`{domain}.mo` will cause the HTML output to use var to indicate replaceable text). Also change some ``gettext`` to :program:`gettext` for consistency.
2) Fix a typo in lngettext doc (originally included in patch by Franz Glasner for #2504).
3) I had started to remove information about private attributes (_info, _charset), advertising public getter methods instead. Then I read the description of NullTranslations and realized the information was needed for subclasses. I’ve reverted my removals, but I still think the private attributes should be listed in a specific section for people writing subclasses and not in the rest of the text. If you’re okay, I’ll make a second patch.
4) Assorted wording changes, missing periods and hyphens, and other very small touch-ups: Turned a broken bare link into a working link with nice text; used the with statement in an example (we all love the with statement!); used two spaces after periods throughout (hello Fred Drake).
Final note: lines have not been rewrapped, for diff clarity. When I commit part or all of this patch, I’ll make another commit to rewrap.
Not addressed:
a) The current docs is currently POSIX-specific.
b) The docs take great care to explain that Unicode strings will be returned in different places, but this should not be so accented in 3.x docs IMO. I would just put a note somewhere near the top that all strings are str and remove the redundant sentences. Following that line of thought, I could group all l*gettext variants at the end of the list of methods, explaining that regular usage should just be happy with str objects and that l*gettext are available if people really want bytes.
c) The file uses “built-in namespace” and “builtins namespace”, sometimes in neighbor paragraphs. :mod:`builtins` is not used, even in explanations of the install function/method. I don’t know if I should change that.
d) Some capitalization patterns look strange to me: I have seen “I18N” and “L10N” in upper case nowhere else. Similarly, lower-case “id” looks stranger than “ID”. The latter is used for example in official GNU gettext docs. Am I going into foolish consistency territory or not?
Thanks in advance for reviews and opinions.
----------
assignee: eric.araujo
components: Documentation
files: gettext-docs-1.diff
keywords: needs review, patch
messages: 122420
nosy: barry, docs@python, eric.araujo
priority: normal
severity: normal
stage: patch review
status: open
title: Enhancements to gettext docs
versions: Python 2.7, Python 3.1, Python 3.2
Added file: http://bugs.python.org/file19819/gettext-docs-1.diff
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue10536>
_______________________________________