reviewboard.webapi.mixins¶

class MarkdownFieldsMixin[source]¶

Bases: object

Mixes in common logic for Markdown text fields.

Any resource implementing this is assumed to have at least one Markdown-capable text field.

Clients can pass ?force-text-type= (for GET) or force_text_type= (for POST/PUT) with a value of plain, markdown or html to return the given text fields in the payload using the requested format.

When markdown is specified, the Markdown text fields will return valid Markdown content, escaping if necessary.

When plain is specified, plain text will be returned instead. If the content was in Markdown before, this will unescape the content.

When html is specified, the content will be transformed into HTML suitable for display.

Clients can also pass ?include-text-types=<type1>[,<type2>,...] (for GET) or include_text_types=<type1>[,<type2>,...] (for POST/PUT) to return the text fields within special type_text_fields entries in the resource payload. A special type of “raw” is allowed, which will return the text types stored in the database.

(Note that passing ?include-text-types=raw is equivalent to passing ?include-raw-text-fields=1 in 2.0.9 and 2.0.10. The latter is deprecated.)

TEXT_TYPE_PLAIN = 'plain'[source]¶

TEXT_TYPE_MARKDOWN = 'markdown'[source]¶

TEXT_TYPE_HTML = 'html'[source]¶

TEXT_TYPE_RAW = 'raw'[source]¶

TEXT_TYPES = ('plain', 'markdown', 'html')[source]¶

SAVEABLE_TEXT_TYPES = ('plain', 'markdown')[source]¶

INCLUDEABLE_TEXT_TYPES = ('plain', 'markdown', 'html', 'raw')[source]¶

DEFAULT_EXTRA_DATA_TEXT_TYPE = 'markdown'[source]¶

serialize_object(obj, *args, **kwargs)[source]¶

Serializes the object, transforming text fields.

This is a specialization of serialize_object that transforms any text fields that support text types. It also handles attaching the raw text to the payload, on request.

serialize_text_type_field(obj, request=None, **kwargs)[source]¶

can_import_extra_data_field(obj, field)[source]¶

Returns whether a particular field in extra_data can be imported.

If an extra_data field is marked as supporting rich text, we’ll skip importing it through normal means. Instead, it will be handled separately later.

get_extra_data_field_supports_markdown(obj, key)[source]¶

Returns whether a particular field in extra_data supports Markdown.

If the field supports Markdown text, the value will be normalized based on the requested ?force-text-type= parameter.

set_text_fields(obj, text_field, rich_text_field_name=None, text_type_field_name=None, text_model_field=None, **kwargs)[source]¶

Normalize Markdown-capable text fields that are being saved.

Parameters:

• obj (django.db.models.Model) – The object containing Markdown-capable fields to modify.

• text_field (unicode) – The key from kwargs containing the new value for the text fields.

• rich_text_field_name (unicode, optional) –

  The name of the boolean field on obj representing the rich text state.

  If not provided, a name will be generated based on the value of text_field ('rich_text' if text_field is 'text', or text_field_rich_text otherwise).

• text_type_field_name (unicode, optional) –

  The key from kwargs containing the text type.

  If not provided, a name will be generated based on the value of text_field ('text_type' if text_field is 'text', or text_field_text_type otherwise).

• text_model_field (unicode, optional) –

  The name of the text field on obj.

  If not provided, text_field will be used for the value.

• **kwargs (dict) –

  Any fields passed by the client. These should be values corresponding to text_type_field_name and text_field in here.

  This may also contain a legacy value of 'text_type', which will be used if text_type_field_name is not present.

Returns:

The fields on obj that were set based on the request.

Return type:

set

set_extra_data_text_fields(obj, text_field, extra_fields, **kwargs)[source]¶

Normalize Markdown-capable text fields in extra_data.

This will check if any Markdown-capable text fields in extra_data have been changed (either by changing the text or the text type), and handle the saving of the text and type.

This works just like set_text_fields(), but specially handles how things are stored in extra_data (text_type vs. rich_text fields, possible lack of presence of a text_type field, etc.).

Parameters:

• obj (django.db.models.Model) – The object containing Markdown-capable fields to modify.

• text_field (unicode) – The key from kwargs containing the new value for the text fields.

• extra_fields (dict) – Fields passed to the API resource that aren’t natively handled by that resource. These may contain extra_data.-prefixed keys.

• **kwargs (dict) – Any fields passed by the client. This may be checked for a legacy text_type field.

Returns:

The keys in extra_data that were set based on the request.

Return type:

set

class UpdateFormMixin[source]¶

Bases: UpdateFormMixin

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. These methods may return either a single value or a list (in the case where the corresponding field expects a list of values, such as a django.forms.ModelMultipleChoiceField).

The create_form() and save_form() methods should be used for creating new form instances and saving them. A form created this way can be given an optional instance argument to allow for updating the instance. Any fields missing from data (but appearing in the form_class’s fields attribute) will be copied over from the instance.

handle_form_request(**kwargs)[source]¶

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

This simply wraps the parent method and handles ImportExtraDataError exceptions during form save.

Parameters:

**kwargs (dict) – Keyword arguments to pass to the parent method.

Returns:

The response to send back to the client.

Return type:

tuple or django.http.HttpResponse

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

Save the form and extra data.

Parameters:

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

• save_kwargs (dict) – Additional keyword arguments to pass to the ModelForm.save().

• extra_fields (dict, optional) – The extra data to save on the object. These should be key-value pairs in the form of extra_data.key = value.

• **kwargs (dict) – Additional keyword arguments to pass to the parent method.

Returns:

The saved model instance.

Return type:

django.db.models.Model

Raises:

reviewboard.webapi.base.ImportExtraDataError – Extra data failed to import. The form will not be saved.