Changeset 4835 for waeup

Timestamp:

17 Jan 2010, 14:14:30 (15 years ago)

Author:

uli

Message:

Update/fix converter docs.

File:

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

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

@@ -16 +16 @@
     >>> import grok
     >>> grok.testing.grok('waeup')
+
+Constants
+=========
+
+.. attribute:: NONE_STRING_VALUE
+
+   This value determines, which string represents
+   'non-values'. Current setting is:
+
+      >>> from waeup.utils.converters import NONE_STRING_VALUE
+      >>> NONE_STRING_VALUE
+      ''
+
+   If this value is found during conversion from strings, the value to
+   set will become ``None``.
+
 
 Adapters
@@ -35 +51 @@
    :mod:`zope.schema` like :class:`zope.schema.TextLine`,
    `zope.schema.Choice` or similar.
+
+   .. method:: provides(waeup.interfaces.ISchemaTypeConverter)
+
+   .. method:: _convertValueFromString(string)
+
+       Raises :exc:`NotImplementedError`.
+
+       Called by :meth:`fromString()` to convert a given string to a
+       value appropriate for the applied field type. The string might
+       be ``None`` or ``missing_value`` from field definition.
+
+       Override this method in derived classes to get a working
+       converter.
+
+   .. method:: _convertValueToString(value)
+
+       Raises :exc:`NotImplementedError`.
+
+       Called by :meth:`toString()` to convert a given value to a
+       string suitable to be stored for instance in CSV files.
+
+       Override this method in derived classes to get a working
+       converter.
 
    .. method:: fromString(string[, strict=True])
@@ -46 +85 @@
        data.
 
+   .. method:: toString(value[, strict=True])
+
+       Generate a string from ``value``, suitable to be stored in CSV
+       files or similar. This method does preliminary checks, handles
+       defaults and ``missing_value`` stuff and then calls
+       :meth:`_convertValueToString(value)` to do the actual
+       conversion.
+
+       Use `strict` to enable/disable validations of transformed
+       data.
+       
+
 
 :class:`TextConverter`
@@ -187 +238 @@
    .. method:: provides(waeup.interfaces.ISchemaTypeConverter)
 
-   .. method:: fromString(string[, strict=True])
+   .. method:: fromString(string[, strict=False])
 
        Compute a value from the given `string`. Be aware that this
@@ -200 +251 @@
        data.
 
-
+       As an invalid value will result in a `KeyError`, additional
+       validation checks are disabled with this converter. This speeds
+       up things as expensive lookups are avoided.
+
+   .. method:: toString(value[, strict=False])
+
+       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.
+
+       As an invalid value will result in a `ValueError`, additional
+       validation checks are disabled with this converter. This speeds
+       up things as expensive lookups are avoided.
 
 
@@ -521 +591 @@
 
 Now we can get a converter for this field by explicitly creating a
-:class:`TextConverter` instance:
+:class:`ChoiceConverter` instance:
 
     >>> from waeup.utils.converters import ChoiceConverter