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.
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.
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 naivetime
objects are assumed to be in the current system timezone. Similarly on decoding a time string the outputtime
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 naivedatetime
objects are assumed to be in the current system timezone. Similarly on decoding a date time string the outputdatetime
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:
CalculatedField¶
class CalculatedField(expr[, **options])
MultiPartField¶
class MultiPartField(field_names, separator=""[, **options])
A field that combines strings from other resource fields with a joining value.