reviewboard.reviews.fields¶

class BaseReviewRequestFieldSet(review_request_details)[source]¶

Bases: object

Base class for sets of review request fields.

A fieldset stores a list of fields that are rendered on the review request page. They may contain default fields, and new fields can be added or removed.

Review Board provides three main fieldsets: “main”, “info”, and “reviewers”. Others can be added by subclassing and registering through register_review_request_fieldset.

fieldset_id = None[source]¶

label = None[source]¶

show_required = False[source]¶

field_classes = None[source]¶

tag_name = None[source]¶

__init__(review_request_details)[source]¶

classmethod is_empty()[source]¶

Returns whether the fieldset is empty.

A fieldset is empty if there are no field classes registered. An empty fieldset will not be displayed on the page.

classmethod add_field(field_cls)[source]¶

Adds a field class to this fieldset.

The field will be rendered inside this fieldset on the page.

A given field class can only be in one fieldset. Its field_id must be unique.

classmethod remove_field(field_cls)[source]¶

Removes a field class from this fieldset.

The field class must have been previously added to this fieldset.

class BaseReviewRequestField(review_request_details, request=None)[source]¶

Bases: object

Base class for a field on a review request.

A field is responsible for displaying data from a review request, handling any editing requirements if necessary, recording changes in the ChangeDescription, and rendering those changes.

Each field must have its own unique field_id. This ID will be used when looking up or storing the field’s value.

It is recommended that fields provided by extensions prefix their field ID with some sort of identifier for the extension or the vendor.

Creating a new field requires subclassing BaseReviewRequestField and overriding any fields or functions necessary. Its class must then be added to a fieldset.

A field will be instantiated with either a ReviewRequest or a ReviewRequestDraft, depending on what is being edited. This is stored in review_request_details. Functions should optimistically fetch values from that, if possible. They can call get_review_request() on review_request_details to fetch the actual ReviewRequest.

If the function takes a review_request_details parameter, it must use that instead.

field_id = None[source]¶

label = None[source]¶

is_editable = False[source]¶

is_required = False[source]¶

default_css_classes = set([])[source]¶

change_entry_renders_inline = True[source]¶

model = None[source]¶

can_record_change_entry[source]¶

__init__(review_request_details, request=None)[source]¶

value[source]¶

Returns the value loaded from the database.

This will fetch the value with the associated ReviewRequest or ReviewRequestDraft, and then cache it for future lookups.

has_value_changed(old_value, new_value)[source]¶

Returns whether the value has changed.

By default, it performs an inequality check on the values. This can be overridden to perform more specialized checks.

record_change_entry(changedesc, old_value, new_value)[source]¶

Records information on the changed values in a ChangeDescription.

By default, the values are stored as-is along with the field ID. This can be overridden to perform more specialized storage.

serialize_change_entry(changedesc)[source]¶

Serialize a change entry for public consumption.

This will output a version of the change entry for use in the API. It can be the same content stored in the ChangeDescription, but does not need to be.

Parameters:	changedesc (reviewboard.changedescs.models.ChangeDescription) – The change description whose field is to be serialized.
Returns:	An appropriate serialization for the field.
Return type:	dict

serialize_change_entry_for_model_list(field_info)[source]¶

Return the change entry for a list of models.

Parameters:	field_info (dict) – A dictionary describing how the field has changed. This is guaranteed to have new and old keys, but may also contain added and removed keys as well.
Returns:	A mapping of each key present in field_info to its list of model instances.
Return type:	dict

serialize_change_entry_for_singleton(field_info)[source]¶

Return the change entry for a singleton.

Singleton fields (e.g., summaries) are stored in ChangeDescriptions as a list with a single element.

Parameters:	field_info (dict) – A dictionary describing how the field has changed. This is guaranteed to have new and old keys, but may also contain added and removed keys as well.
Returns:	A mapping of each key in field_info to a single value.
Return type:	dict

serialize_change_entry_for_list(field_info)[source]¶

Return the change entry for a list of plain data.

Parameters:	field_info (dict) – A dictionary describing how the field has changed. This is guaranteed to have new and old keys, but may also contain added and removed keys as well.
Returns:	A mapping of each key in field_info to a list of values.
Return type:	dict

get_change_entry_sections_html(info)[source]¶

Returns sections of change entries with titles and rendered HTML.

By default, this just returns a single section for the field, with the field’s title and rendered change HTML.

Subclasses can override this to provide more information.

render_change_entry_html(info)[source]¶

Renders a change entry to HTML.

By default, this returns a simple “changed from X to Y” using the old and new values. This can be overridden to generate more specialized output.

This function is expected to return safe, valid HTML. Any values coming from a field or any other form of user input must be properly escaped.

Subclasses can override render_change_entry_value_html to change how the value itself will be rendered in the string.

render_change_entry_added_value_html(info, value)[source]¶

render_change_entry_removed_value_html(info, value)[source]¶

render_change_entry_value_html(info, value)[source]¶

Renders the value for a change description string to HTML.

By default, this just converts the value to text and escapes it. This can be overridden to customize how the value is displayed.

load_value(review_request_details)[source]¶

Loads a value from the review request or draft.

By default, this loads the value as-is from the extra_data field. This can be overridden if you need to deserialize the value in some way.

This must use review_request_details instead of self.review_request_details.

save_value(value)[source]¶

Saves the value in the review request or draft.

By default, this saves the value as-is in the extra_data field. This can be overridden if you need to serialize the value in some way.

propagate_data(review_request_details)[source]¶

Propagate data in from source review request or draft.

By default, this loads only the field’s value from a source review request or draft and saves it as-is into the review request or draft associated with the field. This can be overridden if you need to propagate additional data elements.

This method is preferable to explictly calling load_value() and save_value() in series to propagate data from a source into a field, because it allows for copying additional data elements beyond only the field’s value.

This function must use the review_request_details parameter instead of the review_request_details attribute on the field.

Parameters:	review_request_details (reviewboard.reviews.models.base_review_request_details) – The source review request or draft whose data is to be propagated.

render_value(value)[source]¶

Renders the value in the field.

By default, this converts to text and escapes it. This can be overridden if you need to render it in a more specific way.

This must use value instead of self.value.

should_render(value)[source]¶

Returns whether the field should be rendered.

By default, the field is always rendered, but this can be overridden if you only want to show under certain conditions (such as if it has a value).

This must use value instead of self.value.

get_css_classes()[source]¶

Returns the list of CSS classes to apply to the element.

By default, this will include the contents of default_css_classes, and required if it’s a required field.

This can be overridden to provide additional CSS classes, if they’re not appropraite for default_css_classes.

get_data_attributes()[source]¶

Returns any data attributes to include in the element.

By default, this returns nothing.

as_html()[source]¶

Returns the field rendered as HTML.

By default, this just calls render_value with the value from the database.

class BaseEditableField(review_request_details, request=None)[source]¶

Bases: reviewboard.reviews.fields.BaseReviewRequestField

Base class for an editable field.

This simply marks the field as editable.

default_css_classes = [u’editable’][source]¶

is_editable = True[source]¶

class BaseCommaEditableField(review_request_details, request=None)[source]¶

Bases: reviewboard.reviews.fields.BaseEditableField

Base class for an editable comma-separated list of values.

This is used for dealing with lists of items that appear comma-separated in the UI. It works with stored lists of content on the review request or draft, and on the ChangeDescription.

Subclasses can override this to provide specialized rendering on a per-item-basis. That’s useful for showing links to items, for example.

default_css_classes = [u’editable’, u’comma-editable’][source]¶

order_matters = False[source]¶

one_line_per_change_entry = True[source]¶

has_value_changed(old_value, new_value)[source]¶

Returns whether two values have changed.

If order_matters is set to True, this will do a strict list comparison. Otherwise, it will compare the items in both lists without caring about the ordering.

serialize_change_entry(changedesc)[source]¶

Serialize a change entry for public consumption.

This will output a version of the change entry for use in the API. It can be the same content stored in the ChangeDescription, but does not need to be.

Parameters:	changedesc (reviewboard.changedescs.models.ChangeDescription) – The change description whose field is to be serialized.
Returns:	An appropriate serialization for the field.
Return type:	dict

render_value(values)[source]¶

Renders the list of items.

This will call out to render_item for every item. The list of rendered items will be separated by a comma and a space.

render_item(item)[source]¶

Renders an item from the list.

By default, this will convert the item to text and then escape it.

render_change_entry_html(info)[source]¶

Renders a change entry to HTML.

By default, this returns HTML containing a list of removed items, and a list of added items. This can be overridden to generate more specialized output.

This function is expected to return safe, valid HTML. Any values coming from a field or any other form of user input must be properly escaped.

render_change_entry_value_html(info, values)[source]¶

Renders a list of items for change description HTML.

By default, this will call render_change_entry_item_html for every item in the list. The list of rendered items will be separated by a comma and a space.

render_change_entry_item_html(info, item)[source]¶

Renders an item for change description HTML.

By default, this just converts the value to text and escapes it. This can be overridden to customize how the value is displayed.

class BaseTextAreaField(review_request_details, request=None)[source]¶

Bases: reviewboard.reviews.fields.BaseEditableField

Base class for a multi-line text area field.

The text area can take either plain text or Markdown text. By default, Markdown is supported, but this can be changed by setting enable_markdown to False.

default_css_classes = [u’editable’, u’field-text-area’][source]¶

enable_markdown = True[source]¶

always_render_markdown = False[source]¶

tag_name = u’pre’[source]¶

text_type_key[source]¶

Decorator that converts a method with a single self argument into a property cached on the instance.

is_text_markdown(value)[source]¶

Returns whether the text is in Markdown format.

This can be overridden if the field needs to check something else to determine if the text is in Markdown format.

propagate_data(review_request_details)[source]¶

Propagate data in from source review request or draft.

In addition to the value propagation handled by the base class, this copies the text type details from a source review request or draft and saves it as-is into the review request or draft associated with the field.

Parameters:	review_request_details (reviewboard.reviews.models.base_review_request_details) – The source review request or draft whose data is to be propagated.

get_css_classes()[source]¶

Returns the list of CSS classes.

If Markdown is enabled, and the text is in Markdown format, this will add a “rich-text” field.

get_data_attributes()[source]¶

render_value(text)[source]¶

Returns the value of the field.

If Markdown is enabled, and the text is not in Markdown format, the text will be escaped.

should_render_as_markdown(value)[source]¶

Returns whether the text should be rendered as Markdown.

By default, this checks if the field is set to always render any text as Markdown, or if the given text is in Markdown format.

render_change_entry_html(info)[source]¶

get_review_request_fields()[source]¶

Returns a list of all registered field classes.

get_review_request_fieldsets(include_main=False, include_change_entries_only=False)[source]¶

Returns a list of all registered fieldset classes.

As an internal optimization, the “main” fieldset can be filtered out, to help with rendering the side of the review request page.

get_review_request_fieldset(fieldset_id)[source]¶

Returns the fieldset with the specified ID.

If the fieldset could not be found, this will return None.

get_review_request_field(field_id)[source]¶

Returns the field with the specified ID.

If the field could not be found, this will return None.

register_review_request_fieldset(fieldset)[source]¶

Registers a custom review request fieldset.

A fieldset ID is considered unique and can only be registered once. A KeyError will be thrown if attempting to register a second time.

unregister_review_request_fieldset(fieldset)[source]¶

Unregisters a previously registered review request fieldset.