This section contains all the details of the resource fields built into Odin.
odin.fields
The following arguments are available to all field types. All are optional.
:pyField.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.
:pyField.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.
:pyField.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.
:pyField.null
If True
Odin will raise a validation error if a value is null
. Default is False
.
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 :pyodin.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'
:pyField.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.
:pyField.doc_text
Doc text is used by the :pyodin.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.
:pyField.validators
:pyField.error_messages
:pyField.is_attribute
:pyField.use_default_if_not_provided
Simple field types.
class StringField([max_length=None, **options])
A string.
StringField has one extra argument:
- :py
StringField.max_length
The maximum length (in characters) of the field. The
max_length
value is enforced Odin’s validation.
class IntegerField([min_value=None, max_value=None, **options])
An integer.
IntegerField has two extra arguments:
- :py
IntegerField.min_value
The minimum value of the field. The :py
min_value
value is enforced Odin’s validation.- :py
IntegerField.max_value
The maximum value of the field. The :py
max_value
value is enforced Odin’s validation.
class FloatField([**options])
A floating-point number represented in Python by a float instance.
FloatField has two extra arguments:
- :py
FloatField.min_value
The minimum value of the field. The :py
min_value
value is enforced Odin’s validation.- :py
FloatField.max_value
The maximum value of the field. The :py
max_value
value is enforced Odin’s validation.
class BooleanField([**options])
A true/false field.
class DateField([**options])
A :pydate
field or date encoded in ISO-8601 date string format.
class TimeField([assume_local=True, **options])
A :pydatetime.time
field or time encoded in ISO-8601 time string format.
TimeField has an extra argument:
- :py
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 :py
True
, in this state naive :pytime
objects are assumed to be in the current system timezone. Similarly on decoding a time string the output :pytime
will be converted to the current system timezone.
class NaiveTimeField([ignore_timezone=False, **options])
A :pydatetime.time
field or time encoded in ISO-8601 time string format. The naive time field differs from :py~TimeField
in the handling of the timezone, a timezone will not be applied if one is not specified.
NaiveTimeField has an extra argument:
- :py
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.
class DateTimeField([**options])
A :pydatetime.datetime
field or date encoded in ISO-8601 datetime string format.
DateTimeField has an extra argument:
- :py
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 :py
True
, in this state naive :pydatetime
objects are assumed to be in the current system timezone. Similarly on decoding a date time string the output :pydatetime
will be converted to the current system timezone.
class NaiveDateTimeField([ignore_timezone=False, **options])
A :pydatetime.datetime
field or time encoded in ISO-8601 datetime string format. The naive date time field differs from :py~DateTimeField
in the handling of the timezone, a timezone will not be applied if one is not specified.
NaiveDateTimeField has an extra argument:
- :py
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.
class HttpDateTimeField([**options])
A :pydatetime
field or date encoded in ISO-1123 or HTTP datetime string format.
class UUIDField([**options])
A :pyUUID
field.
This field supports most accepted values for initializing a UUID except bytes_le.
class EnumField(enum, [**options])
A :pyenum.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 :pyenum.IntEnum
variant is also supported.
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.
class PathField([**options])
A :pypathlib.Path
field that will convert to and from a Path value and a string type.
2.0
class UrlField([**options])
Based on a string field, validates that the supplied value is a valid URL.
class EmailField([**options])
Based on a string field, validates that the supplied value is a valid email address.
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.
class ArrayField([**options])
An array structure represented in Python by a list instance.
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.
- :py
TypedArrayField.field
An instance of an odin field that is used to validate each entry in the array.
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.
- :py
TypedDictField.key_field
An instance of an odin field that is used to validate each key in the dict; default is
StringField
.- :py
TypedDictField.value_field
An instance of an odin field that is used to validate each value in the dict; default is
StringField
.
class DictField([**options])
A dictionary.
Note
The object values in the object are not defined.
Odin also defines a set of fields that allow for composition.
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.
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.
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 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:
field-option-verbose_name
field-option-verbose_name_plural
field-option-name
field-option-doc_text
class CalculatedField(expr[, **options])
class ConstantField(value[, **options])
A fixed value that remains unchanged.
class MultiPartField(field_names, separator=""[, **options])
A field that combines strings from other resource fields with a joining value.