Fields¶
Field¶
-
class
valedictory.fields.
Field
(required=None, error_messages=None, **kwargs)[source]¶ The base class for all fields. By itself,
Field
only enforces theField.required
behaviour. Subclasses ofField
add more validation rules to add more useful behaviours.Attributes
-
required
= True¶ Is this field required to be present in the data.
If a field is not required, and is not present in the data, it will not be present in the cleaned data either. If a field is required, and is not present in the data, a
ValidationException
will be thrown.
-
default
¶ The default for this field if no value is supplied. Can be
None
. If not set, there is no default and the field will not be present in the cleaned data.
-
default_error_messages
¶ A dictionary of messages for each error this field can raise. The default error messages can be overridden by passing an
error_messages
dict to the constructor.- required
- Raised when the field is not in the input data, but the field is required.
Methods
-
clean
(data)[source]¶ Clean and validate the given data.
If there is no data for the field, pass in the
NoData
class to signal this. If the field is required, aValidationException
will be raised. If the field is not required,NoData
is returned.
-
error
(code, params=None, cls=<class 'valedictory.exceptions.ValidationException'>, **kwargs)¶ Construct a validation exception. The message will be pulled from the
default_error_messages
dictionary usingcode
as the key. If the error message takes format parameters, pass in a dict as theparams
argument.
-
TypedField¶
-
class
valedictory.fields.
TypedField
(*, required_types=None, excluded_types=None, type_name=None, **kwargs)[source]¶ A
Field
that requires a specific type of input, such as strings, integers, or booleans.-
required_types
¶ A tuple of acceptable classes for the data. For example,
(int, float)
would accept any number type.
-
excluded_types
¶ A tuple of unacceptable classes for the data. For example,
bool
s are subclasses ofint
s, but should not be accepted as valid data when a number is expected.
-
type_name
¶ The friendly name of the type for error messages.
-
default_error_messages
¶ - invalid_type
- Raised when the incoming data is not an instance of
required_types
, or is a subclass ofexcluded_types
.
-
StringField¶
-
class
valedictory.fields.
StringField
(min_length=None, max_length=None, **kwargs)[source]¶ Accepts a string, and only strings.
-
min_length
= 0¶ The minimum acceptable length of the string. Defaults to no minimum length.
-
max_length
= inf¶ The maximum acceptable length of the string. Defaults to no maximum length.
-
default_error_messages
¶ - non_empty
- Raised when the input is an empty string, but
min_length
is 1. - min_length
- Raised when the input is shorter than
min_length
. - max_length
- Raised when the input is longer than
max_length
.
-
BooleanField¶
NumberField¶
-
class
valedictory.fields.
NumberField
(min=None, max=None, **kwargs)[source]¶ A field that only accepts numbers, either floats or integers.
-
min
= None¶ The minimum allowable value. Values lower than this will raise an exception. Defaults to no minimum value.
-
max
= None¶ The maximum allowable value. Values higher than this will raise an exception. Defaults to no maximum value.
-
IntegerField¶
-
class
valedictory.fields.
IntegerField
(min=None, max=None, **kwargs)[source]¶ A
NumberField
that only accepts integers.
FloatField¶
-
class
valedictory.fields.
FloatField
(min=None, max=None, **kwargs)[source]¶ A
NumberField
that only accepts floating point numbers.
EmailField¶
-
class
valedictory.fields.
EmailField
(min_length=None, max_length=None, **kwargs)[source]¶ A
StringField
that only accepts email address strings. The email matching regular expression only checks for basic conformance: the string must have at least one character, then an ‘@’ symbol, then more characters with at least one dot.-
default_error_messages
¶ - invalid_email
- Raised when the data is not a valid email address.
-
DateTimeField¶
-
class
valedictory.fields.
DateTimeField
(*, timezone_required=None, **kwargs)[source]¶ A field that only accepts ISO 8601 date time strings.
After cleaning, a
datetime.datetime
instance is returned.-
timezone_required
¶ If a timezone is required. If this is
False
, naive datetimes will be allowed.
-
default_error_messages
¶ - invalid_format
- Raised when the input is not a valid ISO8601-formatted date time
- no_timezone
- Raised when the input does not have a timezone specified, but
timezone_required
isTrue
-
DateField¶
TimeField¶
-
class
valedictory.fields.
TimeField
(*, timezone_required=None, **kwargs)[source]¶ A field that only accepts ISO 8601 time strings.
After cleaning, a
datetime.time
instance is returned.-
timezone_required
¶ If a timezone is required. If this is
False
, naive times will be allowed.
-
default_error_messages
¶ - invalid_format
- Raised when the input is not a valid ISO8601-formatted date time
- no_timezone
- Raised when the input does not have a timezone specified, but
timezone_required
isTrue
-
YearMonthField¶
ChoiceField¶
-
class
valedictory.fields.
ChoiceField
(choices=None, **kwargs)[source]¶ A field that only accepts values from a predefined set of choices. The values can be of any hashable type.
-
choices
= set()¶ The field will only accept data if the value is in this set.
-
default_error_messages
¶ - invalid_choice
- Raised when the value is not one of the valid choices
-
ChoiceMapField¶
-
class
valedictory.fields.
ChoiceMapField
(choices=None, **kwargs)[source]¶ A field that only accepts values from a predefined dictionary of choices. The dictionary maps from valid input choices to the cleaned value returned.
For example:
>>> field = ChoiceMapField({1: 'one', 2: 'two', 3: 'three'}) >>> field.clean(1) 'one' >>> field.clean("one") valedictory.exceptions.ValidationException: Not a valid choice
would only accept one of the numbers 1, 2 or 3 as input, and would return one of the strings “one”, “two”, or “three”.
-
choices
= set()¶ The field will only accept data if the value is in this set.
-
default_error_messages
¶ - invalid_choice
- Raised when the value is not one of the valid choices
-
PunctuatedCharacterField¶
-
class
valedictory.fields.
PunctuatedCharacterField
(alphabet=None, punctuation=None, min_length=None, max_length=None, **kwargs)[source]¶ A field that accepts characters only from an alphabet of allowed characters. A set of allowed punctuation characters are allowed and discarded when cleaned.
-
alphabet
¶ A string of all the allowed characters, not including
punctuation
characters. The cleaned output will consist only of characters from this string.
-
punctuation
¶ A string of all the punctuation characters allowed. Punctuation characters will be removed from the cleaned output.
-
min_length
= 0¶ The minimum length of the cleaned output data, not including punctuation characters. There is no minimum length by default.
-
max_length
= inf¶ The maximum length of the cleaned output data, not including punctuation characters. There is no maximum length by default.
-
default_error_messages
¶ - allowed_characters
- Raised when characters not in
alphabet
orpunctuation
are in the input. - min_length
- Raised when the cleaned string is shorter than
min_length
. - max_length
- Raised when the cleaned string is longer than
max_length
.
-
RestrictedCharacterField¶
-
class
valedictory.fields.
RestrictedCharacterField
(alphabet=None, punctuation=None, min_length=None, max_length=None, **kwargs)[source]¶ A field that only allows a defined alphabet of characters to be used.
This is just a
PunctuatedCharacterField
, withpunctuation
set to the empty string.-
alphabet
¶ A string of the characters allowed in the input. If the input contains a character not in this string, a
ValidationException
is raised.
-
DigitField¶
CreditCardField¶
-
class
valedictory.fields.
CreditCardField
(alphabet=None, punctuation=None, min_length=None, max_length=None, **kwargs)[source]¶ Accepts credit card numbers. The credit card numbers are checked using the Luhn checksum.
The credit card number can optionally be punctuated by ” -“ characters.
-
default_error_messages
¶ - luhn_checksum
- Raised when the credit card is not valid, according to the Luhn checksum
-
ListField¶
-
class
valedictory.fields.
ListField
(field=None, **kwargs)[source]¶ A list field validates all elements of a list against a field. For example, to accept a list of integers, you could declare a
ListField
like:class MyValidator(Validator): numbers = ListField(IntegerField())
-
field
¶ The field to validate all elements of the input data against.
-
NestedValidator¶
-
class
valedictory.fields.
NestedValidator
(validator=None, **kwargs)[source]¶ Nested validators allow nesting dicts inside one another. A validator is used to validate and clean the nested dict. To validate a person with structured address data, you could make a
Validator
like:class AddressValidator(Validator): street = StringField(min_length=1) suburb = StringField(min_length=1) postcode = DigitField(min_length=4, max_length=4) state = ChoiceField('ACT NSW NT QLD SA TAS VIC WA'.split()) class Person(Validator): name = StringField() address = NestedValidator(AddressValidator())
This would accept data like:
{ "name": "Alex Smith", "address": { "street": "123 Example Street", "suburb": "Example Burb", "postcode": "7123", "state": "TAS" } }