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 Renato Cunha <renato(a)renatocunha.com>:
PyObject_HEAD's documentation in py3k (http://docs.python.org/dev/py3k/c-api/structures.html#PyObject_HEAD) uses the same content used in the python 2.x's docs which is wrong, as there were some API changes.
PyObject_HEAD is actually defined as
#define PyObject_HEAD PyObject ob_base;
with PyObject defined as
typedef struct _object {
_PyObject_HEAD_EXTRA
Py_ssize_t ob_refcnt;
struct _typeobject *ob_type;
} PyObject;
(The PyTRACE_REFS discussion is still valid, though.)
Additionally, it'd be nice to mention that the Py_REFCNT(ob) and Py_TYPE(ob) macros should be used to access the PyObject members.
----------
assignee: docs@python
components: Documentation
messages: 107953
nosy: docs@python, trovao
priority: normal
severity: normal
status: open
title: Incorrect documentation of the PyObject_HEAD macro
type: behavior
versions: Python 3.1, Python 3.2, Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9014>
_______________________________________
New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>:
>From <http://docs.python.org/dev/py3k/library/datetime.html#datetime.tzinfo.utcof…>:
"""
tzinfo.utcoffset(self, dt)
Return offset of local time from UTC, in minutes east of UTC.
"""
This suggests that the return value is an integer representing the number of minutes. It is later explained that in fact "the value returned must be a timedelta object specifying a whole number of minutes", but many users won't read past the first sentence.
I suggest s/in minutes east of UTC/as a timedelta object/. I think "east of UTC" is redundant given the next sentence, "If local time is west of UTC, this should be negative", but that can also be reworded for clarity as "The offset for timezones west of UTC is negative, and for those east of UTC is positive."
----------
assignee: docs@python
components: Documentation
keywords: easy
messages: 106371
nosy: belopolsky, docs@python
priority: normal
severity: normal
status: open
title: TZ offset description is unclear in docs
versions: Python 2.7, Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue8810>
_______________________________________
New submission from STINNER Victor <victor.stinner(a)haypocalc.com>:
The documentation of PyArg_Parse*() number formats specify that only int / float / complex are accepted, whereas any int / float / complex compatible object is accepted. "compatible" means that it has an __int__() / __float__() / __complex__() method, or nb_int / nb_float of Py_TYPE(obj)->tp_as_number->nb_int is defined (tp_as_number has no nb_complex).
I suppose that the following paragraph is also outdated:
"It is possible to pass "long" integers (integers whose value exceeds the
platform's :const:`LONG_MAX`) however no proper range checking is done --- the
most significant bits are silently truncated when the receiving field is too
small to receive the value (actually, the semantics are inherited from downcasts
in C --- your mileage may vary)."
Moreover, "without overflow checking" should be explained (Mark told me that the number is truncated to a power of 2).
----------
assignee: docs@python
components: Documentation, Interpreter Core
messages: 107379
nosy: docs@python, haypo, mark.dickinson
priority: normal
severity: normal
status: open
title: Doc/c-api/arg.rst: fix documentation of number formats
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue8952>
_______________________________________
New submission from Marc-Andre Lemburg <mal(a)egenix.com>:
This needs to be done to protect our users (importing crypto code or using it may be illegal in their home country, see http://rechten.uvt.nl/koops/cryptolaw/ for a survey) and to satisfy an attribution requirement in the OpenSSL license and code base:
"""
This product includes cryptographic software written by Eric Young (eay(a)cryptsoft.com). This product includes software written by Tim Hudson (tjh(a)cryptsoft.com). This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)
"""
----------
assignee: docs@python
components: Build, Documentation
messages: 108929
nosy: docs@python, lemburg
priority: normal
severity: normal
status: open
title: Python download page needs to mention crypto code in Windows installer
versions: 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/issue9119>
_______________________________________
New submission from John Posner <jjposner(a)optimum.net>:
The documentation for collections.defaultdict is confusing with respect to the __missing__ method. The fact is that a programmer using defaultdict does not need to know anything about __missing__.
The attached patch contains a rewrite of the entire section (but not the "defaultdict Examples" section, which is fine.
----------
assignee: docs@python
components: Documentation
files: defaultdict.patch
keywords: patch
messages: 113105
nosy: docs@python, jjposner
priority: normal
severity: normal
status: open
title: defaultdict doc makes incorrect reference to __missing__ method
versions: Python 2.7
Added file: http://bugs.python.org/file18417/defaultdict.patch
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9536>
_______________________________________
New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>:
Is there a reason for not documenting Py_TPFLAGS_LONG_SUBCLASS (Py_TPFLAGS_INT_SUBCLASS in 2.x)?
This flag is used in PyLong_Check, but neither this flag or its inheritance properties are explained anywhere in the docs.
See also issue5476.
----------
assignee: docs@python
components: Documentation
messages: 110787
nosy: belopolsky, docs@python
priority: normal
severity: normal
stage: needs patch
status: open
title: Py_TPFLAGS_LONG_SUBCLASS is not documented
type: feature request
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9307>
_______________________________________
New submission from Eli Bendersky <eliben(a)gmail.com>:
The first paragraph in its documentation says:
"""
In the Python interpreter, do "from pydoc import help" to provide online
help. Calling help(thing) on a Python object documents the object.
"""
Which is no longer accurate, because the help() function has long ago become a built-in.
Below is an excerpt from Terry Reedy in a private email discussion on this subject, that raises more issues.
---------------------------------------------
1. The output from help(help) could be made more clear.
The nature of 'help' has been a point of confusion. A recent python-list post asked something like "What is 'help'?"
Now (with some parallel examples:
>>> help(int)
Help on class int in module builtins:
class int(object)
[snip]
>>> help(1)
Help on int object:
class int(object)
[snip]
>>> help(help)
Help on _Helper in module site object:
class _Helper(builtins.object)
| Define the built-in 'help'.
| This is a wrapper around pydoc.help (with a twist).
|
| Methods defined here:
|
| __call__(self, *args, **kwds)
|
a. 'module site object' is nonsense, it should just be 'module site', except that to be parallel to what is done for other instances, it should be 'Help on _Helper object'. Why should help special-case itself (with a slightly garbled line?) Is that done in site._Helper or pydoc.help?
However, it would be more helpful for all instances to give the location of the class when one asks for help on an instance, just as when one asks for help on the class itself. It is annoying to to have to repeat help(<classname>) just to get that info. So I would like to see
"Help on instance of class int in module builtins:"
"Help on instance of class _Helper in module site:"
This would be a code patch to pydoc.help
b. "This is a wrapper around pydoc.help" good so far
"(with a twist)" thanks a lot. I think the comment should be either removed or explained. A reference manual should explain, not tease.
Replace "Define the built-in 'help'." with something clearer and more accurate, such as "The name 'help' is injected in module builtins after being bound to an instance of this class.". Put this after, not before, the 'wrapper' line.
A patch for site._Helper doc string.
2. Improve manual chapter for site module.
a. It currently starts "Importing this module will append site-specific paths to the module search path." Add "inject 'help' into builtins and " after append. Then add a short explanation paragraph before the search path stuff. Something like
"This module contains a class (_Helper) that wraps function pydoc.help. An instance of the class is bound to name 'help' in the builtins module."
A recent discussion on pydev or maybe python-list (in the thread mentioned above?) implied that one could usefully make another instance of _Helper or maybe a subclass thereof. I did not pay enough attention, though, to really get it.
b. It currently ends with "XXX Update documentation XXX document python -m site –user-base –user-site"
----------
assignee: docs@python
components: Documentation
messages: 111426
nosy: docs@python, eli.bendersky, tjreedy
priority: normal
severity: normal
status: open
title: some problems with the documentation of pydoc
type: behavior
versions: Python 3.1, Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9364>
_______________________________________
New submission from Brett Cannon <brett(a)python.org>:
Documenting that would help get people using datetime objects with string.format more.
----------
assignee: docs@python
components: Documentation
keywords: easy
messages: 107179
nosy: brett.cannon, docs@python
priority: low
severity: normal
status: open
title: Document that datetime.__format__ is datetime.strftime
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue8913>
_______________________________________
New submission from Éric Araujo <merwok(a)netwok.org>:
Following a discussion on IRC:
<birkenfeld> I would even prefer having more of just `object` instead of :func:`object` or :class:`object`
I think it would be feasible to write a reST role that would use inspect or pydoc to find the type. It would not violate “In the face of ambiguity, refuse the temptation to guess” if it only resolves `somebuiltin` and `some.fully.qualified.name`.
Cons: People unfamiliar with reST might confuse ``code`` with `name`; interpreting the role may prove non-trivial (either requiring importing Python module to introspect them, or keeping a mapping of names→types in some file).
Thoughts?
----------
assignee: docs@python
components: Documentation
messages: 107790
nosy: docs@python, merwok
priority: normal
severity: normal
status: open
title: Add a default role to allow writing bare `len` instead of :func:`len`
type: feature request
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue8996>
_______________________________________