Changeset 4815

Timestamp:

15 Jan 2010, 11:42:21 (15 years ago)

Author:

uli

Message:

• Document BoolConverter?

• Test toString-conversions.

File:

• waeup/branches/ulif-importers/src/waeup/utils/converters.txt (modified) (15 diffs)

waeup/branches/ulif-importers/src/waeup/utils/converters.txt

@@ -24 +24 @@
 
 :class:`Converter`
-----------------------
+------------------
 
 .. class:: Converter(field)
@@ -75 +75 @@
        data.
 
+   .. method:: toString(value[, strict=True])
+
+       Return `value` as string or ``None``.
+
+       If `value` is ``None`` (or field's `missing_value`), ``None``
+       is returned.
+
+       If the value is not valid for the applied field an exception
+       might be raised.
+
+       Use `strict` to enable/disable validations of input data.
+
+
+:class:`BoolConverter`
+---------------------
+
+.. class:: BoolConverter(field)
+
+   Create a converter for boolean fields.
+
+   `field` must be an object implementing
+   ``zope.schema.interfaces.IBool``.
+
+   Instances of this class are available as adapters from :mod:`IBool`
+   to :mod:`ISchemaTypeConverter`.
+
+   .. method:: adapts(zope.schema.IBool)
+
+   .. method:: provides(waeup.interfaces.ISchemaTypeConverter)
+
+   .. method:: fromString(string[, strict=True])
+
+       Compute an integer number value from the given `string`. In
+       general '1', 'true', and 'yes' are interpreted as ``True``,
+       ``None`` is interpreted as 'no value' and all other values are
+       interpreted as ``True``.
+
+       Use `strict` to enable/disable validations of transformed
+       data.
+
+   .. method:: toString(value[, strict=True])
+
+       Return `value` as string or ``None``.
+
+       If `value` is ``None`` (or field's `missing_value`), ``None``
+       is returned. Otherwise ``0`` or ``1`` are returned.
+
+       If the value is not valid for the applied field (i.e. not an
+       integer or `missing_value`) an exception
+       might be raised.
+
+       Use `strict` to enable/disable validations of input data.
+
 
 :class:`IntConverter`
@@ -101 +154 @@
        Use `strict` to enable/disable validations of transformed
        data.
+
+   .. method:: toString(value[, strict=True])
+
+       Return `value` as string or ``None``.
+
+       If `value` is ``None`` (or field's `missing_value`), ``None``
+       is returned.
+
+       If the value is not valid for the applied field (i.e. not an
+       integer or `missing_value`) an exception
+       might be raised.
+
+       Use `strict` to enable/disable validations of input data.
+
 
 
@@ -171 +238 @@
     u'blah'
 
+And back:
+
+    >>> converter.toString(u'blah')
+    'blah'
+
 Okay, not very surprising. But the field definitions can help also
 deliver values, if the given value is missing:
@@ -194 +266 @@
 
     >>> converter.fromString(None, strict=False) is None
-    True   
+    True 
 
 
@@ -207 +279 @@
     True
 
-We can also set a missing type:
+We can also set a value that indicates missing data (``None`` by default):
 
     >>> field = TextLine(title=u'Some Title',
@@ -216 +288 @@
     >>> converter.fromString(None)
     u'<NO-VALUE>'
+
+And put it back:
+
+    >>> converter.toString(u'<NO-VALUE>') is None
+    True
 
 
@@ -250 +327 @@
     666
 
+And back:
+
+    >>> converter.toString(666)
+    '666'
+
 Okay, not very surprising. But the field definitions can help also
 deliver values, if the given value is missing:
@@ -275 +357 @@
     True
 
+The same for the inverse operation:
+
+    >>> converter.toString(None)
+    Traceback (most recent call last):
+    ...
+    RequiredMissing
+
+    >>> converter.toString(None, strict=False) is None
+    True
+
+
 If a field is not required, we will get the ``missing_value`` type in
 same case:
@@ -283 +376 @@
     >>> converter = ISchemaTypeConverter(field)
     >>> converter.fromString(None) is None
+    True
+
+    >>> converter.toString(None) is None
     True
 
@@ -295 +391 @@
     >>> from zc.sourcefactory.browser.source import FactoredTerms
     >>> from zc.sourcefactory.browser.token import (
-    ...   fromString, fromUnicode, fromInteger)
+    ...   fromString, fromUnicode, fromInteger, fromPersistent)
     >>> from zope.component import getGlobalSiteManager
     >>> gsm = getGlobalSiteManager()
@@ -302 +398 @@
     >>> gsm.registerAdapter(fromUnicode)
     >>> gsm.registerAdapter(fromInteger)
+    >>> gsm.registerAdapter(fromPersistent)
 
 We create a field that also implements ``IChoice``, a regular
@@ -331 +428 @@
 
     >>> converter.fromString('a')
+    'a'
+
+or values back to strings:
+
+    >>> converter.toString('a')
     'a'
 
@@ -373 +475 @@
 Note, that when asking for conversion of Choice fields, you must
 deliver the token value of the source/vocabulary. This might be the
-same as the actual value, but it it might be not.
+same as the actual value as string, but it it might be different,
+depending of the kind of source/vocabulary used.
 
 Furthermore, when writing 'exporters', i.e. components that turn a
@@ -379 +482 @@
 token value of a term.
 
+Using the ;meth:`toString()` will deliver the token for us:
+
+    >>> converter.toString(1)
+    '1'
+
+    >>> from waeup.interfaces import ICourse
+    >>> from zope.schema import getFields
+    >>> field = getFields(ICourse)['semester']
+
+    >>> converter = ISchemaTypeConverter(field)
+    >>> converter.fromString('0')
+    0
+
+    >>> converter.toString(1)
+    '1'
+
+
+
+    >>> class Cave(object):
+    ...   name = 'Home sweet home'
+
+    >>> def tokenizer(cave):
+    ...   return cave.name
+
+    >>> from zc.sourcefactory.interfaces import IToken
+    >>> from zope.component import getGlobalSiteManager
+    >>> gsm = getGlobalSiteManager()
+    >>> gsm.registerAdapter(tokenizer, required=(Cave,), provided=IToken)
+
+    >>> obj1 = Cave()
+    >>> obj1.name = 'Wilma'
+
+    >>> obj2 = Cave()
+    >>> obj2.name = 'Fred'
+
+    >>> from zc.sourcefactory.basic import BasicSourceFactory
+    >>> class CustomSource(BasicSourceFactory):
+    ...   def getValues(self):
+    ...     return [obj1, obj2]
+    ...    
+    ...   def getTitle(self, value):
+    ...     return value.name
+
+    >>> field = Choice(title=u'Some cave',
+    ...                default=obj1,
+    ...                source=CustomSource(),
+    ...                required=True)
+
+    >>> converter = ISchemaTypeConverter(field)
+    >>> result = converter.fromString('Wilma')
+    >>> result
+    <Cave object at 0x...>
+
+    >>> result is obj1, result.name
+    (True, 'Wilma')
+
+    >>> converter.toString(obj2)
+    'Fred'