reviewboard.reviews.actions¶

MAX_DEPTH_LIMIT = 2[source]¶: The maximum depth limit of any action instance.

class BaseReviewRequestAction[source]¶

Bases: object

A base class for an action that can be applied to a review request.

Creating an action requires subclassing BaseReviewRequestAction and overriding any fields/methods as desired. Different instances of the same subclass can also override the class fields with their own instance fields.

Example

class UsedOnceAction(BaseReviewRequestAction):
    action_id = 'once'
    label = 'This is used once.'

class UsedMultipleAction(BaseReviewRequestAction):
    def __init__(self, action_id, label):
        super(UsedMultipleAction, self).__init__()

        self.action_id = 'repeat-' + action_id
        self.label = 'This is used multiple times,'

Note

Since the same action will be rendered for multiple different users in a multithreaded environment, the action state should not be modified after initialization. If we want different action attributes at runtime, then we can override one of the getter methods (such as get_label()), which by default will simply return the original attribute from initialization.

action_id = None[source]¶: The ID of this action. Must be unique across all types of actions and menu actions, at any depth.

label = None[source]¶: The label that displays this action to the user.

url = '#'[source]¶: The URL to invoke if this action is clicked.

hidden = False[source]¶: Determines if this action should be initially hidden to the user.

__init__()[source]¶

Initialize this action.

By default, actions are top-level and have no children.

copy_to_dict(context)[source]¶

Copy this action instance to a dictionary.

Parameters:: context (django.template.Context) – The collection of key-value pairs from the template.
Returns:: The corresponding dictionary.
Return type:: dict

get_label(context)[source]¶

Return this action’s label.

Parameters:: context (django.template.Context) – The collection of key-value pairs from the template.
Returns:: The label that displays this action to the user.
Return type:: unicode

get_url(context)[source]¶

Return this action’s URL.

Parameters:: context (django.template.Context) – The collection of key-value pairs from the template.
Returns:: The URL to invoke if this action is clicked.
Return type:: unicode

get_hidden(context)[source]¶

Return whether this action should be initially hidden to the user.

Parameters:: context (django.template.Context) – The collection of key-value pairs from the template.
Returns:: Whether this action should be initially hidden to the user.
Return type:: bool

should_render(context)[source]¶

Return whether or not this action should render.

The default implementation is to always render the action everywhere.

Parameters:: context (django.template.Context) – The collection of key-value pairs available in the template just before this action is to be rendered.
Returns:: Determines if this action should render.
Return type:: bool

property max_depth[source]¶

Lazily compute the max depth of any action contained by this action.

Top-level actions have a depth of zero, and child actions have a depth that is one more than their parent action’s depth.

Algorithmically, the notion of max depth is equivalent to the notion of height in the context of trees (from graph theory). We decided to use this term instead so as not to confuse it with the dimensional height of a UI element.

Returns:: The max depth of any action contained by this action.
Return type:: int

reset_max_depth()[source]¶: Reset the max_depth of this action and all its ancestors to zero.

render(context, action_key='action', template_name='reviews/action.html')[source]¶

Render this action instance and return the content as HTML.

Parameters:

context (django.template.Context) – The collection of key-value pairs that is passed to the template in order to render this action.
action_key (unicode, optional) – The key to be used for this action in the context map.
template_name (unicode, optional) – The name of the template to be used for rendering this action.

Returns:

The action rendered in HTML.

Return type:

unicode

register(parent=None)[source]¶

Note

Newly registered top-level actions are appended to the left of the other previously registered top-level actions. So if we intend to register a collection of top-level actions in a certain order, then we likely want to iterate through the actions in reverse.

Parameters:

parent (BaseReviewRequestMenuAction, optional) – The parent action instance of this action instance.

Raises:

KeyError – A second registration is attempted (action IDs must be unique across all types of actions and menu actions, at any depth).
DepthLimitExceededError – The maximum depth limit is exceeded.

unregister()[source]¶

Unregister this review request action instance.

Note

This method can mutate its parent’s child actions. So if we are iteratively unregistering a parent’s child actions, then we should consider first making a clone of the list of children.

Raises:: KeyError – An unregistration is attempted before it’s registered.

class BaseReviewRequestMenuAction(child_actions=None)[source]¶

Bases: BaseReviewRequestAction

A base class for an action with a dropdown menu.

Note

A menu action’s child actions must always be pre-registered.

__init__(child_actions=None)[source]¶

Initialize this menu action.

Parameters:

child_actions (list of BaseReviewRequestAction, optional) – The list of child actions to be contained by this menu action.

Raises:

KeyError – A second registration is attempted (action IDs must be unique across all types of actions and menu actions, at any depth).
DepthLimitExceededError – The maximum depth limit is exceeded.

copy_to_dict(context)[source]¶

Copy this menu action instance to a dictionary.

Parameters:: context (django.template.Context) – The collection of key-value pairs from the template.
Returns:: The corresponding dictionary.
Return type:: dict

property max_depth[source]¶

Lazily compute the max depth of any action contained by this action.

Returns:: The max depth of any action contained by this action.
Return type:: int

render(context, action_key='menu_action', template_name='reviews/menu_action.html')[source]¶

Render this menu action instance and return the content as HTML.

Parameters:

context (django.template.Context) – The collection of key-value pairs that is passed to the template in order to render this menu action.
action_key (unicode, optional) – The key to be used for this menu action in the context map.
template_name (unicode, optional) – The name of the template to be used for rendering this menu action.

Returns:

The action rendered in HTML.

Return type:

unicode

unregister()[source]¶

Unregister this review request action instance.

This menu action recursively unregisters its child action instances.

Raises:: KeyError – An unregistration is attempted before it’s registered.

get_top_level_actions()[source]¶

Return a generator of all top-level registered action instances.

Yields:: BaseReviewRequestAction – All top-level registered review request action instances.

register_actions(actions, parent_id=None)[source]¶

If no parent_id is given, then the actions are assumed to be top-level.

Parameters:

actions (iterable of BaseReviewRequestAction) – The collection of action instances to be registered.
parent_id (unicode, optional) – The action ID of the parent of each action instance to be registered.

Raises:

KeyError – The parent action cannot be found or a second registration is attempted (action IDs must be unique across all types of actions and menu actions, at any depth).
DepthLimitExceededError – The maximum depth limit is exceeded.

unregister_actions(action_ids)[source]¶

Unregister each of the actions corresponding to the given IDs.

Parameters:: action_ids (iterable of unicode) – The collection of action IDs corresponding to the actions to be removed.
Raises:: KeyError – An unregistration is attempted before it’s registered.

clear_all_actions()[source]¶

Clear all registered actions.

This method is really only intended to be used by unit tests. We might be able to remove this hack once we convert to djblets.registries.

Warning

This will clear all actions, even if they were registered in separate extensions.