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: exceptions.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.

error_payload[source]¶: The error payload to send to the client.

class CallbackRegistry[source]¶

Bases: reviewboard.registries.registry.Registry

item_name = u'callback'[source]¶

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

register(item)[source]¶

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: djblets.webapi.resources.mixins.queries.APIQueryUtilsMixin, djblets.webapi.resources.mixins.api_tokens.ResourceAPITokenMixin, djblets.webapi.resources.mixins.oauth2_tokens.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 = u'reviewboard.org'[source]¶

api_token_model[source]¶: alias of reviewboard.webapi.models.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: reviewboard.webapi.base.RBResourceMixin, djblets.webapi.resources.base.WebAPIResource

A specialization of the Djblets WebAPIResource for Review Board.

__init__(*args, **kwargs)[source]¶: x.__init__(…) initializes x; see help(type(x)) for signature

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

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(**kwargs)[source]¶

Returns the serialized object for the resource.

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

get_list(**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.

delete(**kwargs)[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.

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:

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.
A JSON Merge Patch document through setting extra_data:json=patch. This is a simple way of setting new structured JSON content.
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.