:py:mod:`gnome.persist.extend_colander` ======================================= .. py:module:: gnome.persist.extend_colander .. autoapi-nested-parse:: Extend colander's basic types for serialization/deserialization of gnome specific types Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: gnome.persist.extend_colander.LocalDateTime gnome.persist.extend_colander.DefaultTuple gnome.persist.extend_colander.NumpyFixedLen gnome.persist.extend_colander.NumpyArray gnome.persist.extend_colander.DatetimeValue2dArray gnome.persist.extend_colander.DatetimeValue1dArray gnome.persist.extend_colander.TimeDelta gnome.persist.extend_colander.OrderedCollectionType .. py:class:: LocalDateTime(*args, **kwargs) Bases: :py:obj:`colander.DateTime` A type representing a Python ``datetime.datetime`` object. This type serializes python ``datetime.datetime`` objects to a `ISO8601 `_ string format. The format includes the date, the time, and the timezone of the datetime. The constructor accepts an argument named ``default_tzinfo`` which should be a Python ``tzinfo`` object. If ``default_tzinfo`` is not specified the default tzinfo will be equivalent to UTC (Zulu time). The ``default_tzinfo`` tzinfo object is used to convert 'naive' datetimes to a timezone-aware representation during serialization. If ``default_tzinfo`` is explicitly set to ``None`` then no default tzinfo will be applied to naive datetimes. You can adjust the error message reported by this class by changing its ``err_template`` attribute in a subclass on an instance of this class. By default, the ``err_template`` attribute is the string ``Invalid date``. This string is used as the interpolation subject of a dictionary composed of ``val`` and ``err``. ``val`` and ``err`` are the unvalidatable value and the exception caused trying to convert the value, respectively. These may be used in an overridden err_template as ``${val}`` and ``${err}`` respectively as necessary, e.g. ``_('${val} cannot be parsed as an iso8601 date: ${err}')``. For convenience, this type is also willing to coerce ``datetime.date`` objects to a DateTime ISO string representation during serialization. It does so by using midnight of the day as the time, and uses the ``default_tzinfo`` to give the serialization a timezone. Likewise, for convenience, during deserialization, this type will convert ``YYYY-MM-DD`` ISO8601 values to a datetime object. It does so by using midnight of the day as the time, and uses the ``default_tzinfo`` to give the serialization a timezone. If the :attr:`colander.null` value is passed to the serialize method of this class, the :attr:`colander.null` value will be returned. The subnodes of the :class:`colander.SchemaNode` that wraps this type are ignored. .. py:method:: strip_timezone(_datetime) .. py:method:: serialize(node, appstruct) Serialize a DateTime object returns an iso formatted string .. py:method:: deserialize(node, cstruct) .. py:class:: DefaultTuple Bases: :py:obj:`colander.Tuple` A Tuple subclass that provides defaults from child nodes. Required because Tuple returns `colander.null` by default when ``appstruct`` is not provided, instead of creating a Tuple of default values. .. py:method:: serialize(node, appstruct) .. py:class:: NumpyFixedLen Bases: :py:obj:`colander.Tuple` A subclass of :class:`colander.Tuple` that converts itself to a Tuple and back to a numpy array. This is used to define schemas for Numpy arrays that have a fixed size like WorldPoint, 3D velocity of SimpleMover. .. py:method:: serialize(node, appstruct) Serialize a fixed length numpy array .. py:method:: deserialize(node, cstruct) .. py:class:: NumpyArray Bases: :py:obj:`colander.List` A subclass of :class:`colander.List` that converts itself to a more general numpy array of greater than length 1. .. py:method:: serialize(node, appstruct) Serialize a numpy array .. py:method:: deserialize(node, cstruct) .. py:class:: DatetimeValue2dArray(accept_scalar=False) Bases: :py:obj:`colander.Sequence` A subclass of :class:`colander.Sequence` that converts itself to a numpy array using :class:`gnome.basic_types.datetime_value_2d` as the data type. todo: serialize/deserialize must happen for each element - not very efficient. .. py:method:: serialize(node, appstruct) Serialize a 2D Datetime value array .. py:method:: deserialize(node, cstruct) Along with the normal ``node`` and ``cstruct`` arguments, this method accepts an additional optional keyword argument: ``accept_scalar``. This keyword argument can be used to override the constructor value of the same name. If ``accept_scalar`` is ``True`` and the ``cstruct`` does not have an ``__iter__`` method or is a mapping type, the value will be turned into a single element list. If ``accept_scalar`` is ``False`` and the ``cstruct`` does not have an ``__iter__`` method or is a mapping type, an :exc:`colander.Invalid` error will be raised during serialization and deserialization. The default of ``accept_scalar`` is ``None``, which means respect the default ``accept_scalar`` value attached to this instance via its constructor. .. py:class:: DatetimeValue1dArray(accept_scalar=False) Bases: :py:obj:`colander.Sequence` A subclass of :class:`colander.Sequence` that converts itself to a numpy array using :class:`gnome.basic_types.datetime_value_2d` as the data type. .. py:method:: serialize(node, appstruct) Along with the normal ``node`` and ``appstruct`` arguments, this method accepts an additional optional keyword argument: ``accept_scalar``. This keyword argument can be used to override the constructor value of the same name. If ``accept_scalar`` is ``True`` and the ``appstruct`` does not have an ``__iter__`` method or is a mapping type, the value will be turned into a single element list. If ``accept_scalar`` is ``False`` and the ``appstruct`` does not have an ``__iter__`` method or is a mapping type, an :exc:`colander.Invalid` error will be raised during serialization and deserialization. The default of ``accept_scalar`` is ``None``, which means respect the default ``accept_scalar`` value attached to this instance via its constructor. .. py:method:: deserialize(node, cstruct) Along with the normal ``node`` and ``cstruct`` arguments, this method accepts an additional optional keyword argument: ``accept_scalar``. This keyword argument can be used to override the constructor value of the same name. If ``accept_scalar`` is ``True`` and the ``cstruct`` does not have an ``__iter__`` method or is a mapping type, the value will be turned into a single element list. If ``accept_scalar`` is ``False`` and the ``cstruct`` does not have an ``__iter__`` method or is a mapping type, an :exc:`colander.Invalid` error will be raised during serialization and deserialization. The default of ``accept_scalar`` is ``None``, which means respect the default ``accept_scalar`` value attached to this instance via its constructor. .. py:class:: TimeDelta Bases: :py:obj:`colander.Float` Add a type to serialize/deserialize timedelta objects .. py:method:: serialize(node, appstruct) .. py:method:: deserialize(*args, **kwargs) .. py:class:: OrderedCollectionType(accept_scalar=False) Bases: :py:obj:`colander.Sequence` A type which represents a variable-length sequence of nodes, all of which must be of the same type. The type of the first subnode of the :class:`colander.SchemaNode` that wraps this type is considered the sequence type. The optional ``accept_scalar`` argument to this type's constructor indicates what should happen if the value found during serialization or deserialization does not have an ``__iter__`` method or is a mapping type. If ``accept_scalar`` is ``True`` and the value does not have an ``__iter__`` method or is a mapping type, the value will be turned into a single element list. If ``accept_scalar`` is ``False`` and the value does not have an ``__iter__`` method or is a mapping type, an :exc:`colander.Invalid` error will be raised during serialization and deserialization. The default value of ``accept_scalar`` is ``False``. If the :attr:`colander.null` value is passed to the serialize method of this class, the :attr:`colander.null` value is returned. .. py:method:: _validate(node, value, accept_scalar)