Jump to >

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.

name = None[source]

The localized name of the field type.

This should be in sentence casing.

__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 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.
__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:unicode
class NonRequestFieldTypeMixin[source]

Bases: object

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]

Bases: djblets.webapi.fields.BaseAPIFieldType

A field type for boolean values.

name = u'Boolean'[source]
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]

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.

name = u'Choice'[source]
__init__(*args, **kwargs)[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.

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.
__str__()[source]

Return a string representation of the field type.

Returns:A string representation of this field type.
Return type:unicode
class DateTimeFieldType(field_info)[source]

Bases: djblets.webapi.fields.BaseAPIFieldType

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

name = u'ISO 8601 Date/Time'[source]
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.

name = u'Dictionary'[source]
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.

name = u'Uploaded file'[source]
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]

Bases: djblets.webapi.fields.BaseAPIFieldType

A field type for integer values.

name = u'Integer'[source]
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.

name = u'List'[source]
__init__(*args, **kwargs)[source]

Initialize the field type.

Parameters:
  • *args (tuple) – Positional arguments for the parent constructor.
  • **kwargs (dict) – Keyword arguments for the parent constructor.
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.

__str__()[source]

Return a string representation of the field type.

Returns:A string representation of this field type.
Return type:unicode
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 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 = u'Resource'[source]
__init__(*args, **kwargs)[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.
__str__()[source]

Return a string representation of the field type.

Returns:A string representation of this field type.
Return type:unicode
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 override clean_value() to safely handle client requests.

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

name = u'Resource List'[source]
__str__()[source]

Return a string representation of the field type.

Returns:A string representation of this field type.
Return type:unicode
class StringFieldType(field_info)[source]

Bases: djblets.webapi.fields.BaseAPIFieldType

A field type for string values.

name = u'String'[source]
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