[Python-checkins] CVS: python/nondist/peps pep-0252.txt,1.4,1.5

[Guido van Rossum]

Update of /cvsroot/python/python/nondist/peps
In directory usw-pr-cvs1:/tmp/cvs-serv5011

Modified Files:
	pep-0252.txt 
Log Message:
Added attribute descriptor API.

Still need to do the signature object API.


Index: pep-0252.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0252.txt,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -r1.4 -r1.5
*** pep-0252.txt	2001/04/23 16:35:33	1.4
--- pep-0252.txt	2001/04/23 21:19:03	1.5
***************
*** 25,28 ****
--- 25,29 ----
      generalized attribute represented by getter and setter functions.
  
+ 
  Introduction
  
***************
*** 40,43 ****
--- 41,45 ----
      are not on the table for this PEP.
  
+ 
  Introspection APIs
  
***************
*** 116,119 ****
--- 118,122 ----
      docstring extraction isn't feasible in this case.)
  
+ 
  Specification of the class-based introspection API
  
***************
*** 274,278 ****
--- 277,372 ----
      and classes support assignment to __bases__ and __dict__.)
  
+ 
  Specification of the attribute descriptor API
+ 
+     Attribute descriptors have the following attributes.  In the
+     examples, x is an object, C is x.__class__, x.meth() is a method,
+     and x.ivar is a data attribute or instance variable.
+ 
+     - name: the original attribute name.  Note that because of
+       aliasing and renaming, the attribute may be known under a
+       different name, but this is the name under which it was born.
+       Example: C.meth.name == 'meth'.
+ 
+     - doc: the attribute's documentation string.
+ 
+     - objclass: the class that declared this attribute.  The
+       descriptor only applies to objects that are instances of this
+       class (this includes instances of its subclasses).  Example:
+       C.meth.objclass is C.
+ 
+     - kind: either "method" or "data".  This distinguishes between
+       methods and data attributes.  The primary operation on a method
+       attribute is to call it.  The primary operations on a data
+       attribute are to get and to set it.  Example: C.meth.kind ==
+       'method'; C.ivar.kind == 'data'.
+ 
+     - default: for optional data attributes, this gives a default or
+       initial value.  XXX Python has two kinds of semantics for
+       referencing "absent" attributes: this may raise an
+       AttributeError, or it may produce a default value stored
+       somewhere in the class.  There could be a flag that
+       distinguishes between these two cases.  Also, there could be a
+       flag that tells whether it's OK to delete an attribute (and what
+       happens then -- a default value takes its place, or it's truly
+       gone).
+ 
+     - attrclass: for data attributes, this can be the class of the
+       attribute value, or None.  If this is not None, the attribute
+       value is restricted to being an instance of this class (or of a
+       subclass thereof).  If this is None, the attribute value is not
+       constrained.  For method attributes, this should normally be
+       None (a class is not sufficient information to describe a method
+       signature).  If and when optional static typing is added to
+       Python, this the meaning of this attribute may change to
+       describe the type of the attribute.
+ 
+     - signature: for methods, an object that describes the signature
+       of the method.  Signature objects will be described further
+       below.
+ 
+     - readonly: Boolean indicating whether assignment to this
+       attribute is disallowed.  This is usually true for methods.
+       Example: C.meth.readonly == 1; C.ivar.kind == 0.
+ 
+     - get(): a function of one argument that retrieves the attribute
+       value from an object.  Examples: C.ivar.get(x) ~~ x.ivar;
+       C.meth.get(x) ~~ x.meth.
+ 
+     - set(): a function of two arguments that sets the attribute value
+       on the object.  If readonly is set, this method raises a
+       TypeError exception.  Example: C.ivar.set(x, y) ~~ x.ivar = y.
+ 
+     - call(): for method descriptors, this is a function of at least
+       one argument that calls the method.  The first argument is the
+       object whose method is called; the remaining arguments
+       (including keyword arguments) are passed on to the method.
+       Example: C.meth.call(x, 1, 2) ~~ x.meth(1, 2).
+ 
+     - bind(): for method descriptiors, this is a function of one
+       argument that returns a "bound method object".  This in turn can
+       be called exactly like the method should be called (in fact this
+       is what is returned for a bound method).  This is the same as
+       get().  Example: C.meth.bind(x) ~~ x.meth.
+ 
+     For convenience, __name__ and __doc__ are defined as aliases for
+     name and doc.  Also for convenience, calling the descriptor can do
+     one of three things:
+ 
+     - Calling a method descriptor is the same as calling its call()
+       method.  Example: C.meth(x, 1, 2) ~~ x.meth(1, 2).
+ 
+     - Calling a data descriptor with one argument is the same as
+       calling its get() method.  Example: C.ivar(x) ~~ x.ivar.
+ 
+     - Calling a data descriptor with two arguments is the same as
+       calling its set() method.  Example: C.ivar(x, y) ~~ x.ivar = y.
+ 
+     Note that this specification does not define how to create
+     specific attribute descriptors.  This is up to the individual
+     attribute descriptor implementations, of which there may be many.
+ 
+ 
+ Specification of the signature object API
  
      XXX