djblets.webapi.fields¶

Representations of field types in the API.

class ListFieldTypeItemsInfo[source]¶

Bases: TypedDict

Information on an item in a list for ListFieldType.

New in version 4.0.

type: Type¶

The type of item.

This can be any class type, including primitives or API field types.

__annotations__ = {'type': ForwardRef('Type', module='djblets.webapi.fields')}¶

__optional_keys__ = frozenset({})¶

__orig_bases__ = (<function TypedDict>,)¶

__required_keys__ = frozenset({'type'})¶

__total__ = True¶

class BaseAPIFieldType(field_info: _FieldInfo)[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.

name: Optional[StrOrPromise] = None¶

The localized name of the field type.

This should be in sentence casing.

Type:

str

__init__(field_info: _FieldInfo) → None[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.

field_info: _FieldInfo¶

Information defined for the field on the API resource.

Type:

dict

get_value_from_data(name: str, fields_data: _FieldsDict, files_data: _FilesDict) → Optional[object][source]¶

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 usually request.POST or request.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:

object

get_field_info_key(key: str) → Any[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 (str) – 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: Optional[Any]) → Any[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.

__str__() → str[source]¶

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:

str

__annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]'}¶

class NonRequestFieldTypeMixin[source]¶

Bases: object

Mixin for field types not intended to handle values from requests.

clean_value(value: Any) → Any[source]¶

Validate and return a normalized string result from a value.

Parameters:

value (object) – The value to normalize.

Raises:

NotImplementederror – An error describing that this field type cannot be used with request data.

class BooleanFieldType(field_info: _FieldInfo)[source]¶

Bases: BaseAPIFieldType

A field type for boolean values.

name: Optional[StrOrPromise] = 'Boolean'[source]¶

The localized name of the field type.

This should be in sentence casing.

Type:

str

clean_value(value: Any) → bool[source]¶

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.

Parameters:

value (object) – The value to normalize.

Returns:

The normalized boolean value.

Return type:

str

__annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]'}¶

class ChoiceFieldType(*args, **kwargs)[source]¶

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'[source]¶

The localized name of the field type.

This should be in sentence casing.

Type:

str

__init__(*args, **kwargs) → None[source]¶

Initialize the field type.

Parameters:

• *args (tuple) – Positional arguments for the parent constructor.

• **kwargs (dict) – Keyword arguments for the parent constructor.

Raises:

KeyError – The “choices” key was not found in the field information.

choices: Sequence[str]¶

clean_value(value: Any) → Any[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.

__str__() → str[source]¶

Return a string representation of the field type.

Returns:

A string representation of this field type.

Return type:

str

__annotations__ = {'choices': 'Sequence[str]', 'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]'}¶

class DateTimeFieldType(field_info: _FieldInfo)[source]¶

Bases: BaseAPIFieldType

A field type for representing date/times in ISO 8601 format.

name: Optional[StrOrPromise] = 'ISO 8601 Date/Time'[source]¶

The localized name of the field type.

This should be in sentence casing.

Type:

str

clean_value(value: Any) → datetime[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.

__annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]'}¶

class DictFieldType(field_info: _FieldInfo)[source]¶

Bases: BaseAPIFieldType

A field type for dictionary-based values.

name: Optional[StrOrPromise] = 'Dictionary'[source]¶

The localized name of the field type.

This should be in sentence casing.

Type:

str

clean_value(value: Any) → Mapping[Any, Any][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.

__annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]'}¶

class FileFieldType(field_info: _FieldInfo)[source]¶

Bases: BaseAPIFieldType

A field type for uploaded files.

name: Optional[StrOrPromise] = 'Uploaded file'[source]¶

The localized name of the field type.

This should be in sentence casing.

Type:

str

get_value_from_data(name: str, fields_data: _FieldsDict, files_data: _FilesDict) → Optional[UploadedFile][source]¶

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 usually request.POST or request.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, or None if not found.

Return type:

django.core.files.uploadedfile.UploadedFile

__annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]'}¶

class IntFieldType(field_info: _FieldInfo)[source]¶

Bases: BaseAPIFieldType

A field type for integer values.

name: Optional[StrOrPromise] = 'Integer'[source]¶

The localized name of the field type.

This should be in sentence casing.

Type:

str

clean_value(value: Any) → int[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.

__annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]'}¶

class ListFieldType(*args, **kwargs)[source]¶

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'[source]¶

The localized name of the field type.

This should be in sentence casing.

Type:

str

__init__(*args, **kwargs) → None[source]¶

Initialize the field type.

Parameters:

• *args (tuple) – Positional arguments for the parent constructor.

• **kwargs (dict) – Keyword arguments for the parent constructor.

item_info: Optional[ListFieldTypeItemsInfo]¶

Information on the type of item in the list.

Type:

dict

clean_value(value: Any) → Sequence[Any][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:

list

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[source]¶

Return a string representation of the field type.

Returns:

A string representation of this field type.

Return type:

str

__annotations__ = {'field_info': '_FieldInfo', 'item_info': 'Optional[ListFieldTypeItemsInfo]', 'name': 'Optional[StrOrPromise]'}¶

class ResourceFieldType(*args, **kwargs)[source]¶

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 override clean_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'[source]¶

The localized name of the field type.

This should be in sentence casing.

Type:

str

__init__(*args, **kwargs) → None[source]¶

Initialize the field type.

Parameters:

• *args (tuple) – Positional arguments for the parent constructor.

• **kwargs (dict) – Keyword arguments for the parent constructor.

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:

type

__str__() → str[source]¶

Return a string representation of the field type.

Returns:

A string representation of this field type.

Return type:

str

__annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]', 'resource': 'Type[WebAPIResource]'}¶

class ResourceListFieldType(*args, **kwargs)[source]¶

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 override clean_value() to safely handle client requests.

This expects a "resource" key in the field information.

name: Optional[StrOrPromise] = 'Resource List'[source]¶

The localized name of the field type.

This should be in sentence casing.

Type:

str

__annotations__ = {'field_info': '_FieldInfo', 'name': 'Optional[StrOrPromise]', 'resource': 'Type[WebAPIResource]'}¶

__str__() → str[source]¶

Return a string representation of the field type.

Returns:

A string representation of this field type.

Return type:

str

class StringFieldType(field_info: _FieldInfo)[source]¶

Bases: BaseAPIFieldType

A field type for string values.

__annotations__ = {}¶

name: Optional[StrOrPromise] = 'String'[source]¶

The localized name of the field type.

This should be in sentence casing.

Type:

str

clean_value(value: Any) → str[source]¶

Validate and return a normalized string result from a value.

Parameters:

value (object) – The value to normalize.

Returns:

A string version of the value.

Return type:

str