Jump to >

This documentation covers the in-development release of Djblets. You can see the latest stable docs or all previous versions.

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.

name = None[source]

The localized name of the field type.

This should be in sentence casing.

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 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)[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]

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

clean_value(value)[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)[source]

A field type for boolean values.

clean_value(value)[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

unicode

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

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.

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]

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]

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]

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 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

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

int

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 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

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.

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

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.

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

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.

class StringFieldType(field_info)[source]

A field type for string values.

clean_value(value)[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

unicode