New submission from Luke Plant <L.Plant.98(a)cantab.net>:
Docs for SimpleCookie, BaseCookie.value_encode and BaseCookie.value_decode are obviously incorrect. Attempt at patch attached.
The error has existed in every Python version I've seen, I've tagged the ones I believe can receive fixes, sorry if I've made a mistake.
Thanks.
----------
assignee: docs@python
components: Documentation
files: http_cookies_doc_corrections.diff
keywords: patch
messages: 126962
nosy: docs@python, spookylukey
priority: normal
severity: normal
status: open
title: Various obvious errors in cookies documentation
versions: Python 2.7, Python 3.1, Python 3.2
Added file: http://bugs.python.org/file20507/http_cookies_doc_corrections.diff
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue11001>
_______________________________________
New submission from Jyrki Pulliainen <jyrki(a)dywypi.org>:
In threading module, the Lock.acquire documentation is misleading. The signature suggests that the blocking can be given as a keyword argument but that would lead to an TypeError, as thread.lock.acquire does not accept keyword arguments.
The signature in documentation should be formatted as in thread.lock.acquire.
----------
assignee: docs@python
components: Documentation
messages: 124861
nosy: Jyrki.Pulliainen, docs@python
priority: normal
severity: normal
status: open
title: Lock.acquire documentation is misleading
versions: Python 2.7, Python 3.1
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue10789>
_______________________________________
New submission from Antoine Pitrou <pitrou(a)free.fr>:
The urllib.request documentation intermingles old 2.x urllib (FancyURLopener, etc.) with urllib2-inherited (*Handler, build_opener, etc.) primitives without making any distinction. This makes it rather confusing for the reader to figure out which ones to use.
Ideally, the use of the old primitives should also be discouraged.
----------
assignee: docs@python
components: Documentation
messages: 118179
nosy: docs@python, orsenthil, pitrou
priority: normal
severity: normal
stage: needs patch
status: open
title: urllib.request documentation confusing
versions: Python 3.1, Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue10048>
_______________________________________
New submission from Pierre Quentel <pierre.quentel(a)gmail.com>:
Hi,
I wrote a patch for the cgi module in version 3.2rc1 (#4953). Small changes should be done to the documentation of this module to reflect the changes in the module API :
- in section "20.2.2. Using the cgi module"
original text :
"If a field represents an uploaded file, accessing the value via the value attribute or the getvalue() method reads the entire file in memory as a string. This may not be what you want. You can test for an uploaded file by testing either the filename attribute or the file attribute. You can then read the data at leisure from the file attribute:"
proposed new text (for files, value is bytes, not string, and the read() method on file also returns bytes) :
"If a field represents an uploaded file, accessing the value via the value attribute or the getvalue() method reads the entire file in memory as bytes. This may not be what you want. You can test for an uploaded file by testing either the filename attribute or the file attribute. You can then read the data at leisure from the file attribute (the read() and readline() methods will return bytes) :"
- version 3.2 introduced a parameter "encoding" for the FieldStorage constructor, used to decode the bytes received on the HTTP connection for fields other than files. This encoding must the one defined in the HTML document holding the form submitted to the CGI script ; it is usually defined by a meta tag :
<meta http-equiv="Content-type" content="text/html;charset=latin-1">
or by the Content-Type header for this document
I'm not sure where this should be mentioned in the module documentation. Maybe in "20.2.9. Common problems and solutions" for the moment. But there are plans (#11066) to introduce another interface to change the encoding of sys.stdout in the CGI script itself, so another option would be to open a specific section about encodings
Hope it's clear enough
Pierre
----------
assignee: docs@python
components: Documentation
messages: 129691
nosy: docs@python, quentel
priority: normal
severity: normal
status: open
title: Buf in cgi module doc
type: behavior
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue11352>
_______________________________________
New submission from Éric Araujo <merwok(a)netwok.org>:
Built-in containers like dict use an ellipsis to represent a recursive item. In the symbols index, “...” only links to the secondary prompt; I think it should also link to a paragraph explaining the display of recursive containers.
----------
assignee: docs@python
components: Documentation
keywords: easy
messages: 116256
nosy: docs@python, eric.araujo
priority: normal
severity: normal
stage: needs patch
status: open
title: Document ... used in recursive repr of containers
versions: Python 2.7, Python 3.1, Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9842>
_______________________________________
New submission from Sandro Tosi <sandro.tosi(a)gmail.com>:
Hi, following up http://mail.python.org/pipermail/docs/2011-February/003083.html we have a chat on #python-dev on the topic, the situation is
- all started with os.lchmod() and as.lchflags() methods not available on a Debian system
- that's because POSIX does not require those functions and then Linux systems don't provide them
- so we then thought about clarifying, only for those 2 methods, that they might not be available with a format like "availability: some unix systems"
- then we noticed that on top of os doc there's a notice "An “Availability: Unix” note means that this function is commonly found on Unix systems. It does not make any claims about its existence on a specific operating system." and so we thought about linking every 'Availability: Unix' to that note
- or transform that not in a footnote and link every 'Availability: Unix' for functions that might not be present to that footnote.
It's enough for the conversation dump: ideas/suggestions? :)
----------
assignee: docs@python
components: Documentation
messages: 128746
nosy: docs@python, sandro.tosi
priority: normal
severity: normal
status: open
title: clarifying Availability: Unix
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue11233>
_______________________________________
New submission from Nick Coghlan <ncoghlan(a)gmail.com>:
The test.support docs are there to help CPython devs with writing good unit tests more easily. There are a few additions we've made in recent years that haven't made it into the .rst file, so it is easy to miss useful tools if you don't go looking through the module source code.
There are some other helper modules (such as test.script_helper) that could also stand to be made easier to find.
Fixing this is just a matter of doing a pass through test.support and the test directory looking for things that might be worth mentioning in the test package docs.
----------
assignee: docs@python
keywords: easy
messages: 127086
nosy: docs@python, ncoghlan
priority: normal
severity: normal
stage: needs patch
status: open
title: Bring test.support docs up to date
type: behavior
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue11015>
_______________________________________
New submission from Paul Davis <paul.joseph.davis(a)gmail.com>:
The docs for __getattr__ in the object model section could be more specific on the behavior when a @property raises an AttributeError and there is a custom __getattr__ defined. Specifically, it wasn't exactly clear that __getattr__ would be invoked after a @property was found and evaluated.
The attached script demonstrates the issue on OS X 10.6, Python 2.6.1
I'm thinking something along the lines of:
If the attribute search encounters an AttributeError (perhaps due to a @property raising the error) the search is considered a failure and __getattr__ is invoked.
----------
assignee: docs@python
components: Documentation
files: example.py
messages: 105790
nosy: Paul.Davis, docs@python
priority: normal
severity: normal
status: open
title: Documentation for __getattr__
type: feature request
versions: Python 2.6
Added file: http://bugs.python.org/file17349/example.py
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue8722>
_______________________________________
New submission from Alan Isaac <alan.isaac(a)gmail.com>:
In PEP 227 missing text is marked with XXX. Most of this is just calls for examples and elaboration. However under the Implementation section XXX marks a substantive question about the documentation.
Fixing this may be low priority, but a tracker search suggested it is currently not even being tracked ...
----------
assignee: docs@python
components: Documentation
messages: 127184
nosy: aisaac, docs@python
priority: normal
severity: normal
status: open
title: pep 227 missing text
type: feature request
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue11023>
_______________________________________
New submission from Xavier Morel <xavier.morel(a)masklinn.net>:
argparse has been merged to the standard library in 3.2, and (tell me if I'm wrong) would therefore be the "best-practices" way to parse command-line arguments.
Numerous stdlib modules can be used as scripts, but they tend to have ad-hoc documentation (if they are at all documented) and arguments parsing (using any of the 4 available methods in Python: straight from sys.argv, getopt, optparse and argparse).
I picked smtpd as a first shot since it does something useful (SMTP proxy) and has a pretty good (if ad-hoc) command-line documentation.
smtpd is currently using getopt for its options parsing and the argument parsing is very cleanly factored: the port only had to replace the implementation of the `parseargs` function (and add and remove some helpers).
* The port keeps the existing arguments semantics (including the mandatory host:port syntax for the local and remote specs if overridden)
* The port tries to maintain the old error messages, but due to the way argparse works (or the way I used it for the specs) the parity is not perfect when providing incorrect specs
* The CLI help uses argparse's formatting, and the documentation for the local and remote specs was set on these arguments rather than as an epilog. The version string was also removed from the help screen
* Because they are set by argparse's arguments validation, the status codes on incorrect arguments are slightly different:
- running smtpd.py as a regular user without the `--nosetuid` flag still exits with status 1
- providing incorrect spec formats (missing or non-int port) or providing too many positional arguments (3 or more) now exits with status 2 (formerly 1)
----------
assignee: docs@python
components: Documentation, Library (Lib)
files: smtpd-to-argparse.diff
keywords: patch
messages: 128917
nosy: barry, docs@python, xmorel
priority: normal
severity: normal
status: open
title: smtpd-as-a-script feature should be documented and should use argparse
versions: Python 3.3
Added file: http://bugs.python.org/file20812/smtpd-to-argparse.diff
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue11260>
_______________________________________
