Commits

Anonymous committed 7706a1c

update docs

Comments (0)

Files changed (3)

    <http://docs.repoze.org/colander>`_
 
 A schema is composed of one or more *schema node* objects, each
-typically of the class :class:`colander.SchemaNode`, usually in a nested
-arrangement.  Each schema node object has a required *type*, an
-optional *validator*, an optional *default*, an optional *title*, an
-optional *description*, and a slightly less optional *name*.
+typically of the class :class:`colander.SchemaNode`, usually in a
+nested arrangement.  Each schema node object has a required *type*, an
+optional *validator*, an optional *default*, an optional *missing*, an
+optional *title*, an optional *description*, and a slightly less
+optional *name*.
 
 The *type* of a schema node indicates its data type (such as
 :class:`colander.Int` or :class:`colander.String`).
 ``validator=colander.Range(0, 200)``.  A validator is not called after
 schema node serialization, only after node deserialization.
 
-The *default* of a schema node indicates its default value if a value
-for the schema node is not found in the input data during
-serialization.  It should be the *deserialized* representation.  If a
-schema node does not have a default, it is considered a required
-schema node.
+The *default* of a schema node indicates the value to be serialized if
+a value for the schema node is not found in the input data during
+serialization.  It should be the deserialized representation.  If a
+schema node does not have a default, it is considered "serialization
+required".
+
+The *missing* of a schema node indicates the value to be deserialized
+if a value for the schema node is not found in the input data during
+deserialization.  It should be the deserialized representation.  If a
+schema node does not have a default, it is considered "deserialization
+required".
 
 The *name* of a schema node is used to relate schema nodes to each
 other.  It is also used as the title if a title is not provided.

docs/serialization.rst

 .. code-block:: python
    :linenos:
 
-    def deserialize(self, field, pstruct):
-        if pstruct is None:
-            pstruct = {}
-        value = pstruct.get('value') or ''
-        confirm = pstruct.get('confirm') or ''
-        field.confirm = confirm
-        if value != confirm:
-            raise Invalid(field.schema, self.mismatch_message, value)
-        return value
+    import colander
 
-    def serialize(self, field, cstruct=None, readonly=False):
-        if cstruct is None:
-            cstruct = field.default
-        if cstruct is None:
+    def serialize(self, field, cstruct, readonly=False):
+        if cstruct is colander.null:
             cstruct = ''
         confirm = getattr(field, 'confirm', '')
         template = readonly and self.readonly_template or self.template
                               confirm_subject=self.confirm_subject,
                               )
 
+    def deserialize(self, field, pstruct):
+        if pstruct is colander.null:
+            return colander.default
+        value = pstruct.get('value') or ''
+        confirm = pstruct.get('confirm') or ''
+        field.confirm = confirm
+        if value != confirm:
+            raise Invalid(field.schema, self.mismatch_message, value)
+        return value
 
 The schema type associated with this widget is expecting a single
 string as its cstruct.  The ``value`` passed to the exception
     import cgi
 
     class MyInputWidget(Widget):
-        def serialize(self, field, cstruct=None, readonly=False):
+        def serialize(self, field, cstruct, readonly=False):
             if cstruct is null:
                 cstruct = u''
             return '<input type="text" value="%s">' % cgi.escape(cstruct)
 
-        def deserialize(self, field, pstruct=None):
+        def deserialize(self, field, pstruct):
             if cstruct is null:
                 return default
+            return pstruct
 
+Note that both the deserialize method of a widget must also deal with
+the ``colander.null`` value (usually by returning `colander.default``,
+which signifies to the schema that the default value should be used if
+it exists).  ``colander.null`` will be passed to the widget when a
+value is missing from the pstruct.
+
+The only other real constraint of the deserialize method is that the
+``serialize`` method must be able to reserialize the return value of
+``deserialize``.  One caveat exists: if ``deserialize`` returns
+``colander.default``, the ``serialize`` method needn't deal with it
+explicitly; it's handled at a higher level.
+