New submission from Marien Zwart <m_zwart(a)123mail.org>:
Based on questions asked on freenode's #python by people reading the tutorial I would like to suggest two improvements to http://docs.python.org/tutorial/errors.html#handling-exceptions :
- Mention the older "except SomeException, e:" syntax too, not just "except SomeException as e:". I have had people ask me to help them upgrade to a newer python because they thought their version of python did not support catching exception instances (their distro python being 2.5). A big fat warning that they're reading the Python 2.6 tutorial (with links to older tutorials) may also work.
- Mention "except IOError as e" before mentioning "except IOError as (errno, strerror):". The latter is an advanced and relatively unusual trick, combining regular exception catching and unpacking. Those two concepts need to be explained before the combination is. I have had people ask me how to do "except KeyError as (key, insert_something_here):" because they thought they *always* needed those parens there.
(perhaps just not mentioning unpacking here at all, using "except IOError as e:" and then using e.errno would make more sense, especially since "except IOError as (errno, strerror):" is a SyntaxError in python 3 and up (because of the unpacking) and python 2.5.x and down (because of the "as")...)
I can try to write a patch to the documentation if you like.
----------
assignee: docs@python
components: Documentation
messages: 105218
nosy: docs@python, marienz
priority: normal
severity: normal
status: open
title: Minor improvements to the "Handling Exceptions" part of the tutorial
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue8652>
_______________________________________
New submission from Dave Abrahams <dave(a)boostpro.com>:
http://docs.python.org/library/site.html#module-site mentions two variables that don't appear in my Python 2.6.5 installation's site module:
PYTHONNOUSERSITE
New in version 2.6.
PYTHONUSERBASE
New in version 2.6.
----------
assignee: docs@python
components: Documentation
messages: 104985
nosy: dabrahams, docs@python
priority: normal
severity: normal
status: open
title: Non-existent variables documented
versions: Python 2.6
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue8617>
_______________________________________
New submission from Éric Araujo <merwok(a)netwok.org>:
Attaching a patch to edit mention of “build number” in library/sys.
I also don’t understand “The first three characters are used to identify the version in the installation directories (where appropriate on each platform)”, maybe someone who does could enlighten me.
If #5778 is rejected, the doc will need another update to mention that there may be a newline in sys.version.
----------
assignee: docs@python
components: Documentation
files: sys.version1.diff
keywords: patch
messages: 112189
nosy: docs@python, merwok
priority: normal
severity: normal
stage: patch review
status: open
title: Update sys.version doc
versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2
Added file: http://bugs.python.org/file18289/sys.version1.diff
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9442>
_______________________________________
New submission from anatoly techtonik <techtonik(a)gmail.com>:
`copy` module covers very important aspect of Python programming. However its documentation doesn't provide any intro or overview of this problem starting right from details. When people meet `copy` construction in the code - the refer to module documentation and its doesn't completely answer two basic questions they have:
1. why copy module is needed (i.e. what's the problem with var assignment)
2. when and where it should be used
----------
assignee: docs@python
components: Documentation
messages: 108069
nosy: docs@python, techtonik
priority: normal
severity: normal
status: open
title: no copy.copy problem description
versions: Python 2.7, Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9021>
_______________________________________
New submission from Kirikaza <kirikaza(a)rambler.ru>:
In practice urllib reads HTTP_PROXY firstly and then if HTTP_PROXY is empty urllib reads http_proxy. Documentation (http://docs.python.org/library/urllib.html) says nothing about HTTP_PROXY.
Maybe it affects all the versions of Python.
----------
assignee: docs@python
components: Documentation
messages: 114319
nosy: docs@python, kirikaza
priority: normal
severity: normal
status: open
title: docs do not say that urllib uses HTTP_PROXY
versions: Python 2.6
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9637>
_______________________________________
New submission from Steven Bethard <steven.bethard(a)gmail.com>:
Argparse supports silencing help for certain options using SUPPRESS.
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: [-h]
optional arguments:
-h, --help show this help message and exit
This should be documented in the description of help=
http://docs.python.org/library/argparse.html#help
----------
assignee: docs@python
components: Documentation
messages: 111320
nosy: bethard, docs@python
priority: normal
severity: normal
status: open
title: document argparse's help=SUPPRESS
versions: Python 2.7, Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9349>
_______________________________________
New submission from Daniel Stutzbach <daniel(a)stutzbachenterprises.com>:
PyUnicode_EncodeDecimal is undocumented (although it's referenced in passing in the documentation for PyLong_FromUnicode). There's a lengthy comment in unicodeobject.h describing PyUnicode_EncodeDecimal, which could be converted more or less directly into documentation.
----------
assignee: docs@python
components: Documentation
messages: 105205
nosy: docs@python, stutzbach
priority: normal
severity: normal
stage: needs patch
status: open
title: PyUnicode_EncodeDecimal is undocumented
versions: Python 2.7, Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue8646>
_______________________________________
New submission from Ray.Allen <ysj.ray(a)gmail.com>:
The distutils api document for class Extension:
http://docs.python.org/dev/py3k/distutils/apiref.html#distutils.core.Extens…
Among the argument, in fact, the type of the arguments "sources", "include_dirs", "library_dirs", "libraries", "runtime_library_dirs" must be list, but all of them are marked as "string". I think this is a problem.
Here is a patch for this, against py3k.
----------
assignee: docs@python
components: Documentation
files: distutils_apiref.diff
keywords: patch
messages: 110724
nosy: docs@python, ysj.ray
priority: normal
severity: normal
status: open
title: Distutils document problem?
versions: Python 3.2
Added file: http://bugs.python.org/file18061/distutils_apiref.diff
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9302>
_______________________________________
New submission from R. David Murray <rdmurray(a)bitdance.com>:
I wanted to find out if Namespace supported lookup by subscripting (args['someopt']), but the docs are silent on what Namespace is. (The answer, by the way, appears to be "no"; there is a feature request for this in issue 8979).
----------
assignee: bethard
components: Documentation
messages: 107653
nosy: bethard, docs@python, r.david.murray
priority: normal
severity: normal
stage: needs patch
status: open
title: argparse docs cross reference Namespace as a class but the Namespace class is not documented
type: behavior
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue8982>
_______________________________________
New submission from Eli Bendersky <eliben(a)gmail.com>:
Due to a discussion on python-dev (Subject: "Markup of command-line options in Python's .rst documentation"), Georg Brandl checked in revision r82961 with a clarification of :option: markup which should only be used for Python interpreter's own flags.
However, several modules in stdlib use :option: for their own command-line options, which creates confusion (these options get linked by Sphinx to unrelated Python options).
I'm attaching a patch that fixes this issue for these files. The affected files are:
Doc/library/idle.rst
Doc/library/timeit.rst
Doc/library/test.rst
Doc/library/doctest.rst
Doc/library/unittest.rst
Doc/library/pydoc.rst
Doc/library/webbrowser.rst
Doc/library/compileall.rst
Note1: :option: was fixed to `` markup (code snippet) as per the recommendation in the updated documentation guide
Note2: I didn't patch trace.rst because it's overgoing a major rehaul (http://bugs.python.org/issue9264)
----------
assignee: docs@python
components: Documentation
messages: 110862
nosy: docs@python, eli.bendersky
priority: normal
severity: normal
status: open
title: Fix usage of :option: markup in stdlib ReST docs
type: behavior
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9312>
_______________________________________