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 Marc-Andre Lemburg <mal(a)egenix.com>:
Mark Shannon on python-dev:
The following API functions were removed from 3.1.3:
PyAST_Compile
PyCObject_AsVoidPtr
PyCObject_FromVoidPtr
PyCObject_FromVoidPtrAndDesc
PyCObject_GetDesc
PyCObject_Import
PyCObject_SetVoidPtr
PyCode_CheckLineNumber
Py_CompileStringFlags
PyEval_CallObject
PyOS_ascii_atof
PyOS_ascii_formatd
PyOS_ascii_strtod
PyThread_exit_prog
PyThread__PyThread_exit_prog
PyThread__PyThread_exit_thread
PyUnicode_SetDefaultEncoding
And the following were added to 3.2,
of which only 2 are documented:
PyArg_ValidateKeywordArguments
PyAST_CompileEx
Py_CompileString
Py_CompileStringExFlags
PyErr_NewExceptionWithDoc (documented)
PyErr_SyntaxLocationEx
PyErr_WarnFormat
PyFrame_GetLineNumber
PyImport_ExecCodeModuleWithPathnames
PyImport_GetMagicTag
PyLong_AsLongLongAndOverflow (documented)
PyModule_GetFilenameObject
Py_SetPath
PyStructSequence_GetItem
PyStructSequence_NewType
PyStructSequence_SetItem
PySys_AddWarnOptionUnicode
PySys_AddXOption
PySys_FormatStderr
PySys_FormatStdout
PySys_GetXOptions
PyThread_acquire_lock_timed
PyType_FromSpec
PyUnicode_AsUnicodeCopy
PyUnicode_AsWideCharString
PyUnicode_EncodeFSDefault
PyUnicode_FSDecoder
Py_UNICODE_strcat
Py_UNICODE_strncmp
Py_UNICODE_strrchr
PyUnicode_TransformDecimalToASCII
For added confusion PySys_SetArgvEx is documented as
new in 3.2, but exists in 3.1.3
Note that this only include functions.
The API also includes a number of macros such as
Py_False and Py_RETURN_FALSE, types ,
and data like PyBool_Type.
----------
assignee: docs@python
components: Documentation
messages: 128294
nosy: docs@python, lemburg
priority: normal
severity: normal
status: open
title: Undocumented public APIs in Python 3.2
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue11173>
_______________________________________
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>
_______________________________________
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>
_______________________________________