[Python-checkins] python/dist/src/Doc/ref ref3.tex,1.99,1.100

[gvanrossum@users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/ref
In directory sc8-pr-cvs1:/tmp/cvs-serv20937

Modified Files:
	ref3.tex 
Log Message:
SF doc patch #692001, properties and __getattribute__.  I added some
stuff, and changed 'property' to 'descriptor'.


Index: ref3.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ref/ref3.tex,v
retrieving revision 1.99
retrieving revision 1.100
diff -C2 -d -r1.99 -r1.100
*** ref3.tex	31 Jan 2003 18:52:45 -0000	1.99
--- ref3.tex	28 Feb 2003 14:11:45 -0000	1.100
***************
*** 1156,1162 ****
  attribute access (use of, assignment to, or deletion of \code{x.name})
  for class instances.
- For performance reasons, these methods are cached in the class object
- at class definition time; therefore, they cannot be changed after the
- class definition is executed.
  
  \begin{methoddesc}[object]{__getattr__}{self, name}
--- 1156,1159 ----
***************
*** 1172,1179 ****
  This is done both for efficiency reasons and because otherwise
  \method{__setattr__()} would have no way to access other attributes of
! the instance.
! Note that at least for instance variables, you can fake
! total control by not inserting any values in the instance
! attribute dictionary (but instead inserting them in another object).
  \withsubitem{(object method)}{\ttindex{__setattr__()}}
  \end{methoddesc}
--- 1169,1177 ----
  This is done both for efficiency reasons and because otherwise
  \method{__setattr__()} would have no way to access other attributes of
! the instance.  Note that at least for instance variables, you can fake
! total control by not inserting any values in the instance attribute
! dictionary (but instead inserting them in another object).  See the
! \method{__getattribute__()} method below for a way to actually get
! total control in new-style classes.
  \withsubitem{(object method)}{\ttindex{__setattr__()}}
  \end{methoddesc}
***************
*** 1189,1193 ****
  would cause a recursive call to itself.  Instead, it should insert the
  value in the dictionary of instance attributes, e.g.,
! \samp{self.__dict__[\var{name}] = value}.
  \withsubitem{(instance attribute)}{\ttindex{__dict__}}
  \end{methoddesc}
--- 1187,1194 ----
  would cause a recursive call to itself.  Instead, it should insert the
  value in the dictionary of instance attributes, e.g.,
! \samp{self.__dict__[\var{name}] = value}.  For new-style classes,
! rather than accessing the instance dictionary, it should call the base
! class method with the same name, for example,
! \samp{object.__setattr__(self, name, value)}.
  \withsubitem{(instance attribute)}{\ttindex{__dict__}}
  \end{methoddesc}
***************
*** 1197,1200 ****
--- 1198,1246 ----
  assignment.  This should only be implemented if \samp{del
  obj.\var{name}} is meaningful for the object.
+ \end{methoddesc}
+ 
+ \subsubsection{More attribute access for new-style classes \lable{new-style-attribute-access}}
+ 
+ The following methods only apply to new-style classes.
+ 
+ \begin{methoddesc}[object]{__getattribute__}{self, name}
+ Called unconditionally to implement attribute accesses for instances
+ of the class. If the class also defines \method{__getattr__}, it will
+ never be called (unless called explicitly).
+ This method should return the (computed) attribute
+ value or raise an \exception{AttributeError} exception.
+ In order to avoid infinite recursion in this method, its
+ implementation should always call the base class method with the same
+ name to access any attributes it needs to access, for example,
+ \samp{object.__getattribute__(self, name)}.
+ \end{methoddesc}
+ 
+ \subsubsubsection{Implementing Descriptors \label{descriptors}}
+ 
+ The following methods only apply when an instance of the class
+ containing the method (a so-called \emph{descriptor} class) is in
+ the class dictionary of another new-style class, known as the
+ \emph{owner} class. In the examples below, ``the attribute'' refers to
+ the attribute whose name is the key of the property in the accessed
+ class' \code{__dict__}.
+ 
+ \begin{methoddesc}[object]{__get__}{self, instance, owner}
+ Called to get the attribute of the owner class (class attribute acess)
+ or of an instance of that class (instance attribute acces).
+ \var{owner} is always the owner class, while \var{instance} is the
+ instance that the attribute was accessed through, or \code{None} when
+ the attribute is accessed through the \var{owner}.  This method should
+ return the (computed) attribute value or raise an
+ \exception{AttributeError} exception.
+ \end{methoddesc}
+ 
+ \begin{methoddesc}[object]{__set__}{self, instance, value}
+ Called to set the attribute on an instance \{instance} of the owner
+ class to a new value, \var{value}.
+ \end{methoddesc}
+ 
+ \begin{methoddesc}[object]{__delete__}{self, instance}
+ Called to delete the attribute on an instance \{instance} of the owner
+ class.
  \end{methoddesc}