djblets.webapi.fields¶
Representations of field types in the API.
- class BaseAPIFieldType(field_info)[source]¶
Base class for a field type for an API.
This is responsible for defining the requirements of a field and to validate and normalize a value provided by a client of the API, for storage or processing.
- get_value_from_data(name, fields_data, files_data)[source]¶
Return a value from the data from a request.
- Parameters
name (unicode) – The name of the entry in the API request to retrieve data for.
fields_data (dict) – A dictionary of data provided in the request for standard fields. This is usually
request.POSTorrequest.GET.files_data (dict) – A dictionary of data provided in the request for uploaded files. This is usually
request.FILES.
- Returns
The value from one of the dictionaries, or
Noneif not found.- Return type
- get_field_info_key(key)[source]¶
Return the value for a key in the field information dictionary.
This will return a consistent error if the key is not found.
- clean_value(value)[source]¶
Validate and return a normalized result from the given value.
By default, this just returns the provided value. Subclasses should override this to perform normalization.
- Parameters
value (object) – The value to validate and normalize.
- Returns
The normalized value.
- Return type
- Raises
django.core.exceptions.ValidationError – The value is not valid for this field type.
- class NonRequestFieldTypeMixin[source]¶
Mixin for field types not intended to handle values from requests.
- class ChoiceFieldType(*args, **kwargs)[source]¶
A field type for a fixed choice of strings.
This takes a
choiceskey in the field information dictionary, which specifies a list of values accepted during validation.- clean_value(value)[source]¶
Validate and return a normalized result from the given value.
This will return the value if it’s a valid choice.
- Parameters
value (object) – The value to validate and normalize.
- Returns
The value, if it’s a valid choice.
- Return type
- Raises
django.core.exceptions.ValidationError – The value is not one of the valid choices.
- class DateTimeFieldType(field_info)[source]¶
A field type for representing date/times in ISO 8601 format.
- clean_value(value)[source]¶
Validate and return a datetime from an ISO 8601 value.
- Parameters
value (object) – The value to validate and normalize. This should be a
datetime.datetimeor an ISO 8601 date/time string.- Returns
The resulting date/time value.
- Return type
- Raises
django.core.exceptions.ValidationError – The resulting value was not a valid ISO 8601 date/time string or the time was ambiguous.
- class DictFieldType(field_info)[source]¶
A field type for dictionary-based values.
- clean_value(value)[source]¶
Validate and return a dictionary from a dictionary or JSON value.
- Parameters
value (object) – The value to validate and normalize. This should be a
dictor JSON string representing a dictionary.- Returns
The resulting dictionary value.
- Return type
- Raises
django.core.exceptions.ValidationError – The resulting value was not a dictionary. Either the value provided was of an invalid type or the parsed JSON data did not result in a dictionary.
- class FileFieldType(field_info)[source]¶
A field type for uploaded files.
- get_value_from_data(name, fields_data, files_data)[source]¶
Return a value from the uploaded files from a request.
- Parameters
name (unicode) – The name of the entry in the API request to retrieve data for.
fields_data (dict, unused) – A dictionary of data provided in the request for standard fields. This is usually
request.POSTorrequest.GET.files_data (dict) – A dictionary of data provided in the request for uploaded files. This is usually
request.FILES.
- Returns
The value from
files_data, orNoneif not found.- Return type
- class IntFieldType(field_info)[source]¶
A field type for integer values.
- clean_value(value)[source]¶
Validate and return an integer for a given value.
- Parameters
value (object) – The value to validate and normalize.
- Returns
The resulting integer value.
- Return type
- Raises
django.core.exceptions.ValidationError – The value is not a valid integer.
- class ListFieldType(*args, **kwargs)[source]¶
A field type for list-based values.
This takes an optional
itemskey in the field information dictionary, which is itself a field information dictionary for the type of item in the list. If provided, all values in a JSON list in the request payload will be cleaned using that item type. If not provided, the list will be allowed as-is.- clean_value(value)[source]¶
Validate and return a list from a list or JSON value.
- Parameters
value (object) – The value to validate and normalize. This should be a
listor JSON string representing a list.- Returns
The resulting list of optionally-cleaned items.
- Return type
- Raises
django.core.exceptions.ValidationError – This will be raised if the resulting value was not a dictionary. Either the value provided was of an invalid type or the parsed JSON data did not result in a dictionary. It may also be raised through the list item type’s validation.
- class ResourceFieldType(*args, **kwargs)[source]¶
A field type for referencing a resource.
This is intended purely for the
Resource.fieldslist, for the purpose of documentation. It’s generally not considered safe to let a client specify information like resources in a request. If needed, subclasses can overrideclean_value()to safely handle client requests.This expects a “resource” key in the field information. It can point to a resource class or instance, or a string path pointing to one.
- class ResourceListFieldType(*args, **kwargs)[source]¶
A field type for referencing a list of a type of resource.
This is intended purely for the
Resource.fieldslist, for the purpose of documentation. It’s generally not considered safe to let a client specify information like resources in a request. If needed, subclasses can overrideclean_value()to safely handle client requests.This expects a
"resource"key in the field information.