Mailman 3 June 2012 - docs

Re: [docs] [Tutor] special attributes naming confusion
by Dave June 6, 2012

June 6, 2012

I'm not sure where this comment belongs, but I want to share my perspective on the documentation of these special method names. In the following section there is an inconsistency which could be confusing to someone just learning Python (e.g., me). In the sentence on implementing custom mapping objects, the recommended method names are listed as the short calling names: eys(), values(), items(), etc. But, in contrast, in the sentence on implementing sequence types, the recommended method names are listed as the double underscore internal implementation names: __add__(), __radd__(), __iadd__(), __mul__(), etc. Here's the section of the documentation with this inconsistency. I think it would help to use one or the other of these pairs (calling name vs. internal implementation name) consistently in this section. 3.4.6. Emulating container types¶<http://docs.python.org/reference/datamodel.html#emulating-container-types> The following methods can be defined to implement container objects. Containers usually are sequences (such as lists or tuples) or mappings (like dictionaries), but can represent other containers as well. The first set of methods is used either to emulate a sequence or to emulate a mapping; the difference is that for a sequence, the allowable keys should be the integers *k* for which 0 <= k < N where *N* is the length of the sequence, or slice objects, which define a range of items. (For backwards compatibility, the method __getslice__()<http://docs.python.org/reference/datamodel.html#object.__getslice__>(see below) can also be defined to handle simple, but not extended slices.) It is also recommended that mappings provide the methods keys(), values(), items(), has_key(), get(), clear(), setdefault(), iterkeys(), itervalues(), iteritems(), pop(), popitem(), copy()<http://docs.python.org/library/copy.html#module-copy>, and update() behaving similar to those for Python’s standard dictionary objects. The UserDict<http://docs.python.org/library/userdict.html#module-UserDict>module provides a DictMixin class to help create those methods from a base set of __getitem__()<http://docs.python.org/reference/datamodel.html#object.__getitem__>, __setitem__()<http://docs.python.org/reference/datamodel.html#object.__setitem__>, __delitem__()<http://docs.python.org/reference/datamodel.html#object.__delitem__>, and keys(). Mutable sequences should provide methods append(), count(), index(), extend(), insert(), pop(), remove(), reverse() and sort(), like Python standard list objects. Finally, sequence types should implement addition (meaning concatenation) and multiplication (meaning repetition) by defining the methods __add__()<http://docs.python.org/reference/datamodel.html#object.__add__>, __radd__() <http://docs.python.org/reference/datamodel.html#object.__radd__>, __iadd__() <http://docs.python.org/reference/datamodel.html#object.__iadd__>, __mul__() <http://docs.python.org/reference/datamodel.html#object.__mul__>, __rmul__() <http://docs.python.org/reference/datamodel.html#object.__rmul__>and __imul__() <http://docs.python.org/reference/datamodel.html#object.__imul__>described below; they should not define __coerce__()<http://docs.python.org/reference/datamodel.html#object.__coerce__>or other numerical operators. It is recommended that both mappings and sequences implement the __contains__()<http://docs.python.org/reference/datamodel.html#object.__contains__>method to allow efficient use of the in operator; for mappings, in should be equivalent of has_key(); for sequences, it should search through the values. It is further recommended that both mappings and sequences implement the __iter__()<http://docs.python.org/reference/datamodel.html#object.__iter__>method to allow efficient iteration through the container; for mappings, __iter__() <http://docs.python.org/reference/datamodel.html#object.__iter__>should be the same as iterkeys(); for sequences, it should iterate through the values. This is in addition to some missing documentation regarding mention how some of the special method names should be conveniently called in code. (See below.) On Wed, Jun 6, 2012 at 3:59 PM, Dave <davestechshop(a)gmail.com> wrote: > > > On Wed, Jun 6, 2012 at 3:40 PM, Mark Lawrence <breamoreboy(a)yahoo.co.uk>wrote: > >> On 06/06/2012 20:19, Dave wrote: >> >>> I was reading some tutorial material on creating iterators. It shows the >>> following example implementation of an iterator: >>> >>> class Reverse: >>> """Iterator for looping over a sequence backwards.""" >>> def __init__(self, data): >>> self.data = data >>> self.index = len(data) >>> def __iter__(self): >>> return self >>> def next(self): >>> if self.index == 0: >>> raise StopIteration >>> self.index = self.index - 1 >>> return self.data[self.index] >>> >>> >>> My question is how was I supposed to kinow that the function I call using >>> the name iter() is implemented using the name __iter__()? >>> >>> Is there a rule that describes when I would implement an attribute name >>> with leading and trailing double underscores, and then call it without >>> those underscores? How many names like this exist in Python? Are these >>> special cases or is there a general rule that leading and trailing double >>> underscores get dropped when calling functions that were implemented with >>> these names? I'm trying to understand the big picture as far as how >>> Python >>> works when it comes to this situation. Thanks. >>> >>> >> Try this to start with http://docs.python.org/**reference/datamodel.html# >> **special-method-names<http://docs.python.org/reference/datamodel.html#special-method-names>. >> Note this is for Python 2.7.3, there may be differences in Python 3.x. >> >> -- >> > > Actually, I think I'm getting it now... as I read more of this page I see > that there is no single generalization. These are indeed all special cases. > > But the documentation does appear to be incomplete. It leaves out the > mapping to the name or symbol that should be used to call the special > function in some cases. In particular, in the case of __iter(self), which > is one of the first ones I looked at, it doesn't mention that this is > usually called via iter(). It does mention how it would be called for > mapping containers, however (i.e., iterkeys()). > object.__iter__(*self*) > > This method is called when an iterator is required for a container. This > method should return a new iterator object that can iterate over all the > objects in the container. For mappings, it should iterate over the keys of > the container, and should also be made available as the method iterkeys(). > > But as I read more, I see that much of the documentation does mention how > these special method names are called. For example: > > object.__lt__(*self*, *other*) object.__le__(*self*, *other*)¶<http://docs.python.org/reference/datamodel.html#object.__le__> > object.__eq__(*self*, *other*) object.__ne__(*self*, *other*) object. > __gt__(*self*, *other*) object.__ge__(*self*, *other*) > > New in version 2.1. > > These are the so-called “rich comparison” methods, and are called for > comparison operators in preference to __cmp__()<http://docs.python.org/reference/datamodel.html#object.__cmp__>below. The correspondence between operator symbols and method names is as > follows: x<y calls x.__lt__(y), x<=y calls x.__le__(y), x==y calls > x.__eq__(y), x!=y and x<>y call x.__ne__(y), x>y calls x.__gt__(y), and > x>=y calls x.__ge__(y). > I think there is enough info at this page to answer my question as well as > I need it answered right now. Thanks. >

2 1

[issue9544] xdrlib.Packer().pack_fstring throws a TypeError when called with a str()
by Petri Lehtinen June 6, 2012

June 6, 2012

Changes by Petri Lehtinen <petri(a)digip.org>: Added file: http://bugs.python.org/file25849/issue9544.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9544> _______________________________________

1 0

[issue9544] xdrlib.Packer().pack_fstring throws a TypeError when called with a str()
by Petri Lehtinen June 6, 2012

June 6, 2012

Petri Lehtinen <petri(a)digip.org> added the comment: Attached a patch against 3.2. It reflects the facts that pack_fstring and pack_fopaque are the same methd, and pack_string, pack_opaque and pack_bytes are the same method. ---------- versions: +Python 3.2, Python 3.3 -Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9544> _______________________________________

1 0

document return statement in finally blocks (issue 14167)
by pybugs＠rebertia.com June 4, 2012

June 4, 2012

http://bugs.python.org/review/14167/diff/4310/Doc/reference/compound_stmts.… File Doc/reference/compound_stmts.rst (right): http://bugs.python.org/review/14167/diff/4310/Doc/reference/compound_stmts.… Doc/reference/compound_stmts.rst:311: it is re-raised at the end of the :keyword:`finally` clause. If the `break` statements aren't (re-)"raised" [per se] since they aren't exceptions, so some rephrasing is needed here. http://bugs.python.org/review/14167/diff/4310/Doc/reference/compound_stmts.… Doc/reference/compound_stmts.rst:312: :keyword:`finally` clause raises another exception the saved exception Could use a comma: "another exception*,* the" http://bugs.python.org/review/14167/

1 0

issues with installing and importing rdflib and rdfextras in python and eclipse pydev
by ayodele akingbulu June 4, 2012

June 4, 2012

Hi, I have issues with the installation of rdflib and rdfextras packages on windows for python 3.2.3. I cannot find anywhere in the document detailing how to install this packages and succesfully import them in a python program. not to talk less of accessing it on eclipse indigo. Kindly help to look into this issue as it might be a bug. Regards, Ayo

1 0

proposal: sigle-file TXT format documentation
by Alexey Kosarev June 3, 2012

June 3, 2012

Hi! I strongly propose to introduce single-file TXT documentation. Current plain text documentation is totally navigable, but it's not conveniet to use it on any reading device or search through it using less + grep. Hope you could consider creating a single-file TXT documentation. Thank you!

2 1

Control flow - explanation
by Kennedy Greg - grkenn June 3, 2012

June 3, 2012

Going through the tutorial for programmers, I noticed an area which might benefit from some improvement. http://docs.python.org/tutorial/controlflow.html Code snippet in section 4.4 is followed up by this: "(Yes, this is the correct code. Look closely: the else clause belongs to the for<http://docs.python.org/reference/compound_stmts.html#for> loop, not the if<http://docs.python.org/reference/compound_stmts.html#if> statement.)" -- That's hardly explanatory: if you are unfamiliar with the use of whitespace to designate blocks (say, coming from a language where {} braces normally accomplish the task), then this won't make any sense. This seems as good a place as any to begin addressing the "white space as a control structure" aspect of Python, perhaps with a demonstration that adding tabs to the Else: block will result in incorrect behavior. I don't recall seeing this being mentioned earlier in the tutorial, yet it's an important defining aspect of the grammar. *************************************************************************** The information contained in this communication is confidential, is intended only for the use of the recipient named above, and may be legally privileged. If the reader of this message is not the intended recipient, you are hereby notified that any dissemination, distribution or copying of this communication is strictly prohibited. If you have received this communication in error, please resend this communication to the sender and delete the original message or any copy of it from your computer system. Thank You. ****************************************************************************

2 1

[issue14424] document PyType_GenericAlloc
by Eli Bendersky June 3, 2012

June 3, 2012

New submission from Eli Bendersky <eliben(a)gmail.com>: PyType_GenericAlloc is not documented in http://docs.python.org/dev/c-api/type.html ---------- assignee: docs@python components: Documentation keywords: easy messages: 156917 nosy: docs@python, eli.bendersky priority: low severity: normal status: open title: document PyType_GenericAlloc type: behavior versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14424> _______________________________________

2 3

Glossary mistake
by Gaston Fiore June 2, 2012

June 2, 2012

Hello, In the glossary, in the definition of "file object", there's an extra word "other" in the second sentence of the definition. It currently reads: "Depending on the way it was created, a file object can mediate access to a real on-disk file or to another other type of storage or communication device (for example standard input/output, in-memory buffers, sockets, pipes, etc.)." It should instead read: "Depending on the way it was created, a file object can mediate access to a real on-disk file or to another type of storage or communication device (for example standard input/output, in-memory buffers, sockets, pipes, etc.)." Best, -Gaston

2 1

[issue14971] (unittest) loadTestsFromName does not work on method with a decorator
by R. David Murray June 2, 2012

June 2, 2012

R. David Murray <rdmurray(a)bitdance.com> added the comment: Here's a patch. ---------- components: +Library (Lib) -Documentation keywords: +patch Added file: http://bugs.python.org/file25803/unittest_method_name_difference.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14971> _______________________________________

1 0