rbtools.api.resource¶

Resource definitions for the RBTools Python API.

class rbtools.api.resource.CountResource(transport: Transport, payload: JSONDict, url: str, **kwargs)¶

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: Transport, payload: JSONDict, url: str, **kwargs) → None¶

Initialize the resource.

Parameters:

• transport (rbtools.api.transport.Transport) – The API transport.

• payload (dict) – The response payload.

• url (str) – The URL for the resource.

• **kwargs (dict, unused) – Unused keyword arguments.

get_self(**kwargs: Union[bool, int, float, bytes, str]) → HttpRequest¶

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

Parameters:

**kwargs (dict) – Query arguments to include with the request.

class rbtools.api.resource.DiffCommitItemResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, **kwargs)¶

Bases: BaseDiffCommitItemResource

Item resource for diff commits.

get_files(**kwargs: QueryArgs) → FileDiffListResource¶

Get the files for the commit.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The file diff list resource.

Return type:

rbtools.api.resource.FileDiffListResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

class rbtools.api.resource.DiffCommitListResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, item_mime_type: Optional[str] = None, **kwargs)¶

Bases: GetPatchMixin, ListResource[DiffCommitItemResource]

List resource for diff commits.

New in version 6.0.

__orig_bases__ = (<class 'rbtools.api.resource.mixins.GetPatchMixin'>, rbtools.api.resource.base.ListResource[rbtools.api.resource.diff_commit.DiffCommitItemResource])¶

__parameters__ = ()¶

class rbtools.api.resource.DiffFileAttachmentListResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, item_mime_type: Optional[str] = None, **kwargs)¶

Bases: ListResource[DiffFileAttachmentItemResource]

List resource for diff file attachments.

New in version 5.0.

upload_attachment(*, filename: str, content: bytes, filediff_id: str, source_file: bool = False, **kwargs: QueryArgs) → HttpRequest¶

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 of rbtools.api.request.QueryArgs) – Query arguments to include with the request.

Returns:

The newly created diff file attachment.

Return type:

DiffFileAttachmentItemResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

__orig_bases__ = (rbtools.api.resource.base.ListResource[rbtools.api.resource.diff_file_attachment.DiffFileAttachmentItemResource],)¶

__parameters__ = ()¶

class rbtools.api.resource.DiffItemResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, **kwargs)¶

Bases: GetPatchMixin, ItemResource

Item resource for diffs.

Changed in version 6.0: Renamed from DiffResource.

base_commit_id: str¶

The ID/revision that this change is built upon.

If using a parent diff, then this is the base for that diff. This may not be provided for all diffs or repository types, depending on how the diff was uploaded.

basedir: str¶

The base directory that will be prepended to all paths in the diff.

This is needed for some types of repositories. The directory must be between the root of the repository and the top directory referenced in the diff paths.

commit_count: str¶

The number of commits present.

This will only be set for review requests created with commit history.

extra_data: ResourceExtraDataField¶

Extra data as part of the diff.

id: int¶

The numeric ID of the diff.

name: str¶

The name of the diff, usually the filename.

revision: int¶

The revision of the diff.

This starts at 1 for public diffs. Draft diffs may be 0.

timestamp: str¶

The date and time that the diff was uploaded, in ISO-8601 format.

finalize_commit_series(cumulative_diff: bytes, validation_info: str, parent_diff: Optional[bytes] = None) → HttpRequest¶

Finalize a commit series.

Parameters:

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

• validation_info (str) – The validation information returned by validating 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

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

get_commits(**kwargs: Unpack[BaseGetListParams]) → DiffCommitListResource¶

Get the commits for the diff.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The diff commit list resource.

Return type:

rbtools.api.resource.DiffCommitListResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

get_draft_commits(**kwargs: Unpack[BaseGetListParams]) → DraftDiffCommitListResource¶

Get the commits for the diff when the diff is a draft.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The diff commit list resource.

Return type:

rbtools.api.resource.DraftDiffCommitListResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

get_draft_files(**kwargs: Unpack[BaseGetListParams]) → FileDiffListResource¶

Get the files for the diff when the diff is a draft.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The diff commit list resource.

Return type:

rbtools.api.resource.FileDiffListResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

get_files(**kwargs: Unpack[BaseGetListParams]) → FileDiffListResource¶

Get the files for the diff.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The file diff list resource.

Return type:

rbtools.api.resource.FileDiffListResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

class rbtools.api.resource.DiffListResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, item_mime_type: Optional[str] = None, **kwargs)¶

Bases: DiffUploaderMixin, ListResource[DiffItemResource]

List resource for diffs.

upload_diff(diff: bytes, parent_diff: Optional[bytes] = None, base_dir: Optional[str] = None, base_commit_id: Optional[str] = None, **kwargs: QueryArgs) → HttpRequest¶

Upload a diff to the resource.

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

Parameters:

• diff (bytes) – The diff content.

• parent_diff (bytes, optional) – The parent diff content, if present.

• base_dir (str, optional) – The base directory for the diff, if present.

• base_commit_id (str, optional) – The ID of the commit that the diff is against, if present.

• **kwargs (dict of rbtools.api.request.QueryArgs) – Query arguments to include with the request.

Returns:

The newly-created diff.

Return type:

DiffItemResource

create_empty(base_commit_id: Optional[str] = None, **kwargs: QueryArgs) → HttpRequest¶

Create an empty DiffSet that commits can be added to.

Parameters:

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

• **kwargs (dict of rbtools.api.request.QueryArgs) – Query arguments to include with the request.

Returns:

The newly-created diff.

Return type:

DiffItemResource

__orig_bases__ = (<class 'rbtools.api.resource.mixins.DiffUploaderMixin'>, rbtools.api.resource.base.ListResource[rbtools.api.resource.diff.DiffItemResource])¶

__parameters__ = ()¶

rbtools.api.resource.DiffResource[source]¶

alias of DiffItemResource

class rbtools.api.resource.DiffUploaderMixin¶

Bases: object

A mixin for uploading diffs to a resource.

prepare_upload_diff_request(diff: bytes, parent_diff: Optional[bytes] = None, base_dir: Optional[str] = None, base_commit_id: Optional[str] = None, **kwargs: QueryArgs) → HttpRequest¶

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

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

Parameters:

• diff (bytes) – The diff content.

• parent_diff (bytes, optional) – The parent diff content, if present.

• base_dir (str, optional) – The base directory for the diff, if present.

• base_commit_id (str, optional) – The ID of the commit that the diff is against, if present.

• **kwargs (dict of rbtools.api.request.QueryArgs) – Query arguments to include with the request.

Returns:

The API request.

Return type:

rbtools.api.request.HttpRequest

class rbtools.api.resource.DraftDiffCommitItemResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, **kwargs)¶

Bases: BaseDiffCommitItemResource

Item resource for draft diff commits.

New in version 4.2.

get_draft_files(**kwargs: Unpack[BaseGetListParams]) → FileDiffListResource¶

Get the files for this commit.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The file diff list resource.

Return type:

rbtools.api.resource.FileDiffListResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

class rbtools.api.resource.DraftDiffCommitListResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, item_mime_type: Optional[str] = None, **kwargs)¶

Bases: ListResource[DraftDiffCommitItemResource]

List resource for draft diff commits.

upload_commit(validation_info: str, diff: bytes, commit_id: str, parent_id: str, author_name: str, author_email: str, author_date: str, commit_message: str, committer_name: Optional[str] = None, committer_email: Optional[str] = None, committer_date: Optional[str] = None, parent_diff: Optional[bytes] = None, **kwargs: QueryArgs) → HttpRequest¶

Upload a commit.

Parameters:

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

• diff (bytes) – The diff contents.

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

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

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

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

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

• commit_message (str) – The commit message.

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

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

• committer_date (str, 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 of rbtools.api.request.QueryArgs) – Query arguments to include with the request.

Returns:

The created resource.

Return type:

DraftDiffCommitItemResource

Raises:

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

__orig_bases__ = (rbtools.api.resource.base.ListResource[rbtools.api.resource.draft_diff_commit.DraftDiffCommitItemResource],)¶

__parameters__ = ()¶

rbtools.api.resource.DraftDiffResource[source]¶

alias of DiffItemResource

class rbtools.api.resource.DiffFileAttachmentItemResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, **kwargs)¶

Bases: ItemResource

Item resource for diff file attachments.

New in version 6.0.

absolute_url: str¶

The absolute URL of the file, for downloading purposes.

caption: str¶

The file’s descriptive caption.

extra_data: ResourceExtraDataField¶

Extra data as part of the file attachment.

filename: str¶

The name of the file.

icon_url: str¶

The URL to a 24x24 icon representing the file.

The use of these icons is deprecated and this property may be removed in a future version of Review Board.

id: int¶

The numeric ID of the file.

mimetype: str¶

The mimetype for the file.

repository_file_path: str¶

The file path inside the repository for this file attachment.

repository_revision: str¶

The revision that introduced this version of the file.

review_url: str¶

The URL to a review UI for this file.

revision: int¶

The revision of the file attachment.

thumbnail: str¶

A thumbnail representing this file.

url: str¶

The URL of the file, for downloading purposes.

This is deprecated in favor of the absolute_url attribute.

get_added_in_filediff(**kwargs: Unpack[BaseGetParams]) → FileDiffItemResource¶

Get the file diff that this attachment was added in.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The file diff item resource.

Return type:

rbtools.api.resource.FileDiffItemResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

class rbtools.api.resource.DraftFileAttachmentItemResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, **kwargs)¶

Bases: ItemResource

Item resource for draft file attachments.

New in version 6.0.

absolute_url: str¶

The absolute URL of the file, for downloading purposes.

attachment_history_id: int¶

The ID of the file attachment history.

caption: str¶

The file’s descriptive caption.

extra_data: ResourceExtraDataField¶

Extra data as part of the file attachment.

filename: str¶

The name of the file.

icon_url: str¶

The URL to a 24x24 icon representing the file.

The use of these icons is deprecated and this property may be removed in a future version of Review Board.

id: int¶

The numeric ID of the file.

mimetype: str¶

The mimetype for the file.

review_url: str¶

The URL to a review UI for this file.

revision: int¶

The revision of the file attachment.

thumbnail: str¶

A thumbnail representing this file.

url: str¶

The URL of the file, for downloading purposes.

This is deprecated in favor of the absolute_url attribute.

class rbtools.api.resource.DraftFileAttachmentListResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, item_mime_type: Optional[str] = None, **kwargs)¶

Bases: AttachmentUploadMixin, ListResource[DraftFileAttachmentItemResource]

List resource for draft file attachments.

__orig_bases__ = (<class 'rbtools.api.resource.mixins.AttachmentUploadMixin'>, rbtools.api.resource.base.ListResource[rbtools.api.resource.draft_file_attachment.DraftFileAttachmentItemResource])¶

__parameters__ = ()¶

class rbtools.api.resource.DraftScreenshotItemResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, **kwargs)¶

Bases: ItemResource

Item resource for draft screenshots.

New in version 6.0.

absolute_url: str¶

The absolute URL of the screenshot file, for downloading purposes.

caption: str¶

The screenshot’s descriptive caption.

filename: str¶

The name of the screenshot file.

id: int¶

The numeric ID of the screenshot.

path: str¶

The path of the screenshot’s image file.

This is relative to the configured media directory on the Review Board server.

review_url: str¶

The URL to the review UI for this screenshot

thumbnail_url: str¶

The URL of the screenshot’s thumbnail file.

If this is not an absolute URL, it is relative to the Review Board server URL.

url: str¶

The URL of the screenshot file.

This is deprecated in favor of the absolute_url attribute.

class rbtools.api.resource.DraftScreenshotListResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, item_mime_type: Optional[str] = None, **kwargs)¶

Bases: ScreenshotUploadMixin, ListResource[DraftScreenshotItemResource]

List resource for draft screenshots.

__orig_bases__ = (<class 'rbtools.api.resource.mixins.ScreenshotUploadMixin'>, rbtools.api.resource.base.ListResource[rbtools.api.resource.draft_screenshot.DraftScreenshotItemResource])¶

__parameters__ = ()¶

class rbtools.api.resource.FileAttachmentItemResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, **kwargs)¶

Bases: ItemResource

Item resource for file attachments.

New in version 6.0.

absolute_url: str¶

The absolute URL of the file, for downloading purposes.

attachment_history_id: int¶

The ID of the file attachment history.

caption: str¶

The file’s descriptive caption.

extra_data: ResourceExtraDataField¶

Extra data as part of the file attachment.

filename: str¶

The name of the file.

icon_url: str¶

The URL to a 24x24 icon representing the file.

The use of these icons is deprecated and this property may be removed in a future version of Review Board.

id: int¶

The numeric ID of the file.

mimetype: str¶

The mimetype for the file.

review_url: str¶

The URL to a review UI for this file.

revision: int¶

The revision of the file attachment.

thumbnail: str¶

A thumbnail representing this file.

url: str¶

The URL of the file, for downloading purposes.

This is deprecated in favor of the absolute_url attribute.

class rbtools.api.resource.FileAttachmentListResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, item_mime_type: Optional[str] = None, **kwargs)¶

Bases: AttachmentUploadMixin, ListResource[FileAttachmentItemResource]

List resource for file attachments.

__orig_bases__ = (<class 'rbtools.api.resource.mixins.AttachmentUploadMixin'>, rbtools.api.resource.base.ListResource[rbtools.api.resource.file_attachment.FileAttachmentItemResource])¶

__parameters__ = ()¶

class rbtools.api.resource.FileDiffItemResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, **kwargs)¶

Bases: GetPatchMixin, ItemResource

Item resource for file diffs.

Changed in version 6.0: Renamed from FileDiffResource.

binary: bool¶

Whether this represents a binary file.

dest_detail: Optional[str]¶

Additional information of the destination file.

This is parsed from the diff, but is usually not used for anything.

dest_file: Optional[str]¶

The new name of the patched file.

This may be the same as the source file.

encoding: str¶

The encoding of the original and patched file, if available.

extra_data: ResourceExtraDataField¶

Extra data as part of the diff.

id: int¶

The numeric ID of the file diff.

source_file: str¶

The original name of the file.

source_revision: str¶

The revision of the file being modified.

This is a valid revision in the repository.

status: Literal['copied', 'deleted', 'modified', 'moved', 'unknown']¶

The status of the file.

get_diff_data(**kwargs: QueryArgs) → HttpRequest¶

Retrieve the actual raw diff data for the file.

Parameters:

**kwargs (dict of rbtools.api.request.QueryArgs) – Query arguments to include with the request.

Returns:

A resource wrapping the diff data.

Return type:

rbtools.api.resource.ItemResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

get_dest_attachment(**kwargs: Unpack[BaseGetParams]) → FileAttachmentItemResource¶

Get the file attachment for the modified file.

For binary files where an uploaded attachment exists, this will return the modified version of the file.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The file attachment for the modified version.

Return type:

rbtools.api.resource.FileAttachmentItemResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

get_source_attachment(**kwargs: Unpack[BaseGetParams]) → FileAttachmentItemResource¶

Get the file attachment for the original file.

For binary files where an uploaded attachment exists, this will return the original version of the file.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The file attachment for the original version.

Return type:

rbtools.api.resource.FileAttachmentItemResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

rbtools.api.resource.FileDiffResource[source]¶

alias of FileDiffItemResource

class rbtools.api.resource.FileDiffListResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, item_mime_type: Optional[str] = None, **kwargs)¶

Bases: ListResource[FileDiffItemResource]

List resource for file diffs.

New in version 6.0.

__orig_bases__ = (rbtools.api.resource.base.ListResource[rbtools.api.resource.file_diff.FileDiffItemResource],)¶

__parameters__ = ()¶

class rbtools.api.resource.GetPatchMixin¶

Bases: object

Mixin for resources that implement a get_patch method.

New in version 4.2.

get_patch(**kwargs: QueryArgs) → HttpRequest¶

Retrieve the diff file contents.

Parameters:

**kwargs (dict of rbtools.api.request.QueryArgs) – Query arguments to include with the request.

Returns:

A resource containing the patch. The patch data will be in the data attribute.

Return type:

rbtools.api.resource.ItemResource

class rbtools.api.resource.ItemResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, **kwargs)¶

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: Transport, payload: JSONDict, url: str, token: Optional[str] = None, **kwargs) → None¶

Initialize the resource.

Parameters:

• transport (rbtools.api.transport.Transport) – The API transport.

• payload (dict) – The resource payload.

• url (str) – The resource URL.

• token (str, optional) – The key within the request payload for the resource data.

• **kwargs (dict, unused) – Unused keyword arguments.

__getattr__(name: str) → Any¶

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: str) → Any¶

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:

key (str) – The name of the attribute.

Returns:

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

Return type:

object

Raises:

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

__contains__(key: str) → bool¶

Return whether the resource has a field with the given name.

Parameters:

key (str) – The name of the field.

Returns:

Whether a field with the given name exists.

Return type:

bool

iterfields() → Iterator[str]¶

Iterate through all field names in the resource.

Yields:

str – The name of each field name.

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

Iterate through all field/value pairs in the resource.

Yields:

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

__repr__() → str¶

Return a string representation of the resource.

Returns:

A string representation of the resource.

Return type:

str

delete(*args, **kwargs: Union[bool, int, float, bytes, str]) → None¶

Delete the resource.

Parameters:

• *args (tuple, unused) – Unused positional arguments.

• **kwargs (dict) – Query arguments to include with the request.

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

update(data: Optional[dict[str, Any]] = None, query_args: Optional[dict[str, Union[bool, int, float, bytes, str]]] = None, *args, internal: Literal[False] = False, **kwargs) → Self¶

update(data: Optional[dict[str, Any]] = None, query_args: Optional[dict[str, Union[bool, int, float, bytes, str]]] = None, *args, internal: Literal[True], **kwargs) → HttpRequest

Update the resource.

Any extra_data_json (JSON Merge Patch) or extra_data_json_patch (JSON Patch) fields will be serialized to JSON and stored.

Any extra_data__key fields will be converted to extra_data.key fields, which will be handled by the Review Board API. These cannot store complex types.

Parameters:

• resource (Resource) – The resource instance owning this create method.

• data (dict, optional) – Data to send in the PUT request. This will be merged with **kwargs.

• query_args (dict, optional) – Optional query arguments for the URL.

• *args (tuple, unused) – Unused positional arguments.

• **kwargs (dict) – Keyword arguments representing additional fields to set in the request. This will be merged with data.

Returns:

The updated resource instance.

Return type:

ItemResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

class rbtools.api.resource.ListResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, item_mime_type: Optional[str] = None, **kwargs)¶

Bases: Generic[TItemResource], 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.

__orig_bases__ = (typing.Generic[~TItemResource], <class 'rbtools.api.resource.base.Resource'>)¶

__parameters__ = (~TItemResource,)¶

__init__(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, item_mime_type: Optional[str] = None, **kwargs) → None¶

Initialize the resource.

Parameters:

• transport (rbtools.api.transport.Transport) – The API transport.

• payload (dict or list) – The payload data.

• url (str) – The URL for the resource.

• token (str, optional) – The key within the request payload for the resource data.

• item_mime_type (str, optional) – The mimetype of the items within the list.

• **kwargs (dict) – Keyword arguments to pass through to the base class.

num_items: int¶

The number of items in the current page.

Type:

int

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__() → int¶

Return the length of the list.

Returns:

The number of items in the list.

Return type:

int

__nonzero__() → bool¶

Return whether the list is non-zero.

Returns:

True, always.

Return type:

bool

__bool__() → bool¶

Return whether the list is truthy.

Returns:

True, always.

Return type:

bool

__getitem__(index: int) → TItemResource¶

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__() → Iterator[Any]¶

Iterate through the items.

Yields:

object – Each item in the list.

get_next(**kwargs: Unpack[BaseGetListParams]) → HttpRequest¶

Return the next page of results.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The HTTP request.

Return type:

rbtools.api.request.HttpRequest)

Raises:

StopIteration – There are no more pages of results.

get_prev(**kwargs: Unpack[BaseGetListParams]) → HttpRequest¶

Return the previous page of results.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The HTTP request.

Return type:

rbtools.api.request.HttpRequest)

Raises:

StopIteration – There are no previous pages of results.

get_item(pk: int, **kwargs: Unpack[BaseGetParams]) → HttpRequest¶

Retrieve the item resource with the corresponding primary key.

Parameters:

• pk (int) – The primary key of the item to fetch.

• **kwargs (dict) – Query arguments to include with the request.

Returns:

The HTTP request.

Return type:

rbtools.api.request.HttpRequest

property all_pages: Iterator[Self]¶

Yield all pages of item resources.

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

property all_items: Iterator[Any]¶

Yield all item resources in all pages of this resource.

Yields:

Any – All items in the list.

__repr__() → str¶

Return a string representation of the resource.

create(data: Optional[dict[str, Any]] = None, query_args: Optional[dict[str, Union[bool, int, float, bytes, str]]] = None, *args, internal: Literal[False] = False, **kwargs) → TItemResource¶

create(data: Optional[dict[str, Any]] = None, query_args: Optional[dict[str, Union[bool, int, float, bytes, str]]] = None, *args, internal: Literal[True], **kwargs) → HttpRequest

Create an item resource.

Any extra_data_json (JSON Merge Patch) or extra_data_json_patch (JSON Patch) fields will be serialized to JSON and stored.

Any extra_data__key fields will be converted to extra_data.key fields, which will be handled by the Review Board API. These cannot store complex types.

Parameters:

• resource (Resource) – The resource instance owning this create method.

• data (dict, optional) – Data to send in the POST request. This will be merged with **kwargs.

• query_args (dict, optional) – Optional query arguments for the URL.

• *args (tuple, unused) – Unused positional arguments.

• **kwargs (dict) – Keyword arguments representing additional fields to set in the request. This will be merged with data.

Returns:

The newly-created item resource.

Return type:

ItemResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

class rbtools.api.resource.Resource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, **kwargs)¶

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: Transport, payload: JSONDict, url: str, token: Optional[str] = None, **kwargs) → None¶

Initialize the resource.

Parameters:

• transport (rbtools.api.transport.Transport) – The API transport.

• payload (dict) – The request payload.

• url (str) – The URL for the resource.

• token (str, optional) – The key within the request payload for the resource data.

• **kwargs (dict, unused) – Unused keyword arguments.

property links: ResourceDictField¶

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: JSONDict¶

Return the response payload used to create the resource.

Returns:

The response payload.

Return type:

dict

get_self(*args, **kwargs: Unpack[BaseGetParams]) → Self¶

Get the resource’s ‘self’ link.

Parameters:

• *args (tuple, unused) – Unused positional arguments.

• **kwargs (dict) – Query arguments to include with the request.

Returns:

The newly-fetched resource instance.

Return type:

Resource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

class rbtools.api.resource.ResourceDictField(resource: Resource, fields: dict[str, Any])¶

Bases: MutableMapping[str, Any]

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: Resource, fields: dict[str, Any]) → None¶

Initialize the field.

Parameters:

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

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

__getattr__(name: str) → Any¶

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 (str) – 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: str) → Any¶

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 (str) – 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: str) → None¶

Delete an item from the dictionary.

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

Parameters:

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

Raises:

AttributeError – An error stating that changes are not allowed.

__setitem__(name: str, value: Any) → None¶

Set an item in the dictionary.

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

Parameters:

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

• value (object, unused) – The value to set.

Raises:

AttributeError – An error stating that changes are not allowed.

__len__() → int¶

Return the number of items in the dictionary.

Returns:

The number of items.

Return type:

int

__iter__() → Iterator[Any]¶

Iterate through the dictionary.

Yields:

object – Each item in the dictionary.

__repr__() → str¶

Return a string representation of the dictionary field.

Returns:

The string representation.

Return type:

str

fields() → Iterator[str]¶

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({})¶

__orig_bases__ = (collections.abc.MutableMapping[str, typing.Any],)¶

class rbtools.api.resource.ResourceExtraDataField(resource: Resource, fields: dict[str, Any])¶

Bases: ResourceDictField

Wrapper for extra_data fields on resources.

New in version 3.1.

copy() → dict[str, Any]¶

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.ResourceLinkField(resource: Resource, field_payload: JSONDict)¶

Bases: ResourceDictField, Generic[_TResource]

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: Resource, field_payload: JSONDict) → None¶

Initialize the resource.

Parameters:

• resource (Resource) – The resource which owns this field.

• field_payload (dict) – The field content.

get(**query_args: Union[bool, int, float, bytes, str]) → HttpRequest¶

Fetch the link.

Parameters:

**query_args (dict) – Query arguments to include with the request.

Returns:

The HTTP request.

Return type:

rbtools.api.request.HttpRequest

__abstractmethods__ = frozenset({})¶

__orig_bases__ = (<class 'rbtools.api.resource.base.ResourceDictField'>, typing.Generic[~_TResource])¶

__parameters__ = (~_TResource,)¶

class rbtools.api.resource.ResourceListField(resource: Resource, list_field: list[_TListValue], item_mimetype: Optional[str] = None)¶

Bases: Generic[_TListValue], list[_TListValue]

Wrapper for lists returned from a resource.

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

__init__(resource: Resource, list_field: list[_TListValue], item_mimetype: Optional[str] = None) → None¶

Initialize the field.

Parameters:

• resource (Resource) – The resource which owns this field.

• list_field (list) – The list contents.

• item_mimetype (str, optional) – The mimetype of the list items.

__getitem__(key: int) → _TListValue¶

Return the item at the given index.

Parameters:

key (int) – The index to fetch.

Returns:

The item at the given index.

Return type:

object

__iter__() → Iterator[_TListValue]¶

Iterate through the list.

Yields:

object – Each item in the list.

__repr__() → str¶

Return a string representation of the field.

Returns:

A string representation of the field.

Return type:

str

__orig_bases__ = (typing.Generic[~_TListValue], list[~_TListValue])¶

__parameters__ = (~_TListValue,)¶

class rbtools.api.resource.ReviewRequestItemResource(transport: Transport, payload: JSONDict, url: str, token: Optional[str] = None, **kwargs)¶

Bases: ItemResource

Item resource for review requests.

Changed in version 6.0: Renamed from ReviewRequestResource.

approval_failure: Optional[str]¶

The reason why the review request was not approved.

approved: bool¶

Whether the review request has been approved by reviewers.

On a default install, a review request is approved if it has at least one Ship It! and no open issues. Extensions may change these requirements.

blocks: ResourceListField[ReviewRequestItemResource]¶

The list of review requests that this review request is blocking.

branch: str¶

The branch that the code was changed on or will be committed to.

This is a free-form field that can store any text.

bugs_closed: ResourceListField[str]¶

The list of bugs closed or referenced by this change.

changenum: Optional[int]¶

The change number that the review request represents.

These are server-side repository-specific change numbers, and are not supported by all types of repositories. This is deprecated in favor of the commit_id field.

close_description: str¶

The text describing the closing of the review request.

close_description_text_type: TextType¶

The current or forced text type for the close_description field.

commit_id: str¶

The commit that the review request represents.

created_with_history: bool¶

Whether or not the review request was created with history support.

A value of True indicates that the review request will have commits attached.

depends_on: ResourceListField[ReviewRequestItemResource]¶

The list of review requests that this review request depends on.

description: str¶

The review request’s description.

description_text_type: TextType¶

The current or forced text type for the description field.

extra_data: ResourceExtraDataField¶

Extra data as part of the review request.

id: int¶

The numeric ID of the review request.

issue_dropped_count: int¶

The number of dropped issues on this review request.

issue_open_count: int¶

The number of open issues on this review request.

issue_resolved_count: int¶

The number of resolved issues on this review request.

issue_verifying_count: int¶

The number of issues waiting for verification to resolve or drop.

last_updated: str¶

The date and time that the review request was last updated.

latest_diff: Optional[ResourceLinkField[DiffItemResource]]¶

The most recent diff.

public: bool¶

Whether or not the review request is currently visible to other users.

screenshots: ResourceLinkField[ScreenshotListResource]¶

The screenshots attached to the review request.

ship_it_count: int¶

The number of Ship It-s given to this review request.

status: Union[Literal['discarded'], Literal['pending'], Literal['submitted']]¶

The current status of the review request.

summary: str¶

The review request’s brief summary.

testing_done: str¶

The information on the testing that was done for the change.

testing_done_text_type: TextType¶

The current or forced text type for the testing_done field.

time_added: str¶

The date and time that the review request was added.

property absolute_url: str¶

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.

Type:

str

property url: str¶

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.

Type:

str

submit(description: Optional[str] = None, changenum: Optional[str] = None) → HttpRequest¶

Submit a review request.

Parameters:

• description (str, optional) – The close description text to include.

• changenum (str, optional) – The change number (commit ID) for the review request now that the code has been submitted.

Returns:

The updated review request.

Return type:

ReviewRequestResource

get_or_create_draft(**kwargs: QueryArgs) → HttpRequest¶

Retrieve or create a draft.

Parameters:

**kwargs (dict of rbtools.api.request.QueryArgs) – Query arguments to include with the request.

Returns:

The review request draft.

Return type:

rbtools.api.resource.ItemResource

build_dependency_graph() → defaultdict[Self, set[Self]]¶

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.

get_diffs(**kwargs: Unpack[BaseGetListParams]) → DiffListResource¶

Get the diff list for the review request.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The diff list resource.

Return type:

rbtools.api.resource.DiffListResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

get_file_attachments(**kwargs: Unpack[BaseGetListParams]) → FileAttachmentListResource¶

Get the file attachment list for the review request.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The file attachment list resource.

Return type:

rbtools.api.resource.FileAttachmentListResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

get_latest_diff(**kwargs: Unpack[BaseGetParams]) → DiffItemResource¶

Get the most recent diff list for the review request.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The diff item resource.

Return type:

rbtools.api.resource.DiffItemResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.

get_screenshots(**kwargs: Unpack[BaseGetListParams]) → ScreenshotListResource¶

Get the screenshot list for the review request.

Parameters:

**kwargs (dict) – Query arguments to include with the request.

Returns:

The screenshot list resource.

Return type:

rbtools.api.resource.ScreenshotListResource

Raises:

• rbtools.api.errors.APIError – The Review Board API returned an error.

• rbtools.api.errors.ServerInterfaceError – An error occurred while communicating with the server.