[Python-checkins] CVS: python/dist/src/Doc/lib libstdtypes.tex,1.47,1.48

[Barry Warsaw]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv10889/Doc/lib

Modified Files:
	libstdtypes.tex 
Log Message:
Document function attributes for both the function type and the method
type.  The method documentation also includes a new brief discussion
of `bound' vs. `unbound' and why setting an attr on a bound method is
a TypeError.  Includes Skip's suggested text.


Index: libstdtypes.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libstdtypes.tex,v
retrieving revision 1.47
retrieving revision 1.48
diff -C2 -r1.47 -r1.48
*** libstdtypes.tex	2001/01/09 22:47:46	1.47
--- libstdtypes.tex	2001/01/15 20:28:50	1.48
***************
*** 907,911 ****
--- 907,918 ----
  the function \var{f} was defined).
  
+ Function objects also support getting and setting arbitrary
+ attributes, which can be used to, e.g. attach metadata to functions.
+ Regular attribute dot-notation is used to get and set such
+ attributes. \emph{Note that the current implementation only supports
+ function attributes on functions written in Python.  Function
+ attributes on built-ins may be supported in the future.}
  
+ 
  \subsubsection{Methods \label{typesmethods}}
  \obindex{method}
***************
*** 923,926 ****
--- 930,964 ----
  calling \code{\var{m}.im_func(\var{m}.im_self, \var{arg-1},
  \var{arg-2}, \textrm{\ldots}, \var{arg-n})}.
+ 
+ Class instance methods are either \emph{bound} or \emph{unbound},
+ referring to whether the method was accessed through an instance or a
+ class, respectively.  When a method is unbound, its \code{im_self}
+ attribute will be \code{None} and if called, an explicit \code{self}
+ object must be passed as the first argument.  In this case,
+ \code{self} must be an instance of the unbound method's class (or a
+ subclass of that class), otherwise a \code{TypeError} is raised.
+ 
+ Like function objects, methods objects support getting and setting
+ arbitrary attributes.  However, the attributes are actually stored on
+ the underlying function object (i.e. \code{meth.im_func}).  To avoid
+ surprising behavior, a \code{TypeError} is raised when an attempt is
+ made to set an attribute on a bound method.  It is legal to get a
+ bound method's attribute (the underlying function's attribute is
+ returned), and it is also legal to set or get an unbound method's
+ attribute.  For example:
+ 
+ \begin{verbatim}
+ class C:
+     def method(self):
+         pass
+ 
+ c = C()
+ d = C()
+ c.meth.whoami = 'my name is c'
+ d.meth.whoami = 'my name is d'
+ \end{verbatim}
+ 
+ If bound method attribute setting was allowed, \code{c.meth.whoami}
+ would return ``my name is d''.
  
  See the \citetitle[../ref/ref.html]{Python Reference Manual} for more