reviewboard.webapi.base¶

class ExtraDataAccessLevel[source]¶

Bases: object

Various access levels for extra_data fields.

This class consists of constants describing the various access levels for extra_data keys on WebAPIResource subclasses.

ACCESS_STATE_PUBLIC = 1[source]¶

The associated extra_data key can be retrieved and updated via the API.

ACCESS_STATE_PUBLIC_READONLY = 2[source]¶

The associated extra_data key can only be retrieved via the API.

ACCESS_STATE_PRIVATE = 3[source]¶

The associated extra_data key cannot be accessed via the API.

exception ImportExtraDataError[source]¶

Bases: ValueError

Error importing extra_data from a client request.

This often represents a JSON parse error or format error with a patch. Details are available in the message, and a suitable API error payload is provided.

property error_payload[source]¶

The error payload to send to the client.

class CallbackRegistry[source]¶

Bases: Registry

item_name: Optional[str] = 'callback'[source]¶

The name of the items being registered.

Type:

str

errors: RegistryErrorsDict = {'not_callable': 'Could not register %(item)s: it is not callable.'}[source]¶

Error formatting strings for exceptions.

Entries here override the global DEFAULT_ERRORS dictionary for error messages.

Type:

dict

register(item)[source]¶

Register a callback.

Parameters:

item (callable) – The item to register.

Raises:

• djblets.registries.errors.RegistrationError – Raised if the item is not a callable.

• djblets.registries.errors.AlreadyRegisteredError – Raised if the item is already registered.

class RBResourceMixin[source]¶

Bases: APIQueryUtilsMixin, ResourceAPITokenMixin, ResourceOAuth2TokenMixin

A mixin for Review Board resources.

This mixin is intended to be used by the base Review Board WebAPIResource and in subclasses of resources from other packages (e.g., Djblets) to specialize them for Review Board.

autogenerate_etags = True[source]¶

mimetype_vendor = 'reviewboard.org'[source]¶

api_token_model[source]¶

alias of WebAPIToken

required_features = [][source]¶

An optional set of required features to communicate with this resource.

If no features are listed here, the resource will behave normally. However, if one or more features are listed here and are not enabled, the resource will return a 403 Forbidden error.

class WebAPIResource(*args, **kwargs)[source]¶

Bases: RBResourceMixin, WebAPIResource

A specialization of the Djblets WebAPIResource for Review Board.

__init__(*args, **kwargs)[source]¶

has_access_permissions(*args, **kwargs)[source]¶

Return whether the user has read access to the item resource.

This is used for HTTP GET requests on the item resource. For list resources, see has_list_access_permissions().

Subclasses should override this to provide any specific access control needed for accessing items.

Parameters:

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

• obj (object) – The object to check for permissions.

• *args (tuple) – Additional positional arguments passed to the view.

• **kwargs (dict) – Keyword arguments representing values captured from the URL.

Returns:

True if the user has access permissions. False if it does not.

Return type:

bool

serialize_extra_data_field(obj, request=None)[source]¶

Serialize a resource’s extra_data field.

Parameters:

• obj (django.db.models.Model) – The model of a given resource.

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

Returns:

A serialized extra_data field or None.

Return type:

dict

get(request: HttpRequest, *args, api_format: Optional[str], **kwargs) → WebAPIResourceHandlerResult[source]¶

Returns the serialized object for the resource.

This will require login if anonymous access isn’t enabled on the site.

get_list(request, *args, **kwargs)[source]¶

Returns a list of objects.

This will require login if anonymous access isn’t enabled on the site.

If ?counts-only=1 is passed on the URL, then this will return only a count field with the number of entries, instead of the serialized objects.

create(request: HttpRequest, *args, api_format: Optional[str], **kwargs) → WebAPIResourceHandlerResult[source]¶

Handle HTTP POST requests to list resources.

This is used to create a new object on the list, given the data provided in the request. It should usually return HTTP 201 Created upon success.

By default, this returns HTTP 405 Method Not Allowed.

Parameters:

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

• *args (tuple) – Positional arguments passed to the view.

• api_format (str) – An explicit API format requested for the response.

• **kwargs (dict) – Keyword arguments representing values captured from the URL.

Returns:

The HTTP response, API error, or tuple results from the API handler.

Return type:

WebAPIResourceHandlerResult

update(request: HttpRequest, *args, api_format: Optional[str], **kwargs) → WebAPIResourceHandlerResult[source]¶

Handle HTTP PUT requests to object resources.

This is used to update an object, given full or partial data provided in the request. It should usually return HTTP 200 OK upon success.

By default, this returns HTTP 405 Method Not Allowed.

Parameters:

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

• *args (tuple) – Positional arguments passed to the view.

• api_format (str) – An explicit API format requested for the response.

• **kwargs (dict) – Keyword arguments representing values captured from the URL.

Returns:

The HTTP response, API error, or tuple results from the API handler.

Return type:

WebAPIResourceHandlerResult

delete(request: HttpRequest, *args, api_format: Optional[str], **kwargs) → WebAPIResourceHandlerResult[source]¶

Handles HTTP DELETE requests to object resources.

This is used to delete an object, if the user has permissions to do so.

By default, this deletes the object and returns HTTP 204 No Content.

Parameters:

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

• *args (tuple) – Positional arguments passed to the view.

• api_format (str) – An explicit API format requested for the response.

• **kwargs (dict) – Keyword arguments representing values captured from the URL.

Returns:

The HTTP response, API error, or tuple results from the API handler.

Return type:

WebAPIResourceHandlerResult

can_import_extra_data_field(obj, field)[source]¶

Return whether a top-level field in extra_data can be imported.

Subclasses can use this to limit which fields are imported by import_extra_data(). By default, all fields can be imported.

Note that this only supports top-level keys, and is mostly here for legacy reasons. Subclasses generally should override get_extra_data_field_state() to provide more fine-grained access to content.

Parameters:

• obj (object) – The object being serialized for the resource.

• field (unicode) – The field being considered for import.

Returns:

True if the field can be imported. False if it should be ignored.

Return type:

bool

get_extra_data_field_state(key_path)[source]¶

Return the state of a registered extra_data key path.

Parameters:

key_path (tuple) – The path of the extra_data key as a tuple of unicode strings.

Returns:

The access state of the provided key.

Return type:

int

Example

obj.extra_data = {
    'public': 'foo',
    'private': 'secret',
    'data': {
        'secret_key': 'secret_data',
    },
    'readonly': 'bar',
}

...

key_path = ('data', 'secret_key')
resource.get_extra_data_field_state(key_path)

call_method_view(request, method, view, *args, **kwargs)[source]¶

Call the given method view.

The default behaviour is to call the given view passing in all args and kwargs. However, Review Board allows certain resources to be disabled by setting the required_features attribute. If a feature specified in that list is disabled, this method will return a 403 Forbidden response instead of calling the method view.

In addition, Review Board has token access policies. If the client is authenticated with an API token, the token’s access policies will be checked before calling the view. If the operation is disallowed, a 403 Forbidden response will be returned.

If read-only mode is enabled, all PUT, POST, and DELETE requests will be rejected with a 503 Service Unavailable response, unless the user is a superuser.

Only if all these conditions are met will the view actually be called.

Parameters:

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

• method (unicode) – The HTTP method.

• view (callable) – The view.

• *args (tuple) – Additional positional arguments.

• **kwargs (dict) – Additional keyword arguments.

Returns:

Either a 403 Forbidden error or the result of calling the method view, which will either be a WebAPIError or a 2-tuple of the HTTP status code and a dict indicating the JSON response from the view.

Return type:

WebAPIError or tuple

build_resource_url(name, local_site_name=None, request=None, **kwargs)[source]¶

Build the URL to a resource, factoring in Local Sites.

Parameters:

• name (unicode) – The resource name.

• local_site_name (unicode) – The LocalSite name.

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

• kwargs (dict) – The keyword arguments needed for URL resolution.

Returns:

The resulting absolute URL to the resource.

Return type:

unicode

import_extra_data(obj, extra_data, fields)[source]¶

Import new extra_data content from the client.

There are three methods for injecting new content into the object’s extra_data JSON field:

1. Simple key/value forms through setting extra_data.key=value. This will convert boolean-like strings to booleans, numeric strings to integers or floats, and the rest are stored as strings. It’s only intended for very simple data.

2. A JSON Merge Patch document through setting extra_data:json=patch. This is a simple way of setting new structured JSON content.

3. A more complex JSON Patch document through setting extra_data:json-patch=patch. This is a more advanced way of manipulating JSON data, allowing for sanity-checking of existing content, adding new keys/array indices, replacing existing keys/indices, deleting data, or copying/moving data. If any operation (including the sanity-checking) fails, the whole patch is aborted.

All methods respect any access states that apply to the resource, and forbid both writing to keys starting with __ and replacing the entire root of extra_data.

Changed in version 3.0: Added support for extra_data:json and extra_data:json-patch.

Parameters:

• obj (django.db.models.Model) – The object containing an extra_data field.

• extra_data (dict) – The existing contents of the extra_data field. This will be updated directly.

• fields (dict) – The fields being set in the request. This will be checked for extra_data:json, extra_data:json-patch, and any beginning with extra_data..

Returns:

True if extra_data was at all modified. False if it wasn’t.

Return type:

bool

Raises:

ImportExtraDataError – There was an error importing content into extra_data. There may be a parse error or access error. Details are in the message.