[Zope3-checkins] CVS: Zope3/src/zope/app - context.txt:1.6

[Steve Alexander]

Update of /cvs-repository/Zope3/src/zope/app
In directory cvs.zope.org:/tmp/cvs-serv18902

Modified Files:
	context.txt 
Log Message:
Removed description of problems with ContextAware.
Replaced it with a description of ContextAwareDescriptors() class advice.


=== Zope3/src/zope/app/context.txt 1.5 => 1.6 ===
--- Zope3/src/zope/app/context.txt:1.5	Fri Jun  6 11:45:02 2003
+++ Zope3/src/zope/app/context.txt	Sat Jun 14 09:11:04 2003
@@ -210,7 +210,7 @@
       proxies" always go on the outside?
 
       + I think this has to do with how intrinsic something is.
-        
+
         A descriptor from a class implementation should have full
         access to the implementation.  If adapters could be registered
         for classes, rather than interfaces, then the adapter could
@@ -243,38 +243,41 @@
     If it is made possible to do this, adapters registered for classes would
     always trump those registered for interfaces.
 
-* ContextAware mix-in considered harmful
-
-  ContextAware is a marker mix-in class that causes all descriptors
-  for instances of the class to be implicitly rebound to context
-  wrappers if they are accessed through context wrappers. These
-  descriptors include descriptors not defined in the class statement,
-  such as inherited descriptors and descriptors set by interface
-  declarations. 
+* ContextAwareDescriptors class advice
 
-  This implicit behavior has a high potential to break the
-  expectations of descrioptors set in the class statement.
+  You can make all descriptors defined in a particular class into
+  context-aware descriptors by using the ContextAwareDescriptors() function
+  within the class suite. For example::
 
-  Note that it would not be so evil to have a way to say that all of
-  the descriptors defined in a class statement are context
-  descriptoes, since that is still explicit.  For example::
+      class FooBaseClass:
+          def m0(self, ...)
 
-     class Foo(A, B):
+      class Foo(FooBaseClass):
+          ContextAwareDescriptors()
+          implements(IFoo)
 
-        ContextAware()
+          def m1(self, ...): ...
 
-        implements(IFoo)
+          def m2(self, ...): ...
 
-        def m1(self, ...): ...
+          ...
 
-        def m2(self, ...): ...
+          p = property(_getP, _setP)
 
-        ...
+  In this case, all of the methods defined in Foo, such as m1, m2, and
+  we assume _getP and _setP, will be made into the equivalent of
+  ContextMethods.
+  Properties such as p will be made into the equivalent of ContextProperties.
+  However, m0, inherited from FooBaseClass, will remain a normal
+  instance method.
 
-  would assert that m1, m2, etc are context methods but would not
-  affect descriptors provided by A and B. 
+  If a ContextMethod or other ContextDescriptor is used in Foo, then
+  it will be left exactly as it is.
 
-  The way to achieve this is with the __metaclass__ advice hack.
+  The ContextAwareDescriptors class advice is better than using a marker
+  base-class because with the class advice, you always will be able to see
+  that the descriptors of a class will be made context-aware.
+  With the base-class approach, descriptors could be unpredictably converted
+  into context-aware descriptors through deriving new classes.
+  Such unpredictability and implicitness is bad.
 
-  Actually, I *think* the ContextAware mixin could be fixed with a suitably
-  tricky meta class.