=====================
Model field reference
=====================

.. module: data_migrator.models.fields
   :synopsis: Built-in field types.

.. currentmodule: data_migrator.models

This document contains all API references of BaseClass :class:`~.fields.BaseField`
including the `field options`_ and `field types`_ data_migrator offers.

.. note::

    Technically, these models are defined in :mod:`data_migrator.models.fields`, but
    for convenience they're imported into :mod:`data_migrator.models`, the standard
    convention is to use ``from data_migrator import models`` and refer to fields as
    ``models.<Foo>Field``

Field options
=============

The following arguments are available to all field types. All are optional.

``pos``
--------

.. attribute:: Field.pos

If positive or zero this denotes the column in the source data to select and store in
this field. If not set (or negative) the fields is interpreted as not selecting just
a column from the source but to take the full row in the parse function


``name``
--------

.. attribute:: Field.name

The name of this field. By default this is the name provided in the model declaration.
This attribute is to replace that name by the final column name.


``default``
-----------

.. attribute:: Field.default

The default value to use if the source column is found to be a ``null`` field or if the
parse function returns None. This attribute has default values for Fields that are not
Null<xxx>Fields. For example NullStringField has both NULL and empty string as empty
value. StringField only has empty string as empty value. With this field it can be
changed to some other standard value. Consider a Country field as string and setting it
to the home country by default.

``null``
--------

.. attribute:: Field.null

If set it will match the source column value and consider this a ``None`` value. By
default this attribute is set to ``None``. Note that for none Null fields ``None``
will be translated to :attr:`~Field.default`

``replace``
-----------

.. attribute:: Field.replace

If set this is a pre-emit replacement function. This for example could be used to
insert replacement lookup select queries. Adding more indirection into the data
generation.

``replace``
-----------

.. attribute:: Field.replace

If set this is a pre-emit replacement function. This for example could be used to
insert replacement lookup select queries. Adding more indirection into the data
generation.

``parse``
---------

.. attribute:: Field.parse

If set this is the parsing function to replace the read value into something to use
further down the data migration. Use this for example to clean phone numbers, translate
country definitions into alpha3 codes, or to translate ID's into values based on a
separately loaded lookup table.

``validate``
------------

.. attribute:: Field.validate

Expects a function that returns a boolean, and used to validate the input data.
Expecting data within a range or a specific format, add a column validator here.
Raises `ValidationException` if set and false.

``max_length``
--------------

.. attribute:: Field.max_length

In case of StringFields use this to trim string values to maximum length.

``unique``
----------

.. attribute:: Field.unique

If ``True``, `data-migrator` will check uniqueness of intermediate values
(after parsing). Default is ``False``.

In relationship with the default manager this will keep track of values for this
field. The manager can raise exceptions if uniqueness is violated. Note that it
is up to the manager to either fail or drop the record if the exception is raised.

.. note::

    Use this with HiddenField and a row parse function if some combination of
    fields (aka a compound key) is expected to be unique and not to be violated.


``validate_output``
-------------------

.. attribute:: Field.validate_output

A pre-emit validator used to scan the bare output and raise exceptions if output is
not as expected

``creation_order``
------------------

.. attribute:: Field.creation_order

An automatically generated attribute used to determine order of specification, and
used in the emitting of dataset

.. _field-types:

Field types
===========

.. currentmodule:: data_migrator.models.fields

``BooleanField``
----------------
.. autoclass::  data_migrator.models.fields.BooleanField


``IntField``
----------------
.. autoclass::  data_migrator.models.fields.IntField


``NullIntField``
----------------
.. autoclass::  data_migrator.models.fields.NullIntField


``HiddenField``
----------------
.. autoclass::  data_migrator.models.fields.HiddenField


``StringField``
----------------
.. autoclass::  data_migrator.models.fields.StringField


``NullStringField``
-------------------
.. autoclass::  data_migrator.models.fields.NullStringField


``UUIDField``
----------------
.. autoclass::  data_migrator.models.fields.UUIDField


``NullField``
----------------
.. autoclass::  data_migrator.models.fields.NullField


``JSONField``
----------------
.. autoclass::  data_migrator.models.fields.JSONField


``MappingField``
----------------
.. autoclass::  data_migrator.models.fields.MappingField
   :members:
