djblets.webapi.resources.mixins.forms¶

Mixins for integrating a web API resource with a form.

class UpdateFormMixin[source]¶

Bases: object

A mixin for providing the ability to create and update using a form.

A WebAPIResource class using this mixin must set the form_class attribute to a ModelForm instance that corresponds to the model being updated.

Classes using this mixin can provide methods of the form parse_field_name_field to do parsing of form data before it is passed to the form. Parser methods should be of the form:

def parse_some_field(self, value, request, **kwargs):
    return some_value

These methods may return either a single value or a list of values (in the case where the corresponding field expects a list of values, such as a ModelMultipleChoiceField). They may also raise a ValidationError, though it’s up to the caller of create_form() to catch this and return any suitable errors.

Most implementations will want to call handle_form_request() in their POST/PUT handlers, and override behavior with the parsing methods. Some may also want to override save_form(), build_form_success_response(), or build_form_error_response() to customize behavior.

form_class = None[source]¶

The form class for updating models.

This should be a subclass of django.forms.ModelForm.

property add_form_class[source]¶

The form class for creating new models.

This should be a subclass of django.forms.ModelForm. It defaults to form_class.

handle_form_request(request, data=None, files=None, instance=None, form_kwargs=None, save_kwargs=None, **kwargs)[source]¶

Handle an HTTP request for creating or updating through a form.

This can be called directly from a resource’s create() or update() method to parse request data, create the form, and handle errors or the saving of the form.

New in version 1.0.9.

Parameters:

• request (django.http.HttpRequest) – The HTTP request from the client.

• data (dict, optional) – The data to pass to create_form().

• files (dict, optional) – Files to pass to the form.

• instance (django.db.models.Model, optional) – An existing instance to update, if performing an HTTP PUT request.

• form_kwargs (dict, optional) – Keyword arguments to pass to the form’s constructor.

• save_kwargs (dict, optional) – Keyword arguments to pass to the form’s ModelForm.save() method.

• **kwargs (dict) – Keyword arguments to pass to build_form_error_response(), build_form_success_response(), create_form(), save_form(), and any field parsing methods.

Returns:

The response to send back to the client.

Return type:

tuple or django.http.HttpResponse

create_form(data, request, files=None, instance=None, form_kwargs=None, **kwargs)[source]¶

Create a new form and pre-fill it with data.

Changed in version 1.0.9: The initial values for form fields are now automatically provided in the form data, if not otherwise overridden, making it easier to construct forms.

Along with this, a ModelForm’s fields and exclude lists are now factored in when populating the formw with an instance’s data.

Parameters:

• data (dict) – The request data to pass to the form.

• request (django.http.HttpRequest) – The HTTP request.

• files (dict) – Files to pass to the form.

• instance (django.db.models.Model, optional) – The instance model, if it exists. If this is not None, fields that appear in the form class’s fields attribute that do not appear in the data dict as keys will be copied from the instance.

• form_kwargs (dict, optional) – Additional keyword arguments to provide to the form’s constructor.

• **kwargs (dict) –

  Additional arguments. These will be passed to the resource’s parser methods.

  This contains anything passed as keyword arguments to handle_form_request().

Returns:

The form with data filled.

Return type:

django.forms.ModelForm

Raises:

django.core.exceptions.ValidationError – A field failed validation. This is allowed to be raised by any parse_* methods defined on the resource.

save_form(form, save_kwargs=None, **kwargs)[source]¶

Save and return the results of the form.

This is a simple wrapper around calling ModelForm.save(). It can be overridden by subclasses that need to perform additional operations on the instance or form.

New in version 1.0.9.

Parameters:

• form (django.forms.Form) – The form to save.

• save_kwargs (dict) – Any keyword arguments to pass when saving the form.

• **kwargs (dict) – Additional keyword arguments passed by the caller. This contains anything passed as keyword arguments to handle_form_request().

Returns:

The saved model instance.

Return type:

django.db.models.Model

build_form_errors(form=None, errors=None, **kwargs)[source]¶

Return a dictionary of field errors for use in a response payload.

This will convert each error to a string, resulting in a dictionary mapping field names to lists of errors. This can be safely returned in any API payload.

New in version 1.0.9.

Parameters:

• form (django.forms.Form, optional) – The form containing errors. This may be None if handling a ValidationError from field parsing.

• errors (django.core.exceptions.ValidationError, optional) – An explicit validation error to use for the payload. This will be used if field parsing fails.

• **kwargs (dict) – Additional keyword arguments passed by the caller. This contains anything passed as keyword arguments to handle_form_request().

Returns:

The dictionary of errors. Each key is a field name and each value is a list of error strings.

Return type:

dict

build_form_success_response(form, instance, is_created, **kwargs)[source]¶

Return a success response for a saved instance.

New in version 1.0.9.

Parameters:

• form (django.forms.Form) – The form that saved the instance.

• instance (django.db.models.Model) – The saved instance.

• is_created (bool) – Whether the instance was created.

• **kwargs (dict) – Additional keyword arguments passed by the caller. This contains anything passed as keyword arguments to handle_form_request().

Returns:

The success response to return from the API handler.

Return type:

tuple or django.http.HttpResponse

build_form_error_response(form=None, errors=None, instance=None, **kwargs)[source]¶

Return an error response containing errors for form fields.

New in version 1.0.9.

Parameters:

• form (django.forms.Form, optional) – The form containing errors. This may be None if handling a ValidationError from field parsing.

• errors (django.core.exceptions.ValidationError, optional) – An explicit validation error to use for the payload. This will be used if field parsing fails.

• instance (django.db.models.Model, optional) – The existing instance, if any.

• **kwargs (dict) – Additional keyword arguments passed by the caller. This contains anything passed as response_kwargs to handle_form_request().

Returns:

The error response to return from the API handler.

Return type:

tuple or django.http.HttpResponse