• Get Review Board
  • What's New
  • Products
  • Review Board Code review, image review, and document review
  • Documentation
  • Release Notes
  • Power Pack Enterprise integrations, reports, and enhanced document review
  • Try for 60 Days
  • Purchase
  • RBCommons Review Board as a Service, hosted by us
  • Pricing
  • RBTools Command line tools and Python API for Review Board
  • Documentation
  • Release Notes
  • Review Bot Automated code review, connecting tools you already use
  • Documentation
  • Release Notes
  • RB Gateway Manage Git and Mercurial repositories in your network
  • Documentation
  • Release Notes
  • Learn and Explore
  • What is Code Review?
  • Documentation
  • Frequently Asked Questions
  • Support Options
  • Third-Party Integrations
  • Demo
  • Review Board RBTools Power Pack Review Bot Djblets RB Gateway
    1. Djblets 5.x
    2. Version 5.x
    3. Version 4.x
    4. Version 3.x
    5. Version 2.x
    6. Version 2.0
    7. Version 1.0
    8. Version 0.9
    9. Djblets Documentation
    10. Module and Class References
    11. djblets.webapi.resources.mixins.forms
  • Home
  • Guides
  • Avatar Services Guides
  • Writing Avatar Services
  • Extension Guides
  • Writing Extensions
  • Testing Extensions
  • Feature Checks Guides
  • Introduction to Feature Checks
  • Writing Features
  • Writing Feature Checkers
  • Testing with Feature Checks
  • Integration Guides
  • Supporting Integrations
  • Writing Integrations
  • Privacy Compliance Guides
  • Getting and Checking Consent
  • Working with Personally Identifiable Information
  • Service Integrations
  • reCAPTCHA Guides
  • Using reCAPTCHA
  • Registries Guides
  • Writing Registries
  • Web API Guides
  • Writing Web API Resources
  • Adding OAuth2 Support
  • Module and Class References
  • djblets
  • djblets.deprecation
  • djblets.auth.forms
  • djblets.auth.ratelimit
  • djblets.auth.signals
  • djblets.auth.util
  • djblets.auth.views
  • djblets.avatars.errors
  • djblets.avatars.forms
  • djblets.avatars.registry
  • djblets.avatars.services
  • djblets.avatars.services.base
  • djblets.avatars.services.fallback
  • djblets.avatars.services.file_upload
  • djblets.avatars.services.gravatar
  • djblets.avatars.services.url
  • djblets.avatars.settings
  • djblets.cache.backend
  • djblets.cache.backend_compat
  • djblets.cache.context_processors
  • djblets.cache.errors
  • djblets.cache.forwarding_backend
  • djblets.cache.serials
  • djblets.cache.synchronizer
  • djblets.conditions
  • djblets.conditions.choices
  • djblets.conditions.conditions
  • djblets.conditions.errors
  • djblets.conditions.operators
  • djblets.conditions.values
  • djblets.configforms.forms
  • djblets.configforms.mixins
  • djblets.configforms.pages
  • djblets.configforms.registry
  • djblets.configforms.views
  • djblets.datagrid.grids
  • djblets.db.backends.mysql.base
  • djblets.db.fields
  • djblets.db.fields.base64_field
  • djblets.db.fields.comma_separated_values_field
  • djblets.db.fields.counter_field
  • djblets.db.fields.json_field
  • djblets.db.fields.modification_timestamp_field
  • djblets.db.fields.relation_counter_field
  • djblets.db.managers
  • djblets.db.query
  • djblets.db.query_catcher
  • djblets.db.query_comparator
  • djblets.db.validators
  • djblets.extensions.admin
  • djblets.extensions.errors
  • djblets.extensions.extension
  • djblets.extensions.forms
  • djblets.extensions.hooks
  • djblets.extensions.loaders
  • djblets.extensions.manager
  • djblets.extensions.middleware
  • djblets.extensions.models
  • djblets.extensions.packaging
  • djblets.extensions.resources
  • djblets.extensions.settings
  • djblets.extensions.signals
  • djblets.extensions.staticfiles
  • djblets.extensions.testing
  • djblets.extensions.testing.testcases
  • djblets.extensions.urls
  • djblets.extensions.views
  • djblets.extensions.templatetags.djblets_extensions
  • djblets.features
  • djblets.features.checkers
  • djblets.features.decorators
  • djblets.features.errors
  • djblets.features.feature
  • djblets.features.level
  • djblets.features.registry
  • djblets.features.testing
  • djblets.features.templatetags.features
  • djblets.forms.fields
  • djblets.forms.fieldsets
  • djblets.forms.forms
  • djblets.forms.forms.key_value_form
  • djblets.forms.widgets
  • djblets.gravatars
  • djblets.gravatars.templatetags.gravatars
  • djblets.http.middleware
  • djblets.http.responses
  • djblets.integrations.errors
  • djblets.integrations.forms
  • djblets.integrations.hooks
  • djblets.integrations.integration
  • djblets.integrations.manager
  • djblets.integrations.mixins
  • djblets.integrations.models
  • djblets.integrations.urls
  • djblets.integrations.views
  • djblets.log
  • djblets.log.middleware
  • djblets.log.siteconfig
  • djblets.log.urls
  • djblets.log.views
  • djblets.mail.dmarc
  • djblets.mail.message
  • djblets.mail.testing
  • djblets.mail.utils
  • djblets.markdown
  • djblets.markdown.extensions.escape_html
  • djblets.markdown.extensions.wysiwyg
  • djblets.markdown.extensions.wysiwyg_email
  • djblets.pipeline.compilers.es6
  • djblets.pipeline.compilers.less
  • djblets.pipeline.compilers.mixins
  • djblets.pipeline.compilers.rollup
  • djblets.pipeline.compilers.typescript
  • djblets.pipeline.settings
  • djblets.privacy.consent
  • djblets.privacy.consent.base
  • djblets.privacy.consent.common
  • djblets.privacy.consent.errors
  • djblets.privacy.consent.forms
  • djblets.privacy.consent.hooks
  • djblets.privacy.consent.registry
  • djblets.privacy.consent.tracker
  • djblets.privacy.models
  • djblets.privacy.pii
  • djblets.privacy.templatetags.djblets_privacy
  • djblets.recaptcha.mixins
  • djblets.recaptcha.siteconfig
  • djblets.recaptcha.templatetags.djblets_recaptcha
  • djblets.recaptcha.widgets
  • djblets.registries
  • djblets.registries.errors
  • djblets.registries.importer
  • djblets.registries.mixins
  • djblets.registries.registry
  • djblets.registries.signals
  • djblets.secrets
  • djblets.secrets.crypto
  • djblets.secrets.token_generators
  • djblets.secrets.token_generators.base
  • djblets.secrets.token_generators.legacy_sha1
  • djblets.secrets.token_generators.registry
  • djblets.secrets.token_generators.vendor_checksum
  • djblets.siteconfig
  • djblets.siteconfig.admin
  • djblets.siteconfig.context_processors
  • djblets.siteconfig.django_settings
  • djblets.siteconfig.forms
  • djblets.siteconfig.managers
  • djblets.siteconfig.middleware
  • djblets.siteconfig.models
  • djblets.siteconfig.signals
  • djblets.siteconfig.views
  • djblets.template.caches
  • djblets.template.context
  • djblets.template.loaders.conditional_cached
  • djblets.template.loaders.namespaced_app_dirs
  • djblets.testing.decorators
  • djblets.testing.testcases
  • djblets.testing.testrunners
  • djblets.urls.context_processors
  • djblets.urls.decorators
  • djblets.urls.patterns
  • djblets.urls.resolvers
  • djblets.urls.root
  • djblets.urls.staticfiles
  • djblets.util.compat.django.core.cache
  • djblets.util.compat.python.past
  • djblets.util.contextmanagers
  • djblets.util.dates
  • djblets.util.decorators
  • djblets.util.filesystem
  • djblets.util.functional
  • djblets.util.html
  • djblets.util.http
  • djblets.util.humanize
  • djblets.util.json_utils
  • djblets.util.properties
  • djblets.util.serializers
  • djblets.util.symbols
  • djblets.util.templatetags.djblets_deco
  • djblets.util.templatetags.djblets_email
  • djblets.util.templatetags.djblets_forms
  • djblets.util.templatetags.djblets_images
  • djblets.util.templatetags.djblets_js
  • djblets.util.templatetags.djblets_utils
  • djblets.util.typing
  • djblets.util.views
  • djblets.views.generic.base
  • djblets.views.generic.etag
  • djblets.webapi.auth
  • djblets.webapi.auth.backends
  • djblets.webapi.auth.backends.api_tokens
  • djblets.webapi.auth.backends.base
  • djblets.webapi.auth.backends.basic
  • djblets.webapi.auth.backends.oauth2_tokens
  • djblets.webapi.auth.views
  • djblets.webapi.decorators
  • djblets.webapi.encoders
  • djblets.webapi.errors
  • djblets.webapi.fields
  • djblets.webapi.managers
  • djblets.webapi.models
  • djblets.webapi.oauth2_scopes
  • djblets.webapi.resources
  • djblets.webapi.resources.base
  • djblets.webapi.resources.group
  • djblets.webapi.resources.registry
  • djblets.webapi.resources.root
  • djblets.webapi.resources.user
  • djblets.webapi.resources.mixins.api_tokens
  • djblets.webapi.resources.mixins.forms
  • djblets.webapi.resources.mixins.oauth2_tokens
  • djblets.webapi.resources.mixins.queries
  • djblets.webapi.responses
  • djblets.webapi.signals
  • djblets.webapi.testing
  • djblets.webapi.testing.decorators
  • djblets.webapi.testing.testcases
  • General Index
  • Python Module Index
  • Release Notes
  • 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

    Keep up with the latest Review Board releases, security updates, and helpful information.

    About
    News
    Demo
    RBCommons Hosting
    Integrations
    Happy Users
    Support Options
    Documentation
    FAQ
    User Manual
    RBTools
    Administration Guide
    Power Pack
    Release Notes
    Downloads
    Review Board
    RBTools
    Djblets
    Power Pack
    Package Store
    PGP Signatures
    Contributing
    Bug Tracker
    Submit Patches
    Development Setup
    Wiki
    Follow Us
    Mailing Lists
    Reddit
    Twitter
    Mastodon
    Facebook
    YouTube

    Copyright © 2006-2025 Beanbag, Inc. All rights reserved.

    Terms of Service — Privacy Policy — AI Ethics Policy — Branding

    On this page

    • [Top]
    • UpdateFormMixin
      • UpdateFormMixin.form_class
      • UpdateFormMixin.add_form_class
      • UpdateFormMixin.handle_form_request()
      • UpdateFormMixin.create_form()
      • UpdateFormMixin.save_form()
      • UpdateFormMixin.build_form_errors()
      • UpdateFormMixin.build_form_success_response()
      • UpdateFormMixin.build_form_error_response()