[Zope3-checkins] CVS: Zope3/lib/python/Zope/Schema - README.stx:1.6

Holger Krekel hpk@devel.trillke.net
Thu, 5 Dec 2002 08:22:07 -0500


Update of /cvs-repository/Zope3/lib/python/Zope/Schema
In directory cvs.zope.org:/tmp/cvs-serv26158

Modified Files:
	README.stx 
Log Message:
extended the list of issue that need to be resolved and
thought about.




=== Zope3/lib/python/Zope/Schema/README.stx 1.5 => 1.6 ===
--- Zope3/lib/python/Zope/Schema/README.stx:1.5	Wed Dec  4 16:33:54 2002
+++ Zope3/lib/python/Zope/Schema/README.stx	Thu Dec  5 08:22:07 2002
@@ -2,37 +2,37 @@
 
 Table of contents
 
- Short introduction
+     Short introduction
 
- Long introduction
+     Long introduction
 
- What is a schema, how does it compare to an interface and why should you care?
+     What is a schema, how does it compare to an interface and why should you care?
 
- What does a Schema look like 
- 
- Where Schemas make sense: Providing views from Schemas 
- 
- Issues to be solved 
+     What does a Schema look like 
+     
+     Where Schemas make sense: Providing views from Schemas 
+     
+     Issues to be solved 
 
 
 Introduction
 
- Schemas extend the notion of interfaces to descriptions of Attributes rather than 
- methods.  Every Schema is an interface and specifies the public fields of an 
- object.  A "Field" roughly corresponds to an attribute of a python object. 
- But a Field provides space for a title and a description. It can also constrain
- its value and provide a validation method.  Besides you can optionally specify
- characteristics such as its value beeing readonly or not required. 
-
- Zope 3 schemas were born when Jim Fulton and Martijn Faassen thought about 
- Formulator for Zope3 and PropertySets while at the Zope3 sprint at the 
- Zope BBQ in Berlin. They realized that if you strip all view logic 
- from forms than you have something to interfaces. 
- And thus schemas were born.
+     Schemas extend the notion of interfaces to descriptions of Attributes rather than 
+     methods.  Every Schema is an interface and specifies the public fields of an 
+     object.  A "Field" roughly corresponds to an attribute of a python object. 
+     But a Field provides space for a title and a description. It can also constrain
+     its value and provide a validation method.  Besides you can optionally specify
+     characteristics such as its value beeing readonly or not required. 
+
+     Zope 3 schemas were born when Jim Fulton and Martijn Faassen thought about 
+     Formulator for Zope3 and PropertySets while at the Zope3 sprint at the 
+     Zope BBQ in Berlin. They realized that if you strip all view logic 
+     from forms than you have something to interfaces. 
+     And thus schemas were born.
 
 Dependencies
 
- The Schema package only depends on the Interface package. 
+    The Schema package only depends on the Interface package. 
 
 Simple Usage
 
@@ -56,37 +56,37 @@
 
 What is a schema, how does it compare to an interface?
 
-  A schema is an extended interface which defines Fields.  
-  You can validate that attributes of an object conform to their Fields 
-  defined on the schema.  With plain interfaces you can only validate 
-  that Methods conform to their interface specification.  
-
-  So interfaces and schemas refer to different aspects of an object 
-  (resp. its code and state). 
-
-  A Schema starts out like an interface but defines certain
-  Fields to which an object's attributes must conform to. Let's look at 
-  a stripped down example from the programmer's tutorial (chapter two)::
-
-      from Interface import Interface
-      from Zope.Schema import Interface, Text, TextLine
-
-      class IContact(Interface):
-         "Provides access to basic contact information."
-
-         first = TextLine(title=u"First name")
-         last = TextLine(title=u"Last name")
-         email = TextLine(title=u"Electronic mail address")
-         address = Text(title=u"Postal address")
-         postalCode = TextLine(title=u"Postal code",
+    A schema is an extended interface which defines Fields.  
+    You can validate that attributes of an object conform to their Fields 
+    defined on the schema.  With plain interfaces you can only validate 
+    that Methods conform to their interface specification.  
+
+    So interfaces and schemas refer to different aspects of an object 
+    (resp. its code and state). 
+
+    A Schema starts out like an interface but defines certain
+    Fields to which an object's attributes must conform to. Let's look at 
+    a stripped down example from the programmer's tutorial (chapter two)::
+
+    from Interface import Interface
+    from Zope.Schema import Interface, Text, TextLine
+
+    class IContact(Interface):
+        "Provides access to basic contact information."
+
+        first = TextLine(title=u"First name")
+        last = TextLine(title=u"Last name")
+        email = TextLine(title=u"Electronic mail address")
+        address = Text(title=u"Postal address")
+        postalCode = TextLine(title=u"Postal code",
                        constraint = re.compile("\d{5,5}(-\d{4,4})?$").match)
 
-  'TextLine' is a field and expresses that an attribute is a single line
-  of unicode text.  'Text' expresses an arbitrary unicode ("text") object. 
-  The most interesting part is the last attribute specification. It constrains
-  the 'postalCode' attribute to only have values that are US postal codes.
+    'TextLine' is a field and expresses that an attribute is a single line
+    of unicode text.  'Text' expresses an arbitrary unicode ("text") object. 
+    The most interesting part is the last attribute specification. It constrains
+    the 'postalCode' attribute to only have values that are US postal codes.
       
-  Now we want a class that aheres to the IContact Schema:
+    Now we want a class that aheres to the IContact Schema:
 
     class Contact(Persistence.Persistent):
         __implements__ = IContact
@@ -98,8 +98,8 @@
             self.address = address
             self.postalCode = pc
 
-  Now you can see if an instance of 'Contact' actually implements 
-  the schema:
+    Now you can see if an instance of 'Contact' actually implements 
+    the schema:
 
     from Zope.App.Schema import validateMapping
     someone = contact('Tim','Roberts', 'tim@roberts', '','')
@@ -108,32 +108,53 @@
      
 Issues to be solved
 
- These issues were written up at Rotterdam Sprint (12/4/2002). 
+    These issues were written up at Rotterdam Sprint (12/4/2002). 
  
  I18n 
  
-  How i18n interferes with Schemas is not thought out. In an non-english
-  context we probably want to have titles and descriptions easily 
-  translatable.  The best idea so far is to use an attribute name 
-  together with its surrounding namespace (Interface-name etc.) 
-  as the canonical unique id used for looking up translations. 
+    How i18n interferes with Schemas is not thought out. In an non-english
+    context we probably want to have titles and descriptions easily 
+    translatable.  The best idea so far is to use an attribute name 
+    together with its surrounding namespace (Interface-name etc.) 
+    as the canonical unique id used for looking up translations. 
 
-  Example:
-  
-  Class book(Interface):
+    Example:
   
-     author = ITextLine()
+    class book(Interface):
+        author = ITextLine()
      
-  And in view, while the widget or widget's messages are constructed:
+    To get to the And in view, while the widget or widget's messages are constructed:
   
-  TranslatorService.getMessage('book.author.title','DE_DE')   
+    TranslatorService.getMessage('book.author.title','DE_DE')   
 
+ Integration with Interfaces
+
+    How closely are Interfaces and Schema related?  Should they be refactored
+    into one package?  Currently the Interface package is outside the Zope
+    namespace and Schema is at Zope.Schema. Should this stay this way? Are
+    Schemas Zope-Specific? 
+
+    Shouldn't the 'implements' function on the interface package be
+    named setImplements as opposed to getImplements? This way if you write
+    
+      setImplements(klass, interface) 
+    
+    it is obvious what you mean (as opposed to implements(klass, interface)
+    which could mean *asking* if the klass implements the interface.
+
+ Clarify and clean up use cases
+
+    Some use cases are not easy to understand.  A lot of them look like 
+    features rather than use cases.  The list of schema use cases 
+    needs to be cleaned up and be (sometimes) more detailed.  
 
 References
 
+ Use case list, 
+   http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/Zope3SchemasUseCases
+
+ documented interfaces, Zope/Schema/IField.py 
  Jim Fulton's Programmers Tutorial, 
  in CVS Docs/ZopeComponentArchitecture/PythonProgrammerTutorial/Chapter2
-
-