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