improve schemas chapter

Author: MrTango

docs/backend/schemas.md

@@ -19,12 +19,13 @@ substitutions:
 ## Introduction
 
 [Zope schemas](https://zopeschema.readthedocs.io) are a database-neutral and form-library-neutral way to
-describe Python data models.
+describe Python data models. Schemas extend the notion of interfaces to detailed descriptions of Attributes (but not 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 at least 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 being read-only or not required.
 
 Plone uses Zope schemas for these purposes:
 
 - to describe persistent data models;
 - to describe HTML form data;
+- to describe Plone configuration data
 - to describe ZCML configuration data.
 
 Since Zope schemas are not bound to e.g. a SQL database engine, it gives
@@ -102,95 +103,19 @@ class ICheckoutAddress(zope.interface.Interface):
 
 This schema can be used in {ref}`classic-ui-forms-label` and Dexterity {ref}`backend-content-types-label` data models.
 
-
-## Advanced
-
-We can use this class to store data based on our model definition in the ZODB
-database.
-
-We use `zope.schema.fieldproperty.FieldProperty` to bind
-persistent class attributes to the data definition.
-
-Example:
-
-```
-from persistent import Persistent # Automagical ZODB persistent object
-from zope.schema.fieldproperty import FieldProperty
-
-class CheckoutAddress(Persistent):
-    """ Store checkout address """
-
-    # Declare that all instances of this class will
-    # conform to the ICheckoutAddress data model:
-    zope.interface.implements(ICheckoutAddress)
-
-    # Provide the fields:
-    first_name = FieldProperty(ICheckoutAddress["first_name"])
-    last_name = FieldProperty(ICheckoutAddress["last_name"])
-    organization = FieldProperty(ICheckoutAddress["organization"])
-    phone = FieldProperty(ICheckoutAddress["phone"])
-    country =  FieldProperty(ICheckoutAddress["country"])
-    state = FieldProperty(ICheckoutAddress["state"])
-    city = FieldProperty(ICheckoutAddress["phone"])
-    postal_code = FieldProperty(ICheckoutAddress["postal_code"])
-    street_address = FieldProperty(ICheckoutAddress["street_address"])
-```
-
-For persistent objects, see {doc}`persistent object documentation
-</develop/plone/persistency/persistent>`.
-
-
-### More info
-
-- [zope.schema](https://pypi.python.org/pypi/zope.schema) on PyPi
-- [zope.schema source code](http://github.com/zopefoundation/zope.schema) - definite source for field types and usage.
-- [zope.schema documentation](https://zopeschema.readthedocs.io)
-- [plone.schema](https://github.com/plone/plone.schema)
-
-`zope.schema` and `plone.schema` provide a very comprehensive set of {ref}`backend-fields-label` out of the box.
-Finding good documentation for them, however, can be challenging.  Here are
-some starting points:
-
-- {ref}`reference list of fields used in Plone <backend-fields-label>`
-
-
-## Using schemas as data models
-
-Based on the example data model above, we can use it in e.g. content type
-{doc}`browser views </develop/plone/views/browserviews>` to store arbitrary data as content
-type attributes.
-
-Example:
-
+```{note}
+In Dexterity {ref}`backend-content-types-label` the base class for a schema is `plone.supermodel.model.Schema`.
+This provides functionalities to export and import schemas via XML and TTW editor.
 ```
-class MyView(BrowserView):
-    """ Connect this view to your content type using a ZCML declaration.
-    """
-
-    def __call__(self):
-        # Get the content item which this view was invoked on:
-        context = self.context.aq_inner
-
-        # Store a new address in it as the ``test_address`` attribute
-        context.test_address = CheckoutAddress()
-        context.test_address.first_name = u"Mikko"
-        context.test_address.last_name = u"Ohtamaa"
 
-        # Note that you can still add arbitrary attributes to any
-        # persistent object.  They are simply not validated, as they
-        # don't go through the ``zope.schema`` FieldProperty
-        # declarations.
-        # Do not do this, you will regret it later.
-        context.test_address.arbitary_attribute = u"Don't do this!"
-```
 
-## Field constructor parameters
+### Field constructor parameters
 
 The `Field` base class defines a list of standard parameters that you can
 use to construct schema fields.  Each subclass of `Field` will have its own
 set of possible parameters in addition to this.
 
-See the full list [here](http://docs.zope.org/zope3/Code/zope/schema/_bootstrapfields/Field/index.html).
+See [IField interface](https://zopeschema.readthedocs.io/en/latest/api.html#zope.schema.interfaces.IField) and [field implementation](https://zopeschema.readthedocs.io/en/latest/api.html#field-implementations) in `zope.schema` documentation for details.
 
 Title
 
@@ -220,9 +145,12 @@ is probably not what you intend. Instead, initialize objects in the
 
 In particular, dangerous defaults are: `default=[]`, `default={}`,
 `default=SomeObject()`.
+
+Use `defaultFactory=get_default_name` instead!
 ```
 
-## Schema introspection
+
+### Schema introspection
 
 The `zope.schema._schema` module provides some introspection functions:
 
@@ -247,7 +175,7 @@ class IMyInterface(zope.interface.Interface):
 fields = zope.schema.getFields(IMyInterface)
 ```
 
-### Dumping schema data
+#### Dumping schema data
 
 Below is an example how to extract all schema defined fields from an object.
 
@@ -276,7 +204,7 @@ def dump_schemed_data(obj):
     return out
 ```
 
-### Finding the schema for a Dexterity type
+#### Finding the schema for a Dexterity type
 
 When trying to introspect a Dexterity type, you can get a reference to the schema thus:
 
@@ -291,13 +219,95 @@ schema = getUtility(IDexterityFTI, name=PORTAL_TYPE_NAME).lookupSchema()
 fields added to it at this stage, only the fields directly defined in your
 schema.
 
-## Field order
+
+### More info
+
+- [zope.schema](https://pypi.python.org/pypi/zope.schema) on PyPi
+- [zope.schema source code](http://github.com/zopefoundation/zope.schema) - definite source for field types and usage.
+- [zope.schema documentation](https://zopeschema.readthedocs.io)
+- [plone.schema](https://github.com/plone/plone.schema)
+
+`zope.schema` and `plone.schema` provide a very comprehensive set of {ref}`backend-fields-label` out of the box.
+Finding good documentation for them, however, can be challenging.  Here are
+some starting points:
+
+- {ref}`reference list of fields used in Plone <backend-fields-label>`
+
+
+## Advanced
+
+We can use a schema class to store data based on our model definition in the ZODB
+database.
+
+We use `zope.schema.fieldproperty.FieldProperty` to bind
+persistent class attributes to the data definition.
+
+Example:
+
+```
+from persistent import Persistent # Automagical ZODB persistent object
+from zope.schema.fieldproperty import FieldProperty
+
+class CheckoutAddress(Persistent):
+    """ Store checkout address """
+
+    # Declare that all instances of this class will
+    # conform to the ICheckoutAddress data model:
+    zope.interface.implements(ICheckoutAddress)
+
+    # Provide the fields:
+    first_name = FieldProperty(ICheckoutAddress["first_name"])
+    last_name = FieldProperty(ICheckoutAddress["last_name"])
+    organization = FieldProperty(ICheckoutAddress["organization"])
+    phone = FieldProperty(ICheckoutAddress["phone"])
+    country =  FieldProperty(ICheckoutAddress["country"])
+    state = FieldProperty(ICheckoutAddress["state"])
+    city = FieldProperty(ICheckoutAddress["phone"])
+    postal_code = FieldProperty(ICheckoutAddress["postal_code"])
+    street_address = FieldProperty(ICheckoutAddress["street_address"])
+```
+
+For persistent objects, see {doc}`persistent object documentation
+</develop/plone/persistency/persistent>`.
+
+
+### Using schemas as data models
+
+Based on the example data model above, we can use it in e.g. content type
+{doc}`browser views </develop/plone/views/browserviews>` to store arbitrary data as content
+type attributes.
+
+Example:
+
+```
+class MyView(BrowserView):
+    """ Connect this view to your content type using a ZCML declaration.
+    """
+
+    def __call__(self):
+        # Get the content item which this view was invoked on:
+        context = self.context.aq_inner
+
+        # Store a new address in it as the ``test_address`` attribute
+        context.test_address = CheckoutAddress()
+        context.test_address.first_name = u"Mikko"
+        context.test_address.last_name = u"Ohtamaa"
+
+        # Note that you can still add arbitrary attributes to any
+        # persistent object.  They are simply not validated, as they
+        # don't go through the ``zope.schema`` FieldProperty
+        # declarations.
+        # Do not do this, you will regret it later.
+        context.test_address.arbitary_attribute = u"Don't do this!"
+```
+
+### Field order
 
 The `order` attribute can be used to determine the order in which fields in
 a schema were defined. If one field was created after another (in the same
 thread), the value of `order` will be greater.
 
-## Default values
+### Default values
 
 To make default values of schema effective, class attributes must be
 implemented using `FieldProperty`.
@@ -324,7 +334,7 @@ something = SomeStorage()
 assert something.some_value == True
 ```
 
-## Validation and type constrains
+### Validation and type constrains
 
 Schema objects using field properties provide automatic validation
 facilities, preventing setting badly formatted attributes.
@@ -387,7 +397,7 @@ class IContact(Interface):
     email = schema.TextLine(title=u'Email', constraint=isEmail)
 ```
 
-## Persistent objects and schema
+### Persistent objects and schema
 
 ZODB persistent objects do not provide facilities for setting field defaults
 or validating the data input.
@@ -463,7 +473,7 @@ header = HeaderBehavior()
 assert header.alternatives = []
 ```
 
-## Collections (and multichoice fields)
+### Collections (and multichoice fields)
 
 Collections are fields composed of several other fields.
 Collections also act as multi-choice fields.
@@ -475,7 +485,7 @@ For more information see:
 - Schema [field sources documentation](https://zopeschema.readthedocs.io/en/latest/sources.html#sources-in-fields)
 - [Choice field](https://zopeschema.readthedocs.io/en/latest/fields.html#choice)
 
-### Single-choice example
+#### Single-choice example
 
 Only one value can be chosen.
 
@@ -518,7 +528,7 @@ class ISyncRunOptions(Interface):
                               default=logging.INFO)
 ```
 
-### Multi-choice example
+#### Multi-choice example
 
 Using zope.schema.List, many values can be chosen once.
 Each value is atomically constrained by *value_type* schema field.
@@ -546,7 +556,7 @@ class IMultiChoice(model.Schema):
                                )
 ```
 
-## Dynamic schemas
+### Dynamic schemas
 
 Schemas are singletons, as there only exist one class instance
 per Python run-time. For example, if you need to feed schemas generated dynamically
@@ -565,7 +575,7 @@ as the same copy is shared between different threads and
 if there are two concurrent HTTP requests problems occur.
 ```
 
-### Replacing schema fields with dynamically modified copies
+#### Replacing schema fields with dynamically modified copies
 
 The below is an example for z3c.form. It uses Python `copy`
 module to copy f.field reference, which points to zope.schema
@@ -600,7 +610,7 @@ def fields(self):
             f.field = schema_field
 ```
 
-### Don't use dict {} or list \[\] as a default value
+#### Don't use dict {} or list \[\] as a default value
 
 Because how Python object construction works, giving \[\] or {}
 as a default value will make all created field values to share this same object.