rbtools.api.resource¶

Resource definitions for the RBTools Python API.

Functions

Classes

rbtools.api.resource.resource_mimetype(mimetype)[source]¶

Set the mimetype for the decorated class in the resource map.

class rbtools.api.resource.Resource(transport, payload, url, token=None, **kwargs)[source]¶

Bases: object

Defines common functionality for Item and List Resources.

Resources are able to make requests to the Web API by returning an HttpRequest object. When an HttpRequest is returned from a method call, the transport layer will execute this request and return the result to the user.

Methods for constructing requests to perform each of the supported REST operations will be generated automatically. These methods will have names corresponding to the operation (e.g. ‘update()’). An additional method for re-requesting the resource using the ‘self’ link will be generated with the name ‘get_self’. Each additional link will have a method generated which constructs a request for retrieving the linked resource.

__init__(transport, payload, url, token=None, **kwargs)[source]¶

property links[source]¶

Get the resource’s links.

This is a special property which allows direct access to the links dictionary for a resource. Unlike other properties which come from the resource fields, this one is only accessible as a property, and not using array syntax.

property rsp[source]¶

Return the response payload used to create the resource.

class rbtools.api.resource.ResourceDictField(resource, fields)[source]¶

Bases: MutableMapping

Wrapper for dictionaries returned from a resource.

Items fetched from this dictionary may be wrapped as a resource or resource field container.

Changes cannot be made to resource dictionaries. Instead, changes must be made using Resource.update() calls.

Changed in version 3.1: This class now operates like a standard dictionary, but blocks any changes (which were misleading and could not be used to save state in any prior version).

__init__(resource, fields)[source]¶

Initialize the field.

Parameters:

• resource (Resource) – The parent resource that owns this field.

• fields (dict) – The dictionary contents from the payload.

__getattr__(name)[source]¶

Return the value of a key from the field as an attribute reference.

The resulting value will be wrapped as a resource or resource field if appropriate.

Parameters:

name (unicode) – The name of the key.

Returns:

The value of the field.

Return type:

object

Raises:

AttributeError – The provided key name was not found in the dictionary.

__getitem__(name)[source]¶

Return the value of a key from the field as an item lookup.

The resulting value will be wrapped as a resource or resource field if appropriate.

Parameters:

name (unicode) – The name of the key.

Returns:

The value of the field.

Return type:

object

Raises:

KeyError – The provided key name was not found in the dictionary.

__delitem__(name)[source]¶

Delete an item from the dictionary.

This will raise an exception stating that changes are not allowed and offering an alternative.

Parameters:

name (unicode, unused) – The name of the key to delete.

Raises:

AttributeError – An error stating that changes are not allowed.

__setitem__(name, value)[source]¶

Set an item in the dictionary.

This will raise an exception stating that changes are not allowed and offering an alternative.

Parameters:

name (unicode, unused) – The name of the key to set.

Raises:

AttributeError – An error stating that changes are not allowed.

__len__()[source]¶

Return the number of items in the dictionary.

Returns:

The number of items.

Return type:

int

__iter__()[source]¶

Iterate through the dictionary.

Yields:

object – Each item in the dictionary.

__repr__()[source]¶

Return a string representation of the dictionary field.

Returns:

The string representation.

Return type:

unicode

fields()[source]¶

Iterate through all fields in the dictionary.

This will yield each field name in the dictionary. This is the same as calling keys() or simply for field in dict_field.

Yields:

str – Each field in this dictionary.

__abstractmethods__ = frozenset({})¶

class rbtools.api.resource.ResourceLinkField(resource, fields)[source]¶

Bases: ResourceDictField

Wrapper for link dictionaries returned from a resource.

In order to support operations on links found outside of a resource’s links dictionary, detected links are wrapped with this class.

A links fields (href, method, and title) are accessed as attributes, and link operations are supported through method calls. Currently the only supported method is “GET”, which can be invoked using the ‘get’ method.

__init__(resource, fields)[source]¶

Initialize the field.

Parameters:

• resource (Resource) – The parent resource that owns this field.

• fields (dict) – The dictionary contents from the payload.

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.[source]¶

__abstractmethods__ = frozenset({})¶

class rbtools.api.resource.ResourceExtraDataField(resource, fields)[source]¶

Bases: ResourceDictField

Wrapper for extra_data fields on resources.

New in version 3.1.

copy()[source]¶

Return a copy of the dictionary’s fields.

A copy of the original extra_data content will be returned, without any field wrapping.

Returns:

The copy of the dictionary.

Return type:

dict

__abstractmethods__ = frozenset({})¶

class rbtools.api.resource.ResourceListField(resource, list_field, item_mimetype=None)[source]¶

Bases: list

Wrapper for lists returned from a resource.

Acts as a normal list, but wraps any returned items.

__init__(resource, list_field, item_mimetype=None)[source]¶

__getitem__(key)[source]¶

Return self[index].

__iter__()[source]¶

Implement iter(self).

__repr__()[source]¶

Return repr(self).

class rbtools.api.resource.ItemResource(transport, payload, url, token=None, **kwargs)[source]¶

Bases: Resource

The base class for Item Resources.

Any resource specific base classes for Item Resources should inherit from this class. If a resource specific base class does not exist for an Item Resource payload, this class will be used to create the resource.

The body of the resource is copied into the fields dictionary. The Transport is responsible for providing access to this data, preferably as attributes for the wrapping class.

__init__(transport, payload, url, token=None, **kwargs)[source]¶

__getattr__(name)[source]¶

Return the value for an attribute on the resource.

If the attribute represents an expanded resource, and there’s information available on the expansion (available in Review Board 4.0+), then a resource instance will be returned.

If the attribute otherwise represents a dictionary, list, or a link, a wrapper may be returned.

Parameters:

name (str) – The name of the attribute.

Returns:

The attribute value, or a wrapper or resource representing that value.

Return type:

object

Raises:

AttributeError – A field with the given attribute name was not found.

__getitem__(key)[source]¶

__contains__(key)[source]¶

iterfields() → Iterator[str][source]¶

Iterate through all field names in the resource.

Yields:

str – The name of each field name.

iteritems() → Iterator[str, Any][source]¶

Iterate through all field/value pairs in the resource.

Yields:

tuple – A tuple in (field_name, value) form.

__repr__()[source]¶

Return repr(self).

class rbtools.api.resource.CountResource(transport, payload, url, **kwargs)[source]¶

Bases: ItemResource

Resource returned by a query with ‘counts-only’ true.

When a resource is requested using ‘counts-only’, the payload will not contain the regular fields for the resource. In order to special case all payloads of this form, this class is used for resource construction.

__init__(transport, payload, url, **kwargs)[source]¶

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

Generate an GET request for the resource list.

This will return an HttpRequest to retrieve the list resource which this resource is a count for. Any query arguments used in the request for the count will still be present, only the ‘counts-only’ argument will be removed

class rbtools.api.resource.ListResource(transport, payload, url, token=None, item_mime_type=None, **kwargs)[source]¶

Bases: Resource

The base class for List Resources.

Any resource specific base classes for List Resources should inherit from this class. If a resource specific base class does not exist for a List Resource payload, this class will be used to create the resource.

Instances of this class will act as a sequence, providing access to the payload for each Item resource in the list. Iteration is over the page of item resources returned by a single request, and not the entire list of resources. To iterate over all item resources ‘get_next()’ or ‘get_prev()’ should be used to grab additional pages of items.

__init__(transport, payload, url, token=None, item_mime_type=None, **kwargs)[source]¶

total_results: Optional[int]¶

The total number of results in the list across all pages.

This is commonly set for most list resources, but is not always guaranteed to be available. Callers should check to make sure this is not None.

Type:

int

__len__()[source]¶

__nonzero__()[source]¶

__bool__()[source]¶

__getitem__(index)[source]¶

Return the item at the specified index.

Parameters:

index (int) – The index of the item to retrieve.

Returns:

The item at the specified index.

Return type:

object

Raises:

IndexError – The index is out of range.

__iter__()[source]¶

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

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

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

Retrieve the item resource with the corresponding primary key.

property all_pages[source]¶

Yield all pages of item resources.

Each page of resources is itself an instance of the same ListResource class.

property all_items[source]¶

Yield all item resources in all pages of this resource.

__repr__()[source]¶

Return repr(self).

class rbtools.api.resource.GetPatchMixin[source]¶

Bases: object

Mixin for resources that implement a get_patch method.

New in version 4.2.

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

Retrieve the diff file contents.

Parameters:

**kwargs (dict) – Query args to pass to __init__().

Returns:

A resource payload whose data attribute is the requested patch.

Return type:

ItemResource

class rbtools.api.resource.RootResource(transport, payload, url, **kwargs)[source]¶

Bases: ItemResource

The Root resource specific base class.

Provides additional methods for fetching any resource directly using the uri templates. A method of the form “get_<uri-template-name>” is called to retrieve the HttpRequest corresponding to the resource. Template replacement values should be passed in as a dictionary to the values parameter.

capabilities: ResourceDictField¶

Capabilities for the Review Board server.

__init__(transport, payload, url, **kwargs)[source]¶

class rbtools.api.resource.DiffCommitItemResource(transport, payload, url, token=None, **kwargs)[source]¶

Bases: GetPatchMixin, ItemResource

The commit resource-specific class.

class rbtools.api.resource.DraftDiffCommitItemResource(transport, payload, url, token=None, **kwargs)[source]¶

Bases: GetPatchMixin, ItemResource

The draft commit resource-specific class.

New in version 4.2.

class rbtools.api.resource.DraftDiffCommitListResource(transport, payload, url, token=None, item_mime_type=None, **kwargs)[source]¶

Bases: ListResource

The draft commit list resource-specific class.

Provides additional functionality in the uploading of new commits.

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

Upload a commit.

Parameters:

• validation_info (unicode) – The validation info, or None if this is the first commit in a series.

• diff (bytes) – The diff contents.

• commit_id (unicode) – The ID of the commit being uploaded.

• parent_id (unicode) – The ID of the parent commit.

• author_name (unicode) – The name of the author.

• author_email (unicode) – The e-mail address of the author.

• author_date (unicode) – The date and time the commit was authored in ISO 8601 format.

• committer_name (unicode, optional) – The name of the committer (if applicable).

• committer_email (unicode, optional) – The e-mail address of the committer (if applicable).

• committer_date (unicode, optional) – The date and time the commit was committed in ISO 8601 format (if applicable).

• parent_diff (bytes, optional) – The contents of the parent diff.

• **kwargs (dict) – Keyword argument used to build the querystring for the request URL.

Returns:

The created resource.

Return type:

DraftDiffCommitItemResource

Raises:

rbtools.api.errors.APIError – An error occurred while uploading the commit.

class rbtools.api.resource.DiffUploaderMixin[source]¶

Bases: object

A mixin for uploading diffs to a resource.

prepare_upload_diff_request(diff, parent_diff=None, base_dir=None, base_commit_id=None, **kwargs)[source]¶

Create a request that can be used to upload a diff.

The diff and parent_diff arguments should be strings containing the diff output.

class rbtools.api.resource.DiffListResource(transport, payload, url, token=None, item_mime_type=None, **kwargs)[source]¶

Bases: DiffUploaderMixin, ListResource

The Diff List resource specific base class.

This resource provides functionality to assist in the uploading of new diffs.

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

Upload a diff to the resource.

The diff and parent_diff arguments should be strings containing the diff output.

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

Create an empty DiffSet that commits can be added to.

Parameters:

• base_commit_id (unicode, optional) – The base commit ID of the diff.

• **kwargs (dict) – Keyword arguments to encode into the querystring of the request URL.

Returns:

The created resource.

Return type:

DiffItemResource

class rbtools.api.resource.DiffResource(transport, payload, url, token=None, **kwargs)[source]¶

Bases: GetPatchMixin, ItemResource

The Diff resource specific base class.

Provides the ‘get_patch’ method for retrieving the content of the actual diff file itself.

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

Finalize a commit series.

Parameters:

• cumulative_diff (bytes) – The cumulative diff of the entire commit series.

• validation_info (unicode) – The validation information returned by validatin the last commit in the series with the ValidateDiffCommitResource.

• parent_diff (bytes, optional) –

  An optional parent diff.

  This will be the same parent diff uploaded with each commit.

Returns:

The finalized diff resource.

Return type:

DiffItemResource

class rbtools.api.resource.DraftDiffResource(transport, payload, url, token=None, **kwargs)[source]¶

Bases: GetPatchMixin, ItemResource

The Draft Diff resource specific base class.

Provides the get_patch() method for retrieving the content of the actual diff file itself.

New in version 4.2.

class rbtools.api.resource.FileDiffResource(transport, payload, url, token=None, **kwargs)[source]¶

Bases: GetPatchMixin, ItemResource

The File Diff resource specific base class.

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

Retrieves the actual raw diff data for the file.

class rbtools.api.resource.FileAttachmentListResource(transport, payload, url, token=None, item_mime_type=None, **kwargs)[source]¶

Bases: ListResource

The File Attachment List resource specific base class.

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

Upload a new attachment.

Parameters:

• filename (str) – The name of the file.

• content (bytes) – The content of the file to upload.

• caption (str, optional) – The caption to set on the file attachment.

• attachment_history (str, optional) – The ID of the FileAttachmentHistory to add this attachment to.

• **kwargs (dict) – Additional keyword arguments to add to the request.

class rbtools.api.resource.DiffFileAttachmentListResource(transport, payload, url, token=None, item_mime_type=None, **kwargs)[source]¶

Bases: ListResource

The Diff File Attachment List resource specific base class.

New in version 5.0.

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

Upload a new attachment.

Parameters:

• filename (str) – The name of the file.

• content (bytes) – The content of the file to upload.

• filediff_id (str) – The ID of the filediff to attach the file to.

• source_file (bool, optional) – Whether to upload the source version of a file.

• **kwargs (dict) – Additional keyword arguments to add to the request

Returns:

The request object.

Return type:

rbtools.api.request.HttpRequest

class rbtools.api.resource.DraftFileAttachmentListResource(transport, payload, url, token=None, item_mime_type=None, **kwargs)[source]¶

Bases: FileAttachmentListResource

The Draft File Attachment List resource specific base class.

class rbtools.api.resource.ScreenshotListResource(transport, payload, url, token=None, item_mime_type=None, **kwargs)[source]¶

Bases: ListResource

The Screenshot List resource specific base class.

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

Uploads a new screenshot.

The content argument should contain the body of the screenshot to be uploaded, in string format.

class rbtools.api.resource.DraftScreenshotListResource(transport, payload, url, token=None, item_mime_type=None, **kwargs)[source]¶

Bases: ScreenshotListResource

The Draft Screenshot List resource specific base class.

class rbtools.api.resource.ReviewRequestResource(transport, payload, url, token=None, **kwargs)[source]¶

Bases: ItemResource

The Review Request resource specific base class.

property absolute_url[source]¶

Returns the absolute URL for the Review Request.

The value of absolute_url is returned if it’s defined. Otherwise the absolute URL is generated and returned.

property url[source]¶

Returns the relative URL to the Review Request.

The value of ‘url’ is returned if it’s defined. Otherwise, a relative URL is generated and returned.

This provides compatibility with versions of Review Board older than 1.7.8, which do not have a ‘url’ field.

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

Submit a review request

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

build_dependency_graph()[source]¶

Build the dependency graph for the review request.

Only review requests in the same repository as this one will be in the graph.

A ValueError is raised if the graph would contain cycles.

class rbtools.api.resource.ValidateDiffResource(transport, payload, url, token=None, **kwargs)[source]¶

Bases: DiffUploaderMixin, ItemResource

The Validate Diff resource specific base class.

Provides additional functionality to assist in the validation of diffs.

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

Validate a diff.

class rbtools.api.resource.ValidateDiffCommitResource(transport, payload, url, token=None, **kwargs)[source]¶

Bases: ItemResource

The commit validation resource specific base class.

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

Validate the diff for a commit.

Parameters:

• repository (unicode) – The name of the repository.

• diff (bytes) – The contents of the diff to validate.

• commit_id (unicode) – The ID of the commit being validated.

• parent_id (unicode) – The ID of the parent commit.

• parent_diff (bytes, optional) – The contents of the parent diff.

• base_commit_id (unicode, optional) – The base commit ID.

• validation_info (unicode, optional) – Validation information from a previous call to this resource.

• **kwargs (dict) – Keyword arguments used to build the querystring.

Returns:

The validation result.

Return type:

ValidateDiffCommitResource