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 Ian <ifreecarve(a)gmail.com>:
Concerning this section of the docs:
http://docs.python.org/library/functions.html#staticmethod
There is no example for calling a static method from another static method within the same class.
As I discovered later, it's simple: C.f() -- from inside the class or outside it.
A total newbie will accept this and move on... but in other programming languages, it's frowned upon to the class name from within the class. For example, in PHP you use the "self::" prefix and Java you don't need a prefix at all.
So, even though I had it right the first time, it didn't SEEM right... so I went on a wild goose chase, for nothing. Googling "java call static method" will get you java documentation that lists both cases, as does "c++ call static method" and "php call static method".
I feel that by adding "Note: you must also use the C.f() syntax when calling from within the class", the documentation will be more complete.
----------
assignee: docs@python
components: Documentation
messages: 121314
nosy: docs@python, ifreecarve
priority: normal
severity: normal
status: open
title: list an example for calling static methods from WITHIN classes
type: feature request
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue10438>
_______________________________________
New submission from Humberto Diogenes <humberto(a)digi.com.br>:
On some systems, datetime.strftime() accepts a %s format string that returns epoch / UNIX timestamp, but this behavior is not documented at http://docs.python.org/library/datetime.html
Python 2.7 (r27:82508, Jul 3 2010, 21:12:11)
[GCC 4.0.1 (Apple Inc. build 5493)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import datetime
>>> datetime.datetime.now().strftime('%s')
'1295376929'
----------
assignee: docs@python
components: Documentation
messages: 126481
nosy: docs@python, hdiogenes
priority: normal
severity: normal
status: open
title: Undocumented option for datetime.strftime: %s
versions: Python 2.7
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue10938>
_______________________________________
New submission from Justin Lebar <justin.lebar(a)gmail.com>:
The readline documentation currently says:
> readline.insert_text(string)
> Insert text into the command line.
But as far as I can tell, readline.insert_text() does something only when called from startup_hook or pre_input_hook.
Here's an example of someone using the module in a way that works:
http://swapoff.org/svn/cly/tags/0.7/cly/interactive.py
----------
assignee: docs@python
components: Documentation
messages: 121178
nosy: Justin.Lebar, docs@python
priority: normal
severity: normal
status: open
title: readline.insert_text documentation incomplete
versions: Python 3.1
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue10415>
_______________________________________
New submission from DSM <dsm001(a)users.sourceforge.net>:
Various typo fixes for the docs. As usual, I left historical documents alone (except for 3.1 whatsnew: fixed the spelling of Jack Diederich's name). Fixing ~30 means I probably introduced ~3 problems of my own, but that should still be a net win..
Patch against py3k r84944.
----------
assignee: docs@python
components: Documentation
files: typos.patch
keywords: patch
messages: 117052
nosy: docs@python, dsm001
priority: normal
severity: normal
status: open
title: doc copyedits
versions: Python 3.3
Added file: http://bugs.python.org/file18947/typos.patch
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9911>
_______________________________________
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 Éric Araujo <merwok(a)netwok.org>:
At the top of Doc/library/functions.rst, which documents built-in functions like abs, getattr or hash, a comment reads “document all delegations to __special__ methods”.
Some functions are already good: enumerate for instance does link to the definition of iterator and hints about the __next__ method, format points to __format__, etc. They can serve as example for how to add links (in plain text and in the global index).
----------
assignee: docs@python
components: Documentation
messages: 120189
nosy: docs@python, eric.araujo
priority: normal
severity: normal
stage: needs patch
status: open
title: Document magic methods called by built-in functions
versions: Python 2.7, Python 3.1, Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue10289>
_______________________________________
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 J_Tom_Moon_79 <jtm.moon.forum.user+python(a)gmail.com>:
method xml.etree.ElementTree.tostring from module returns type bytes.
The documentation reads
"""Returns an encoded string containing the XML data."""
(from http://docs.python.org/py3k/library/xml.etree.elementtree.html#xml.etree.El… as of 2011-01-18)
=======================================================
Here is a test program:
-------------------------------------------------------
#!/usr/bin/python
# created for python 3.1
import sys
print(sys.version) # for help verifying version tested
from xml.etree import ElementTree
sampleinput = """<?xml version="1.0"?><Hello></Hello>"""
xmlobj = ElementTree.fromstring(sampleinput)
type(xmlobj)
xmlstr = ElementTree.tostring(xmlobj,'utf-8')
print("xmlstr value is '", xmlstr, "'", sep="")
print("xmlstr type is '", type(xmlstr), "'", sep="")
-------------------------------------------------------
test program output:
-------------------------------------------------------
3.1.3 (r313:86834, Nov 27 2010, 18:30:53) [MSC v.1500 32 bit (Intel)]
xmlstr value is 'b'<Hello />''
xmlstr type is '<class 'bytes'>'
=======================================================
This cheap "fix" for this bug may be simply be a change in documentation.
However, a method called "tostring" really should return something nearer to the built-in str.
----------
assignee: docs@python
components: Documentation, XML
messages: 126506
nosy: JTMoon79, docs@python
priority: normal
severity: normal
status: open
title: xml.etree.ElementTree.tostring returns type bytes, expected type str
type: behavior
versions: Python 3.1
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue10942>
_______________________________________