Field reference¶

This section contains all the details of the resource fields built into Odin.

Field options¶

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

verbose_name¶

Field.verbose_name

A human-readable name for the field. If the verbose name isn’t given, Odin will automatically create it using the field’s attribute name, converting underscores to spaces.

verbose_name_plural¶

Field.verbose_name_plural

A human-readable name for the field. If the verbose name isn’t given, Odin will automatically create it using the field’s attribute name, converting underscores to spaces.

name¶

Field.name

Name of the field as it appears in the exported document. If the name isn’t given, Odin will use the field’s attribute name.

null¶

Field.null

If True Odin will raise a validation error if a value is null. Default is False.

choices¶

Field.choices

An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this field. If this is given, the choices are used to validate entries.

Note

Choices are also used by the odin.contrib.doc_gen to generate documentation.

A choices list looks like this:

GENRE_CHOICES = (
    ('sci-fi', 'Science Fiction'),
    ('fantasy', 'Fantasy'),
    ('others', 'Others'),
)

The first element in each tuple is the value that will be used to validate, the second element is used for documentation. For example:

import Odin

class Book(Odin.Resource):
    GENRE_CHOICES = (
        ('sci-fi', 'Science Fiction'),
        ('fantasy', 'Fantasy'),
        ('others', 'Others'),
    )
    title = Odin.StringField()
    genre = Odin.StringField(choices=GENRE_CHOICES)
>>> b = Book(title="Consider Phlebas", genre="sci-fi")
>>> b.genre
'sci-fi'

default¶

Field.default

The default value for the field. This can be a value or a callable object. If callable it will be called every time a new object is created.

doc_text (help_text)¶

Field.doc_text

Doc text is used by the odin.contrib.doc_gen to generate documentation.

Note

help_text will be deprecated in a future release in favor of doc_text.

Also useful for inline documentation even if documentation is not generated.

validators¶

Field.validators

error_messages¶

Field.error_messages

is_attribute¶

Field.is_attribute

use_default_if_not_provided¶

Field.use_default_if_not_provided

Standard fields¶

Simple field types.

StringField¶

class StringField([max_length=None, **options])

A string.

StringField has one extra argument:

StringField.max_length: The maximum length (in characters) of the field. The max_length value is enforced Odin’s validation.

IntegerField¶

class IntegerField([min_value=None, max_value=None, **options])

An integer.

IntegerField has two extra arguments:

IntegerField.min_value: The minimum value of the field. The min_value value is enforced Odin’s validation.
IntegerField.max_value: The maximum value of the field. The max_value value is enforced Odin’s validation.

FloatField¶

class FloatField([**options])

A floating-point number represented in Python by a float instance.

FloatField has two extra arguments:

FloatField.min_value: The minimum value of the field. The min_value value is enforced Odin’s validation.
FloatField.max_value: The maximum value of the field. The max_value value is enforced Odin’s validation.

BooleanField¶

class BooleanField([**options])

A true/false field.

DateField¶

class DateField([**options])

A date field or date encoded in ISO-8601 date string format.

TimeField¶

class TimeField([assume_local=True, **options])

A datetime.time field or time encoded in ISO-8601 time string format.

TimeField has an extra argument:

TimeField.assume_local: This adjusts the behaviour of how a naive time (time objects with no timezone) or time strings with no timezone specified. By default assume_local is True, in this state naive time objects are assumed to be in the current system timezone. Similarly on decoding a time string the output time will be converted to the current system timezone.

NaiveTimeField¶

class NaiveTimeField([ignore_timezone=False, **options])

A datetime.time field or time encoded in ISO-8601 time string format. The naive time field differs from TimeField in the handling of the timezone, a timezone will not be applied if one is not specified.

NaiveTimeField has an extra argument:

NaiveTimeField.ignore_timezone: Ignore any timezone information provided to the field during parsing. Will also actively strip out any timezone information when processing an existing time value.

DateTimeField¶

class DateTimeField([**options])

A datetime.datetime field or date encoded in ISO-8601 datetime string format.

DateTimeField has an extra argument:

DateTimeField.assume_local: This adjusts the behaviour of how a naive time (date time objects with no timezone) or date time strings with no timezone specified. By default assume_local is True, in this state naive datetime objects are assumed to be in the current system timezone. Similarly on decoding a date time string the output datetime will be converted to the current system timezone.

NaiveDateTimeField¶

class NaiveDateTimeField([ignore_timezone=False, **options])

A datetime.datetime field or time encoded in ISO-8601 datetime string format. The naive date time field differs from DateTimeField in the handling of the timezone, a timezone will not be applied if one is not specified.

NaiveDateTimeField has an extra argument:

NaiveDateTimeField.ignore_timezone: Ignore any timezone information provided to the field during parsing. Will also actively strip out any timezone information when processing an existing datetime value.

HttpDateTimeField¶

class HttpDateTimeField([**options])

A datetime field or date encoded in ISO-1123 or HTTP datetime string format.

UUIDField¶

class UUIDField([**options])

A UUID field.

This field supports most accepted values for initializing a UUID except bytes_le.

EnumField¶

class EnumField(enum, [**options])

A enum.Enum field that will convert to and from an enum and it’s native type.

Ensure that the enum value is compatible with the codec being used.

The enum.IntEnum variant is also supported.

Changed in version 1.5.0: Choices can be used with EnumField to specify a subset of options. A sequence of enum values should be used that will be converted to choice tuples by Odin.

PathField¶

class PathField([**options])

A pathlib.Path field that will convert to and from a Path value and a string type.

New in version 2.0.

UrlField¶

class UrlField([**options])

Based on a string field, validates that the supplied value is a valid URL.

EmailField¶

class EmailField([**options])

Based on a string field, validates that the supplied value is a valid email address.

IP Fields¶

class IPv4Field([**options]) class IPv6Field([**options]) class IPv46Field([**options])

Based on a string field, validates that the supplied value is a valid IP address.

Use the IPv46Field to support either a v4 or v6 address.

ArrayField¶

class ArrayField([**options])

An array structure represented in Python by a list instance.

TypedArrayField¶

class TypedArrayField(field, [**options])

An array structure represented in Python by a list instance accepts an additional parameter of another field type that each entry in the array is validated against.

TypedArrayField.field: An instance of an odin field that is used to validate each entry in the array.

TypedDictField¶

class TypedDictField(key_field, value_field, [**options])

A object structure represented in Python by a dict instance accepts additional parameters of both a key and value field type that each item in the dict is validated against.

TypedDictField.key_field: An instance of an odin field that is used to validate each key in the dict; default is StringField.
TypedDictField.value_field: An instance of an odin field that is used to validate each value in the dict; default is StringField.

DictField¶

class DictField([**options])

A dictionary.

Note

The object values in the object are not defined.

Composite fields¶

Odin also defines a set of fields that allow for composition.

DictAs field¶

class DictAs(of[, **options])

A child object. Requires a positional argument: the class that represents the child resource.

Note

A default dict is automatically assigned.

ArrayOf field¶

class ArrayOf(of[, **options])

A child list. Requires a positional argument: the class that represents a list of resources.

Note

A default list is automatically assigned.

DictOf field¶

class DictOf(of[, **options])

A child dict. Requires a positional argument: the class that represents a dict (or hash map) of resources.

Note

A default dict is automatically assigned.

Virtual fields¶

Virtual fields are special fields that can be used to calculate a value or provide a value lookup. Unlike using a property a virtual field is also a treating like field in that it can be mapped or exported.

Note

You can use the

Virtual fields share many of the options of regular fields:

verbose_name
verbose_name_plural
name
doc_text (help_text)

CalculatedField¶

class CalculatedField(expr[, **options])

ConstantField¶

class ConstantField(value[, **options])

A fixed value that remains unchanged.

MultiPartField¶

class MultiPartField(field_names, separator=""[, **options])

A field that combines strings from other resource fields with a joining value.