djblets.webapi.fields¶
Representations of field types in the API.
- class ListFieldTypeItemsInfo¶
Bases:
TypedDict
Information on an item in a list for ListFieldType.
New in version 4.0.
- __annotations__ = {'type': ForwardRef('Type', module='djblets.webapi.fields')}¶
- __closed__ = False¶
- __extra_items__ = None¶
- __mutable_keys__ = frozenset({'type'})¶
- __optional_keys__ = frozenset({})¶
- __orig_bases__ = (<function TypedDict>,)¶
- __readonly_keys__ = frozenset({})¶
- __required_keys__ = frozenset({'type'})¶
- __total__ = True¶
- class BaseAPIFieldType(field_info: _FieldInfo)¶
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.
- name: Optional[StrOrPromise] = None¶
The localized name of the field type.
This should be in sentence casing.
- Type:
- __init__(field_info: _FieldInfo) None ¶
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: str, fields_data: _FieldsDict, files_data: _FilesDict) Optional[object] ¶
Return a value from the data from a request.
- Parameters:
name (
str
) – 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 usuallyrequest.POST
orrequest.GET
.files_data (
dict
) – A dictionary of data provided in the request for uploaded files. This is usuallyrequest.FILES
.
- Returns:
The value from one of the dictionaries, or
None
if not found.- Return type:
- get_field_info_key(key: str) Any ¶
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: Optional[Any]) Any ¶
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.
- __str__() str ¶
Return a string representation of the field type.
This should return a string summary suitable for human consumption.
- Returns:
A string representation of this field type.
- Return type:
- __annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]'}¶
- class NonRequestFieldTypeMixin¶
Bases:
object
Mixin for field types not intended to handle values from requests.
- class BooleanFieldType(field_info: _FieldInfo)¶
Bases:
BaseAPIFieldType
A field type for boolean values.
- name: Optional[StrOrPromise] = 'Boolean'¶
The localized name of the field type.
This should be in sentence casing.
- Type:
- clean_value(value: Any) bool ¶
Validate and return a boolean result from a value.
This treats
1
,"1"
,True
, or"true"
(case-insensitive) as truthy values, and everything else as a falsy value.
- __annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]'}¶
- class ChoiceFieldType(*args, **kwargs)¶
Bases:
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.- name: Optional[StrOrPromise] = 'Choice'¶
The localized name of the field type.
This should be in sentence casing.
- Type:
- clean_value(value: Any) Any ¶
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.
- __str__() str ¶
Return a string representation of the field type.
- Returns:
A string representation of this field type.
- Return type:
- __annotations__ = {'choices': 'Sequence[str]', 'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]'}¶
- class DateTimeFieldType(field_info: _FieldInfo)¶
Bases:
BaseAPIFieldType
A field type for representing date/times in ISO 8601 format.
- name: Optional[StrOrPromise] = 'ISO 8601 Date/Time'¶
The localized name of the field type.
This should be in sentence casing.
- Type:
- clean_value(value: Any) datetime ¶
Validate and return a datetime from an ISO 8601 value.
- Parameters:
value (
object
) – The value to validate and normalize. This should be adatetime.datetime
or 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.
- __annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]'}¶
- class DictFieldType(field_info: _FieldInfo)¶
Bases:
BaseAPIFieldType
A field type for dictionary-based values.
- name: Optional[StrOrPromise] = 'Dictionary'¶
The localized name of the field type.
This should be in sentence casing.
- Type:
- clean_value(value: Any) Mapping[Any, Any] ¶
Validate and return a dictionary from a dictionary or JSON value.
- Parameters:
value (
object
) – The value to validate and normalize. This should be adict
or 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.
- __annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]'}¶
- class FileFieldType(field_info: _FieldInfo)¶
Bases:
BaseAPIFieldType
A field type for uploaded files.
- name: Optional[StrOrPromise] = 'Uploaded file'¶
The localized name of the field type.
This should be in sentence casing.
- Type:
- get_value_from_data(name: str, fields_data: _FieldsDict, files_data: _FilesDict) Optional[UploadedFile] ¶
Return a value from the uploaded files from a request.
- Parameters:
name (
str
) – 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 usuallyrequest.POST
orrequest.GET
.files_data (
dict
) – A dictionary of data provided in the request for uploaded files. This is usuallyrequest.FILES
.
- Returns:
The value from
files_data
, orNone
if not found.- Return type:
- __annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]'}¶
- class IntFieldType(field_info: _FieldInfo)¶
Bases:
BaseAPIFieldType
A field type for integer values.
- name: Optional[StrOrPromise] = 'Integer'¶
The localized name of the field type.
This should be in sentence casing.
- Type:
- clean_value(value: Any) int ¶
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.
- __annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]'}¶
- class ListFieldType(*args, **kwargs)¶
Bases:
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.- name: Optional[StrOrPromise] = 'List'¶
The localized name of the field type.
This should be in sentence casing.
- Type:
- item_info: Optional[ListFieldTypeItemsInfo]¶
Information on the type of item in the list.
- Type:
- clean_value(value: Any) Sequence[Any] ¶
Validate and return a list from a list or JSON value.
- Parameters:
value (
object
) – The value to validate and normalize. This should be alist
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.
- __str__() str ¶
Return a string representation of the field type.
- Returns:
A string representation of this field type.
- Return type:
- __annotations__ = {'field_info': '_FieldInfo', 'item_info': 'Optional[ListFieldTypeItemsInfo]', 'name': 'Optional[StrOrPromise]'}¶
- class ResourceFieldType(*args, **kwargs)¶
Bases:
NonRequestFieldTypeMixin
,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.
- name: Optional[StrOrPromise] = 'Resource'¶
The localized name of the field type.
This should be in sentence casing.
- Type:
- __init__(*args, **kwargs) None ¶
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.
- resource: Type[WebAPIResource]¶
The resource referenced by this field.
- Type:
- __str__() str ¶
Return a string representation of the field type.
- Returns:
A string representation of this field type.
- Return type:
- __annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]', 'resource': 'Type[WebAPIResource]'}¶
- class ResourceListFieldType(*args, **kwargs)¶
Bases:
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.- name: Optional[StrOrPromise] = 'Resource List'¶
The localized name of the field type.
This should be in sentence casing.
- Type:
- __annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]', 'resource': 'Type[WebAPIResource]'}¶
- class StringFieldType(field_info: _FieldInfo)¶
Bases:
BaseAPIFieldType
A field type for string values.
- __annotations__ = {}¶
- name: Optional[StrOrPromise] = 'String'¶
The localized name of the field type.
This should be in sentence casing.
- Type: