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 onWebAPIResource
subclasses.- ACCESS_STATE_PUBLIC = 1[source]¶
The associated extra_data key can be retrieved and updated 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.
- class CallbackRegistry[source]¶
Bases:
Registry
- 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:
- 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.
- __annotations__ = {'_items': 'set[RegistryItemType]', '_lock': 'RLock', '_registry': 'dict[str, dict[object, RegistryItemType]]', 'already_registered_error_class': 'Type[AlreadyRegisteredError]', 'default_errors': 'RegistryErrorsDict', 'errors': 'RegistryErrorsDict', 'item_name': 'Optional[str]', 'lookup_attrs': 'Sequence[str]', 'lookup_error_class': 'Type[ItemLookupError]', 'state': 'RegistryState'}¶
- __parameters__ = ()¶
- 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.- api_token_model[source]¶
alias of
WebAPIToken
- class WebAPIResource(*args, **kwargs)[source]¶
Bases:
RBResourceMixin
,WebAPIResource
A specialization of the Djblets WebAPIResource for Review Board.
- 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:
- 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 orNone
.- Return type:
- 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 acount
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.
- 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 theextra_data
key as atuple
ofunicode
strings.- Returns:
The access state of the provided key.
- Return type:
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 allargs
andkwargs
. However, Review Board allows certain resources to be disabled by setting therequired_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
ortuple
- 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:
- 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 ofextra_data
.Changed in version 3.0: Added support for
extra_data:json
andextra_data:json-patch
.- Parameters:
obj (
django.db.models.Model
) – The object containing anextra_data
field.extra_data (
dict
) – The existing contents of theextra_data
field. This will be updated directly.fields (
dict
) – The fields being set in the request. This will be checked forextra_data:json
,extra_data:json-patch
, and any beginning withextra_data.
.
- Returns:
True
ifextra_data
was at all modified.False
if it wasn’t.- Return type:
- 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.
- __annotations__ = {}¶