New submission from Chris Rebert <pybugs(a)rebertia.com>:
http://docs.python.org/py3k/library/os.html currently mentions os.popen() in several places. The docs for os.popen() itself say:
'These functions are described in section "File Object Creation"'
However, unlike the 2.x version of that section ( http://docs.python.org/library/os.html#file-object-creation ), the os.popen*() family is not documented there [or indeed anywhere] anymore ( http://docs.python.org/py3k/library/os.html#os-newstreams ); the entire section now only documents os.fdopen().
The 2.7 docs say that the os.popen*() family are deprecated, and indeed, of the family, only os.popen() seems to still exist in Python 3.x (at least based on my testing via ideone.com).
Thus, from what I can see, one of the following is the case:
(A) The entire os.popen*() family is supposed be gone in Python 3.x, so os.popen() should be removed entirely from both the code and the docs.
(B) os.popen() is the sole legitimate survivor of its family, and should be properly documented again.
(C) os.popen() was left in as a kludge, shouldn't be mentioned in the docs, and possibly should be renamed os._popen() to reflect its status.
So, which one of these is it?
----------
assignee: docs@python
components: Documentation
messages: 111597
nosy: cvrebert, docs@python
priority: normal
severity: normal
status: open
title: os.popen referenced but not documented in Python 3.x
versions: Python 3.1
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9382>
_______________________________________
New submission from Cherniavsky Beni <cben(a)users.sf.net>:
>>> help('nonlocal')
no Python documentation found for 'nonlocal'
As a language keyword, it clearly should have documentation.
----------
assignee: docs@python
components: Documentation
messages: 115266
nosy: cben, docs@python
priority: normal
severity: normal
status: open
title: help('nonlocal') missing
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9724>
_______________________________________
New submission from Eli Bendersky <eliben(a)gmail.com>:
The documentation of the standard 'trace' module (Doc/library/trace.rst) is sorely lacking. Arguments are not explained, some key methods are not documented at all, and the CoverageResults class isn't documented.
Usage of these appears in the example but leaves the user confused as the only source of documentation for the example is the source code of the module.
I'm attaching a patch that fixes this issue, by providing documentation for the missing parts.
The patch was generated vs. the latest SVN trunk.
----------
assignee: docs@python
components: Documentation
files: tracedoc.3.patch
keywords: patch
messages: 110344
nosy: docs@python, eli.bendersky, tjreedy
priority: normal
severity: normal
status: open
title: trace.py documentation is incomplete
type: behavior
versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2
Added file: http://bugs.python.org/file18009/tracedoc.3.patch
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9264>
_______________________________________
New submission from anatoly techtonik <techtonik(a)gmail.com>:
Quite often people use .json files for storing configuration. Having a reference to json module from chapter "14. File Formats" would be a good pointer for those looking to .ini alternatives.
----------
assignee: docs@python
components: Documentation
messages: 108833
nosy: docs@python, techtonik
priority: normal
severity: normal
status: open
title: reference json format in file formats chapter
versions: Python 2.6, Python 2.7, Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9101>
_______________________________________
New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>:
Unlike sys.settrace, sys.setprofile is not described as CPython implementation detail in Doc/library/sys.rst.
----------
assignee: docs@python
components: Documentation
messages: 111199
nosy: belopolsky, docs@python
priority: normal
severity: normal
stage: needs patch
status: open
title: sys.setprofile is not described as CPython implementation detail
type: feature request
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9331>
_______________________________________
New submission from Steven Bethard <steven.bethard(a)gmail.com>:
[From http://code.google.com/p/argparse/issues/detail?id=61]
It should be documented clearly that only the arguments present on the parent parser at the time ArgumentParser is called will be included in the parser.
>>> parent = argparse.ArgumentParser(add_help=False)
>>> child = argparse.ArgumentParser(parents=[parent])
>>> parent.add_argument('--foo', action='store_true')
>>> child.parse_args(['--foo'])
usage: [-h]
: error: unrecognized arguments: --foo
----------
assignee: docs@python
components: Documentation
messages: 111306
nosy: bethard, docs@python
priority: normal
severity: normal
status: open
title: Document that argparse "parents" must be fully declared before children
versions: Python 2.7, Python 3.2, Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9343>
_______________________________________
New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>:
This bikeshed have been repainted several times already, but here is a true story.
Cast:
Me = myself
Novice = a 14-year-old boy
Laptop = a MacBook Air
Novice: How do i exit [from python prompt]?
Me: What's your best guess?
Novice: [typing] exit [pressing Enter]
Laptop: Use exit() or Ctrl-D (i.e. EOF) to exit
Novice: [typing] Ctrl...
Me: OMG, you don't know what Ctrl-D means? Look for the Ctrl key.
Novice: There is no such key.
--- curtains ---
I suggest changing
Use exit() or Ctrl-D (i.e. EOF) to exit
to
Type exit() or quit() and press the Enter key to exit
or
Type exit() or quit() and press Enter to exit
or just
Use exit() to exit
My theory is that someone who knows what EOF is, will probably already know how to exit from common terminal oriented programs and Ctrl-D is not universally bound to EOF.
TOOWTDI: two ways to exit is more than enough to teach a novice.
----------
assignee: docs@python
components: Documentation
keywords: easy
messages: 111374
nosy: belopolsky, docs@python
priority: normal
severity: normal
status: open
title: Make exit/quit hint more novice friendly
type: feature request
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9362>
_______________________________________
New submission from Terry J. Reedy <tjreedy(a)udel.edu>:
As reported on python-list by Alan G Isaac,
Lib Ref 6.1.3.1. Format Specification Mini-Language, for instance
http://docs.python.org/dev/py3k/library/string.html#formatstrings
wrongly says in the alignment section
"'<' Forces the field to be left-aligned within the available space (This is the default.)"
This latter, of course, is not true for number fields.
"(This is the default.)" could be replaced by "(the string default)."
(in any case, the '.' should be outside the () unless one is added after 'space' before '(') and "(the number default)" added to the next line. Or instead the issue of defaults could be addressed in the text below the table.
I am assuming that this issue affects 2.6/7.
----------
assignee: docs@python
components: Documentation
messages: 105536
nosy: docs@python, tjreedy
priority: normal
severity: normal
status: open
title: Doc: left alignment is not the default for numbers
versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue8691>
_______________________________________
New submission from Brandon Craig Rhodes <brandon(a)rhodesmill.org>:
The only way to safely build shell command lines from inside of Python — which is necessary when sending commands across SSH, since that behaves like os.system() rather than like subprocess.call() — is to use the wonderful pipes.call() method to turn possibly-dangerous arguments, like filenames that might have spaces, special characters, and embedded "rm -r" calls, into perfectly quoted strings for an "sh"-like shell (say, bash or zsh).
This call is already recommended on mailing lists, blog posts, and Stack Overflow — and since it doesn't start with a "_", I think its public use is fair game. But the "pipes" documentation itself doesn't officially mention or support it. I think it should be added to the Standard Library documentation for "pipes". So. Yeah.
----------
assignee: docs@python
components: Documentation
messages: 115263
nosy: brandon-rhodes, docs@python
priority: normal
severity: normal
status: open
title: pipes.quote() needs to be documented
type: feature request
versions: Python 2.5, Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9723>
_______________________________________
New submission from Arnaud Delobelle <arnodel(a)googlemail.com>:
More detailed explanation of how in place operators work, and how they are related to the operator module iadd, isub, ... functions.
Submitted following this message on python-list:
http://mail.python.org/pipermail/python-list/2010-August/1254243.html
----------
assignee: docs@python
components: Documentation
files: operator_inplace.diff
keywords: patch
messages: 115237
nosy: arno, docs@python
priority: normal
severity: normal
status: open
title: operator module - "in place" operators documentation
versions: Python 3.3
Added file: http://bugs.python.org/file18682/operator_inplace.diff
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9717>
_______________________________________