[docs] Edits to descriptor howto (issue 17894)

ezio.melotti at gmail.com ezio.melotti at gmail.com
Sat May 4 20:18:05 CEST 2013


http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst
File Doc/howto/descriptor.rst (right):

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode39
Doc/howto/descriptor.rst:39: with ``a.__dict__['x']``, then
``type(a).__dict__['x']``, and continuing
This sentence seems too detailed to me, especially in the "Introduction"

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode43
Doc/howto/descriptor.rst:43: descriptor methods are defined.
This is like the original paragraph Ned suggested, the differences with
the original one are:
1) s/The default/Typical/
2) s/may override the default behavior and/will/

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode45
Doc/howto/descriptor.rst:45: Descriptors implements a powerful, general
purpose protocol.  They are also
Here I changed "are a" with "implements".

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode48
Doc/howto/descriptor.rst:48: new style classes introduced in version
2.2.  Descriptors simplify the
This sentence could be removed in the 3.x docs.

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode59
Doc/howto/descriptor.rst:59: .. method:: descr.__get__(self, obj,
type=None) -> value
Here I added .. method:: and indented the description, to make it more
readable.
I haven't changed the contents.

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode65
Doc/howto/descriptor.rst:65: it is passed `None` and the class. The
value it returns will be used as
This should be ``None``.

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode66
Doc/howto/descriptor.rst:66: the value of the attribute.
This would be better explained with an example IMHO, something like:
inst.attr -> attr.__get__(inst, type(inst))
cls.attr -> attr.__get__(None, cls)

This should be done for __set__ and __delete__ too.

http://bugs.python.org/review/17894/diff/8064/Doc/howto/descriptor.rst#newcode71
Doc/howto/descriptor.rst:71: It is passed the object and the value to
set.
I assume that like __get__, if it's called on a class attribute, None
and the class are passed instead.

http://bugs.python.org/review/17894/


More information about the docs mailing list