classification
Title: Descriptors howto
Type: enhancement Stage:
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: works for me
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, ezio.melotti, marco.buttu, rhettinger
Priority: low Keywords: patch

Created on 2013-09-19 17:26 by marco.buttu, last changed 2013-09-21 19:58 by marco.buttu. This issue is now closed.

Files
File name Uploaded Description Edit
py3howto.patch marco.buttu, 2013-09-21 10:44
py3full.patch marco.buttu, 2013-09-21 14:29
Messages (10)
msg198096 - (view) Author: Marco Buttu (marco.buttu) * Date: 2013-09-19 17:26
I think in the descriptor howto, at this point:

>>> class MyClass(object):
    x = RevealAccess(10, 'var "x"')
    y = 5

or the prompt should not have been, or there is a wrong indentation.
Furthermore, in Python 3:

http://docs.python.org/3/howto/descriptor.html

we can remove the explicit derivation from `object`
msg198182 - (view) Author: Marco Buttu (marco.buttu) * Date: 2013-09-21 02:24
Maybe is better to underline the difference between classes and non-classes objects, instead of between objects and classes, because a class is an object, so it could be confusing). 
Raymond, what do you think about rewriting this sentence:

  `The details of invocation depend on whether obj is an object or a class.`

as:

  `The details of invocation depend on whether obj is a class or not.`

I upload two new patches (one for py2 and the other for py3)
msg198183 - (view) Author: Marco Buttu (marco.buttu) * Date: 2013-09-21 03:22
I saw right now your decision about keeping object in the Python 3 doc:

http://bugs.python.org/issue17351#msg183870

So, now the py3 patch takes in account just the indentation of the `RevealAccess` example and the "class or not" suggestion.
msg198184 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013-09-21 06:45
The indentation is not incorrect.  What you're seeing is normal for the interactive prompt.

Also, it is not incorrect to inherit from object in Python 3.
There is some value in keeping the document the same between versions.
msg198191 - (view) Author: Marco Buttu (marco.buttu) * Date: 2013-09-21 10:44
I think the indentation is a problem, for several reasons. In all the examples in the documentation, the form by using the interactive shell is the following:

    >>> class MyClass:
    ...     pass

otherwise:

    class MyClass:
        pass

This one is awful:

>>> class MyClass:
    pass

and in fact it is no used in the doc. So if you want to put the class clause in the interactive shell, you have to add the dots to indent the suite of the compound statement, in order to be consistent with the rest of all the documentation.
But it is not just a problem of beauty:

$ python -m doctest descriptor.rst 
**********************************************************************
File "descriptor.rst", line 165, in descriptor.rst
Failed example:
    class MyClass(object):
Exception raised:
    ...
        class MyClass(object):
                             ^
    SyntaxError: unexpected EOF while parsing
...

By applying the patch, the definitions of the classes RevealAccess and MyClass pass the documentation test. The whole example does not pass in any case, because you are not consistent using the shell notation.
msg198198 - (view) Author: Marco Buttu (marco.buttu) * Date: 2013-09-21 13:03
By looking at the other examples in the howto, I saw there is the same problem in all the definitions in the prompt, and furthermore, we are using a different number of spaces to indent MyClass respect the rest of the classes defined in the prompt. 
There is also a wrong indentation in the StaticMethod definition (no prompt definition):

class StaticMethod(object):
 "Emulate PyStaticMethod_Type() in Objects/funcobject.c"

 def __init__(self, f):
      self.f = f

 def __get__(self, obj, objtype=None):
      return self.f

Applying the py3full.patch, the howto passes all the documentation tests:

$ python -m doctest descriptor.rst | tail -n 1
***Test Failed*** 18 failures.
$ python -m doctest descriptor_modified.rst | tail -n 1
$


My 2 cents
msg198200 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-09-21 13:38
In the latest patch there are 5-spaces indents in several places.
msg198205 - (view) Author: Marco Buttu (marco.buttu) * Date: 2013-09-21 14:29
You are right. Now it should be ok
msg198207 - (view) Author: Marco Buttu (marco.buttu) * Date: 2013-09-21 14:39
By the way, it does not pass all the tests in Python 2.7:

$ python2.7 -m doctest descriptor_modified.rst | tail -n 1
***Test Failed*** 3 failures.

If we want to be very rigorous, in order to pass the tests in Py2.7 too (kipping the rst aligned between py2 and py3), we have to add 3 others doctest: +SKIP directives. 

PS. I think there is a small bug in sphinx, related to our examples:

https://bitbucket.org/birkenfeld/sphinx/issue/1271/doctest-directive-and-dots-not-hidden
msg198223 - (view) Author: Marco Buttu (marco.buttu) * Date: 2013-09-21 19:58
$ python -c "import this" | grep "silently"
Errors should never pass silently
History
Date User Action Args
2013-09-21 19:58:31marco.buttusetmessages: + msg198223
2013-09-21 17:36:50rhettingersetstatus: open -> closed
2013-09-21 14:39:14marco.buttusetmessages: + msg198207
2013-09-21 14:29:10marco.buttusetfiles: + py3full.patch

messages: + msg198205
2013-09-21 14:28:42marco.buttusetfiles: - py3full.patch
2013-09-21 13:38:39ezio.melottisetnosy: + ezio.melotti
messages: + msg198200
2013-09-21 13:03:31marco.buttusetfiles: + py3full.patch

messages: + msg198198
2013-09-21 10:47:31marco.buttusetstatus: closed -> open
resolution: not a bug -> works for me
2013-09-21 10:44:53marco.buttusetfiles: - py3howto.patch
2013-09-21 10:44:46marco.buttusetfiles: - py2howto.patch
2013-09-21 10:44:26marco.buttusetfiles: + py3howto.patch

messages: + msg198191
2013-09-21 06:45:46rhettingersetstatus: open -> closed
resolution: not a bug
messages: + msg198184
2013-09-21 06:32:38rhettingersetpriority: normal -> low
assignee: docs@python -> rhettinger
2013-09-21 03:22:29marco.buttusetfiles: + py3howto.patch

messages: + msg198183
2013-09-21 03:19:15marco.buttusetfiles: - py3howto.patch
2013-09-21 03:04:59marco.buttusetfiles: + py2howto.patch
2013-09-21 03:04:45marco.buttusetfiles: - py2howto.patch
2013-09-21 02:24:49marco.buttusetfiles: + py2howto.patch
2013-09-21 02:24:31marco.buttusetfiles: + py3howto.patch

messages: + msg198182
2013-09-21 02:18:05marco.buttusetfiles: - py2howto.patch
2013-09-21 02:17:58marco.buttusetfiles: - py3howto.patch
2013-09-20 00:51:04ned.deilysetnosy: + rhettinger

versions: - Python 2.6, Python 3.1, Python 3.2
2013-09-19 17:43:14marco.buttusetfiles: + py2howto.patch
2013-09-19 17:42:55marco.buttusetfiles: + py3howto.patch
keywords: + patch
2013-09-19 17:26:26marco.buttucreate