djblets.webapi.fields¶
Representations of field types in the API.
-
class
BaseAPIFieldType
(field_info)[source]¶ Bases:
object
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.
-
__init__
(field_info)[source]¶ Initialize the field type.
Subclasses should override this if they need to look up any values from the field information dictionary.
Parameters: field_info (dict) – Information defined for a field.
-
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.POST
orrequest.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
None
if 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.
Parameters: key (unicode) – The name of the key. Returns: The value for the key. Return type: object Raises: KeyError
– The key was not found in the field information dictionary.
-
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: object Raises: django.core.exceptions.ValidationError
– The value is not valid for this field type.
-
-
class
NonRequestFieldTypeMixin
[source]¶ Bases:
object
Mixin for field types not intended to handle values from requests.
-
class
BooleanFieldType
(field_info)[source]¶ Bases:
djblets.webapi.fields.BaseAPIFieldType
A field type for boolean values.
-
class
ChoiceFieldType
(*args, **kwargs)[source]¶ Bases:
djblets.webapi.fields.BaseAPIFieldType
A field type for a fixed choice of strings.
This takes a
choices
key in the field information dictionary, which specifies a list of values accepted during validation.-
__init__
(*args, **kwargs)[source]¶ Initialize the field type.
Parameters: Raises: KeyError
– The “choices” key was not found in the field information.
-
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: object Raises: django.core.exceptions.ValidationError
– The value is not one of the valid choices.
-
-
class
DateTimeFieldType
(field_info)[source]¶ Bases:
djblets.webapi.fields.BaseAPIFieldType
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.datetime
or an ISO 8601 date/time string.Returns: The resulting date/time value. Return type: datetime.datetime 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]¶ Bases:
djblets.webapi.fields.BaseAPIFieldType
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 dict
or JSON string representing a dictionary.Returns: The resulting dictionary value. Return type: dict 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]¶ Bases:
djblets.webapi.fields.BaseAPIFieldType
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.POST
orrequest.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
, orNone
if not found.Return type:
-
-
class
IntFieldType
(field_info)[source]¶ Bases:
djblets.webapi.fields.BaseAPIFieldType
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: int Raises: django.core.exceptions.ValidationError
– The value is not a valid integer.
-
-
class
ListFieldType
(*args, **kwargs)[source]¶ Bases:
djblets.webapi.fields.BaseAPIFieldType
A field type for list-based values.
This takes an optional
items
key 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
list
or 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]¶ Bases:
djblets.webapi.fields.NonRequestFieldTypeMixin
,djblets.webapi.fields.BaseAPIFieldType
A field type for referencing a resource.
This is intended purely for the
Resource.fields
list, 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.
-
__init__
(*args, **kwargs)[source]¶ Initialize the field type.
Parameters: Raises: ImportError
– The resource class could not be imported.KeyError
– The “resource” key was not found in the field information.
-
-
class
ResourceListFieldType
(*args, **kwargs)[source]¶ Bases:
djblets.webapi.fields.ResourceFieldType
A field type for referencing a list of a type of resource.
This is intended purely for the
Resource.fields
list, 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.
-
class
StringFieldType
(field_info)[source]¶ Bases:
djblets.webapi.fields.BaseAPIFieldType
A field type for string values.