New submission from anatoly techtonik <techtonik(a)gmail.com>:
http://docs.python.org/library/cmd.html#
Documentation for cmd module is poor to explain the value of this module to users. Intro is too abstract - phrase "simple framework for writing line-oriented command interpreters" doesn't mean much. Perhaps word "interactive" is missing?
So, there is no part explaining the what cmd does exactly (intro fails) and no part explaining the main principle - How exactly does this framework allows to do this in a simple way? (I guess reference part under 'Cmd objects -> Cmd.cmdloop([intro]) -> p[4]` does that, but it is not the place you'd usually expect this info.
At the very least what could be done is a link to Doug's tutorial http://www.doughellmann.com/PyMOTW/cmd/
----------
assignee: docs@python
components: Documentation
messages: 152010
nosy: docs@python, techtonik
priority: normal
severity: normal
status: open
title: cmd: no user documentation
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue13875>
_______________________________________
New submission from Stefan Chrobot:
http://docs.python.org/3/reference/simple_stmts.html#assignment-statements
The docs says:
"If the target is a slicing: The primary expression in the reference is evaluated. It should yield a mutable sequence object (such as a list). The assigned object should be a sequence object of the same type."
This seems wrong, because the assigned object can be any iterable:
a = [4, 5, 6]
a[0:0] = range(1, 4)
# a is now [1, 2, 3, 4, 5, 6]
----------
assignee: docs@python
components: Documentation
messages: 188738
nosy: docs@python, stefanchrobot
priority: normal
severity: normal
status: open
title: Misleading information about slice assignment in docs
type: enhancement
versions: Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue17939>
_______________________________________
New submission from Terry J. Reedy <tjreedy(a)udel.edu>:
In 3.3. Special method names, 'object' is used as a pseudo class name to prefix all the special method entries. This conflicts with the usual two Python meanings.
1. 'object' is the name of a specific class. So the entry for object.__getattribute__(self, name) says to avoid circularity by calling
object.__getattribute__(self, name), which looks circular and requires a bit a mental work by the reader to properly understand. Ditto for
object.__setattr__(self, name, value) calling
object.__setattr__(self, name, value)
2. Non-specifically, 'object' is usually understood to mean any Python object, not just a class. But the signatures as written require that 'object' specifically be a class and 'object' does not convey that.
So for both reasons, I propose that the pseudoname 'object' be replaces with 'class' or 'someclass'
----------
assignee: docs@python
components: Documentation
messages: 113194
nosy: docs@python, georg.brandl, terry.reedy
priority: normal
severity: normal
stage: needs patch
status: open
title: Replace confusing pseudoname 'object' in special methods section.
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9538>
_______________________________________
New submission from Michael Foord <michael(a)voidspace.org.uk>:
Where os.listdir encounters undecodable bytes from the filesystem it uses the surrogateescape handler. As the resulting strings are invalid they can't be encoded without an errorhandler, and so can't be printed (for example).
This should be documented.
----------
assignee: docs@python
components: Documentation
messages: 149070
nosy: docs@python, michael.foord
priority: normal
severity: normal
stage: needs patch
status: open
title: os.listdir documentation should mention surrogateescape
versions: Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue13561>
_______________________________________
New submission from beeNuts <jeff.adams(a)linux.com>:
Issue #14144, with the title "urllib2 HTTPRedirectHandler not forwarding POST data in redirect" was recently closed with these comments:
"This could be cookbook recipe style example, if it's utility
value is high. I am closing this issue as I feel that the requirement may not be addressed by a change. If there is patch for HowTo, we can tackle that in another issue. Thank you for contribution."
The decision that documents on this issue were preferable to a patch seems like a fair compromise, especially considering that the RFC is decidedly ambiguous.I was wondering if the HowTo would be forthcoming?
It seems to me that the value/utility would certainly be high. I'd submit it myself but I'm so new to Python that I don't trust my ability to do it correctly. It's something I would find highly useful, though.
----------
assignee: docs@python
components: Documentation
messages: 156080
nosy: beerNuts, docs@python
priority: normal
severity: normal
status: open
title: urllib2 HowTo for overriding post/3xx behavior.
versions: Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue14338>
_______________________________________
New submission from Giampaolo Rodola':
In Python 2 the distinction between open() and codes.open() was clear because 'encoding' and 'errors' args were provided by codecs.open only.
This is no longer the case in Python 3 since both args are provided also by open().
I'm probably missing something but regardless I think codecs.open doc [1] should be more clear as to when and why (say) codecs.open(file, encoding='utf8', errors='ignore') should be preferred over open(file, encoding='utf8', errors='ignore').
[1] http://docs.python.org/3/library/codecs.html#codecs.open
----------
assignee: docs@python
components: Documentation
messages: 184303
nosy: docs@python, ezio.melotti, giampaolo.rodola
priority: normal
severity: normal
status: open
title: Difference between open and codecs.open
versions: Python 3.2, Python 3.3, Python 3.4
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue17437>
_______________________________________
New submission from Antoine Pitrou <pitrou(a)free.fr>:
Sébastien, would you like to provide an updated version of that file? The current contents look hopelessly outdated.
----------
assignee: docs@python
components: Documentation
messages: 124024
nosy: docs@python, pitrou, sable
priority: normal
severity: normal
stage: needs patch
status: open
title: Misc/AIX-NOTES needs updating
versions: Python 2.7, Python 3.1, Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue10709>
_______________________________________
New submission from R. David Murray <rdmurray(a)bitdance.com>:
And I wish I knew what those were.
----------
assignee: docs@python
components: Documentation
messages: 162513
nosy: docs@python, r.david.murray
priority: normal
severity: normal
stage: needs patch
status: open
title: tutorial should use best practices in user defined execeptions section
type: behavior
versions: Python 2.7, Python 3.2, Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue15034>
_______________________________________
New submission from Éric Araujo <merwok(a)netwok.org>:
argparse helpfully makes its messages with gettext.gettext. The docs should explain how to benefit from that in one’s program.
----------
assignee: docs@python
components: Documentation
messages: 122358
nosy: bethard, docs@python, eric.araujo
priority: normal
severity: normal
stage: needs patch
status: open
title: Write argparse i18n howto
type: feature request
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue10529>
_______________________________________
New submission from Роман Донченко <DXDragon(a)yandex.ru>:
The language reference says this in section 3.2:
~
Built-in functions
A built-in function object is a wrapper around a C function. Examples of built-in functions are len() and math.sin() <...> Special read-only attributes: <...> __self__ is set to None (but see the next item) <...>.
~
That is not the case:
ActivePython 3.2.2.3 (ActiveState Software Inc.) based on
Python 3.2.2 (default, Sep 8 2011, 10:55:13) [MSC v.1500 64 bit (AMD64)]
on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> len.__self__
<module 'builtins' (built-in)>
>>> open.__self__
<module 'io' (built-in)>
>>> import math
>>> math.sin.__self__
<module 'math' (built-in)>
----------
assignee: docs@python
components: Documentation
messages: 153287
nosy: SpecLad, docs@python
priority: normal
severity: normal
status: open
title: __self__ on built-in functions is not as documented
type: behavior
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue14003>
_______________________________________