rbtools.api.resource.base¶

Resource base classes for the RBTools Python API.

Module Attributes

Functions

Classes

class rbtools.api.resource.base.BaseGetListParams[source]¶

Bases: BaseGetParams

Base class for parameters for GET requests on lists.

Added in version 6.0.

__firstlineno__ = 580¶

__static_attributes__ = ()¶

counts_only: bool¶

If specified, return only the counts.

Making a request with this will return a CountResource instead of a list.

expand: str¶

max_results: int¶

The maximum number of results to return in the request.

By default, this is 25. There is a hard limit of 200; if you need more than 200 results, you will need to make more than one request.

only_fields: str¶

only_links: str¶

start: int¶

The 0-based index of the first result in the list.

To page through results, the start index should be set to the previous start index plus the number of previous results.

class rbtools.api.resource.base.BaseGetParams[source]¶

Bases: TypedDict

Base class for parameters for GET requests.

This has the basic fields that are supported by all resource endpoints.

Added in version 6.0.

__firstlineno__ = 561¶

__static_attributes__ = ()¶

expand: str¶

A comma-separated list of links to expand within the returned payload.

only_fields: str¶

A comma-separated list of fields to limit the payload to.

only_links: str¶

A comma-separated list of links to limit the payload to.

class rbtools.api.resource.base.CountResource(transport: Transport, payload: JSONDict, url: str, **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.

__firstlineno__ = 1786¶

__init__(transport: Transport, payload: JSONDict, url: str, **kwargs) → None[source]¶

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.

__static_attributes__ = ()¶

get_self(**kwargs: bool | int | float | bytes | str) → HttpRequest[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

Parameters:

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

rbtools.api.resource.base.EXPANDED_TOKEN: Final[str] = '_expanded'¶

The name of the expanded info structure within a response payload.

class rbtools.api.resource.base.ExpandInfo[source]¶

Bases: TypedDict

Information on expanded resources.

This corresponds to djblets.webapi.resources.base._ExpandInfo.

Added in version 6.0.

__firstlineno__ = 542¶

__static_attributes__ = ()¶

item_mimetype: str¶

The MIME type of an expanded item resource.

list_mimetype: NotRequired[str]¶

The MIME type of an expanded list resource.

list_url: NotRequired[str | None]¶

The URL to an expanded list resource, if any.

class rbtools.api.resource.base.ItemResource(transport: Transport, payload: JSONDict, url: str, token: str | None = 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.

__contains__(key: str) → bool[source]¶

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

__firstlineno__ = 1500¶

__getattr__(name: str) → Any[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: str) → Any[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:

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.

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

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.

__repr__() → str[source]¶

Return a string representation of the resource.

Returns:

A string representation of the resource.

Return type:

str

__static_attributes__ = ('_fields',)¶

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

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.

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

Iterate through all field names in the resource.

Yields:

str – The name of each field name.

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

Iterate through all field/value pairs in the resource.

Yields:

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

update(data: Mapping[str, Any] | None = None, query_args: Mapping[str, QueryArgs] | None = None, *args, internal: Literal[False] = False, **kwargs) → Self[source]¶

update(data: Mapping[str, Any] | None = None, query_args: Mapping[str, QueryArgs] | None = 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.

rbtools.api.resource.base.LINKS_TOK: Final[str] = 'links'¶

The name of the links structure within a response payload.

rbtools.api.resource.base.LINK_KEYS: set[str] = {'href', 'method', 'mimetype', 'title'}¶

Keys within a link dict.

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

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.

__bool__() → bool[source]¶

Return whether the list is truthy.

Returns:

True, always.

Return type:

bool

__firstlineno__ = 1846¶

__getitem__(index: int) → TItemResource[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.

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

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.

__iter__() → Iterator[TItemResource][source]¶

Iterate through the items.

Yields:

TItemResource – Each item in the list.

__len__() → int[source]¶

Return the length of the list.

Returns:

The number of items in the list.

Return type:

int

__repr__() → str[source]¶

Return a string representation of the resource.

__static_attributes__ = ('_item_list', '_item_mime_type', 'num_items', 'total_results')¶

property all_items: Iterator[TItemResource][source]¶

Yield all item resources in all pages of this resource.

Yields:

TItemResource – All items in the list.

property all_pages: Iterator[Self][source]¶

Yield all pages of item resources.

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

create(data: dict[str, Any] | None = None, query_args: dict[str, QueryArgs] | None = None, *args, internal: Literal[False] = False, **kwargs) → TItemResource[source]¶

create(data: dict[str, Any] | None = None, query_args: dict[str, QueryArgs] | None = 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.

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

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

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

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[source]¶

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.

num_items: int¶

The number of items in the current page.

Type:

int

total_results: int | None¶

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

rbtools.api.resource.base.RESOURCE_MAP: dict[str, type[Resource]] = {'application/vnd.reviewboard.org.api-token': <class 'rbtools.api.resource.api_token.APITokenItemResource'>, 'application/vnd.reviewboard.org.api-tokens': <class 'rbtools.api.resource.api_token.APITokenListResource'>, 'application/vnd.reviewboard.org.archived-review-request': <class 'rbtools.api.resource.archived_review_request.ArchivedReviewRequestItemResource'>, 'application/vnd.reviewboard.org.archived-review-requests': <class 'rbtools.api.resource.muted_review_request.MutedReviewRequestListResource'>, 'application/vnd.reviewboard.org.commit': <class 'rbtools.api.resource.diff_commit.DiffCommitItemResource'>, 'application/vnd.reviewboard.org.commit-validation': <class 'rbtools.api.resource.validate_diff_commit.ValidateDiffCommitResource'>, 'application/vnd.reviewboard.org.commits': <class 'rbtools.api.resource.diff_commit.DiffCommitListResource'>, 'application/vnd.reviewboard.org.default-reviewer': <class 'rbtools.api.resource.default_reviewer.DefaultReviewerItemResource'>, 'application/vnd.reviewboard.org.default-reviewers': <class 'rbtools.api.resource.default_reviewer.DefaultReviewerListResource'>, 'application/vnd.reviewboard.org.diff': <class 'rbtools.api.resource.diff.DiffItemResource'>, 'application/vnd.reviewboard.org.diff-context': <class 'rbtools.api.resource.diff_context.DiffContextResource'>, 'application/vnd.reviewboard.org.diff-file-attachment': <class 'rbtools.api.resource.diff_file_attachment.DiffFileAttachmentItemResource'>, 'application/vnd.reviewboard.org.diff-file-attachments': <class 'rbtools.api.resource.diff_file_attachment.DiffFileAttachmentListResource'>, 'application/vnd.reviewboard.org.diff-validation': <class 'rbtools.api.resource.validate_diff.ValidateDiffResource'>, 'application/vnd.reviewboard.org.diffs': <class 'rbtools.api.resource.diff.DiffListResource'>, 'application/vnd.reviewboard.org.draft-commit': <class 'rbtools.api.resource.draft_diff_commit.DraftDiffCommitItemResource'>, 'application/vnd.reviewboard.org.draft-commits': <class 'rbtools.api.resource.draft_diff_commit.DraftDiffCommitListResource'>, 'application/vnd.reviewboard.org.draft-file-attachment': <class 'rbtools.api.resource.draft_file_attachment.DraftFileAttachmentItemResource'>, 'application/vnd.reviewboard.org.draft-file-attachments': <class 'rbtools.api.resource.draft_file_attachment.DraftFileAttachmentListResource'>, 'application/vnd.reviewboard.org.draft-screenshot': <class 'rbtools.api.resource.draft_screenshot.DraftScreenshotItemResource'>, 'application/vnd.reviewboard.org.draft-screenshots': <class 'rbtools.api.resource.draft_screenshot.DraftScreenshotListResource'>, 'application/vnd.reviewboard.org.extension': <class 'rbtools.api.resource.extension.ExtensionItemResource'>, 'application/vnd.reviewboard.org.extensions': <class 'rbtools.api.resource.extension.ExtensionListResource'>, 'application/vnd.reviewboard.org.file': <class 'rbtools.api.resource.file_diff.FileDiffItemResource'>, 'application/vnd.reviewboard.org.file-attachment': <class 'rbtools.api.resource.file_attachment.FileAttachmentItemResource'>, 'application/vnd.reviewboard.org.file-attachment-comment': <class 'rbtools.api.resource.file_attachment_comment.FileAttachmentCommentItemResource'>, 'application/vnd.reviewboard.org.file-attachment-comments': <class 'rbtools.api.resource.file_attachment_comment.FileAttachmentCommentListResource'>, 'application/vnd.reviewboard.org.file-attachments': <class 'rbtools.api.resource.file_attachment.FileAttachmentListResource'>, 'application/vnd.reviewboard.org.file-diff-diff-comments': <class 'rbtools.api.resource.diff_comment.DiffCommentListResource'>, 'application/vnd.reviewboard.org.files': <class 'rbtools.api.resource.file_diff.FileDiffListResource'>, 'application/vnd.reviewboard.org.general-comment': <class 'rbtools.api.resource.general_comment.GeneralCommentItemResource'>, 'application/vnd.reviewboard.org.general-comments': <class 'rbtools.api.resource.general_comment.GeneralCommentListResource'>, 'application/vnd.reviewboard.org.hosting-service': <class 'rbtools.api.resource.hosting_service.HostingServiceItemResource'>, 'application/vnd.reviewboard.org.hosting-service-account': <class 'rbtools.api.resource.hosting_service_account.HostingServiceAccountItemResource'>, 'application/vnd.reviewboard.org.hosting-service-accounts': <class 'rbtools.api.resource.hosting_service_account.HostingServiceAccountListResource'>, 'application/vnd.reviewboard.org.hosting-services': <class 'rbtools.api.resource.hosting_service.HostingServiceListResource'>, 'application/vnd.reviewboard.org.last-update': <class 'rbtools.api.resource.last_update.LastUpdateResource'>, 'application/vnd.reviewboard.org.muted-review-request': <class 'rbtools.api.resource.muted_review_request.MutedReviewRequestItemResource'>, 'application/vnd.reviewboard.org.oauth-app': <class 'rbtools.api.resource.oauth_application.OAuthApplicationItemResource'>, 'application/vnd.reviewboard.org.oauth-apps': <class 'rbtools.api.resource.oauth_application.OAuthApplicationListResource'>, 'application/vnd.reviewboard.org.oauth-token': <class 'rbtools.api.resource.oauth_token.OAuthTokenItemResource'>, 'application/vnd.reviewboard.org.oauth-tokens': <class 'rbtools.api.resource.oauth_token.OAuthTokenListResource'>, 'application/vnd.reviewboard.org.remote-repositories': <class 'rbtools.api.resource.remote_repository.RemoteRepositoryListResource'>, 'application/vnd.reviewboard.org.remote-repository': <class 'rbtools.api.resource.remote_repository.RemoteRepositoryItemResource'>, 'application/vnd.reviewboard.org.repositories': <class 'rbtools.api.resource.repository.RepositoryListResource'>, 'application/vnd.reviewboard.org.repository': <class 'rbtools.api.resource.repository.RepositoryItemResource'>, 'application/vnd.reviewboard.org.repository-branches': <class 'rbtools.api.resource.repository_branch.RepositoryBranchListResource'>, 'application/vnd.reviewboard.org.repository-commits': <class 'rbtools.api.resource.repository_commit.RepositoryCommitListResource'>, 'application/vnd.reviewboard.org.repository-group': <class 'rbtools.api.resource.repository_group.RepositoryGroupItemResource'>, 'application/vnd.reviewboard.org.repository-groups': <class 'rbtools.api.resource.repository_group.RepositoryGroupListResource'>, 'application/vnd.reviewboard.org.repository-info': <class 'rbtools.api.resource.repository_info.RepositoryInfoResource'>, 'application/vnd.reviewboard.org.repository-user': <class 'rbtools.api.resource.repository_user.RepositoryUserItemResource'>, 'application/vnd.reviewboard.org.repository-users': <class 'rbtools.api.resource.repository_user.RepositoryUserListResource'>, 'application/vnd.reviewboard.org.review': <class 'rbtools.api.resource.review.ReviewItemResource'>, 'application/vnd.reviewboard.org.review-diff-comment': <class 'rbtools.api.resource.diff_comment.DiffCommentItemResource'>, 'application/vnd.reviewboard.org.review-diff-comments': <class 'rbtools.api.resource.diff_comment.DiffCommentListResource'>, 'application/vnd.reviewboard.org.review-group': <class 'rbtools.api.resource.review_group.ReviewGroupItemResource'>, 'application/vnd.reviewboard.org.review-group-user': <class 'rbtools.api.resource.review_group_user.ReviewGroupUserItemResource'>, 'application/vnd.reviewboard.org.review-group-users': <class 'rbtools.api.resource.review_group_user.ReviewGroupUserListResource'>, 'application/vnd.reviewboard.org.review-groups': <class 'rbtools.api.resource.review_group.ReviewGroupListResource'>, 'application/vnd.reviewboard.org.review-replies': <class 'rbtools.api.resource.review_reply.ReviewReplyListResource'>, 'application/vnd.reviewboard.org.review-reply': <class 'rbtools.api.resource.review_reply.ReviewReplyItemResource'>, 'application/vnd.reviewboard.org.review-reply-diff-comment': <class 'rbtools.api.resource.diff_comment.DiffCommentItemResource'>, 'application/vnd.reviewboard.org.review-reply-diff-comments': <class 'rbtools.api.resource.diff_comment.DiffCommentListResource'>, 'application/vnd.reviewboard.org.review-reply-file-attachment-comment': <class 'rbtools.api.resource.file_attachment_comment.FileAttachmentCommentItemResource'>, 'application/vnd.reviewboard.org.review-reply-file-attachment-comments': <class 'rbtools.api.resource.file_attachment_comment.FileAttachmentCommentListResource'>, 'application/vnd.reviewboard.org.review-reply-general-comment': <class 'rbtools.api.resource.general_comment.GeneralCommentItemResource'>, 'application/vnd.reviewboard.org.review-reply-general-comments': <class 'rbtools.api.resource.general_comment.GeneralCommentListResource'>, 'application/vnd.reviewboard.org.review-request': <class 'rbtools.api.resource.review_request.ReviewRequestItemResource'>, 'application/vnd.reviewboard.org.review-request-change': <class 'rbtools.api.resource.change.ChangeItemResource'>, 'application/vnd.reviewboard.org.review-request-changes': <class 'rbtools.api.resource.change.ChangeListResource'>, 'application/vnd.reviewboard.org.review-request-draft': <class 'rbtools.api.resource.review_request_draft.ReviewRequestDraftResource'>, 'application/vnd.reviewboard.org.review-requests': <class 'rbtools.api.resource.review_request.ReviewRequestListResource'>, 'application/vnd.reviewboard.org.reviews': <class 'rbtools.api.resource.review.ReviewListResource'>, 'application/vnd.reviewboard.org.root': <class 'rbtools.api.resource.root.RootResource'>, 'application/vnd.reviewboard.org.screenshot': <class 'rbtools.api.resource.screenshot.ScreenshotItemResource'>, 'application/vnd.reviewboard.org.screenshot-comment': <class 'rbtools.api.resource.screenshot_comment.ScreenshotCommentItemResource'>, 'application/vnd.reviewboard.org.screenshot-comments': <class 'rbtools.api.resource.screenshot_comment.ScreenshotCommentListResource'>, 'application/vnd.reviewboard.org.screenshots': <class 'rbtools.api.resource.screenshot.ScreenshotListResource'>, 'application/vnd.reviewboard.org.search': <class 'rbtools.api.resource.search.SearchResource'>, 'application/vnd.reviewboard.org.server-info': <class 'rbtools.api.resource.server_info.ServerInfoResource'>, 'application/vnd.reviewboard.org.session': <class 'rbtools.api.resource.session.SessionResource'>, 'application/vnd.reviewboard.org.status-update': <class 'rbtools.api.resource.status_update.StatusUpdateItemResource'>, 'application/vnd.reviewboard.org.status-updates': <class 'rbtools.api.resource.status_update.StatusUpdateListResource'>, 'application/vnd.reviewboard.org.user': <class 'rbtools.api.resource.user.UserItemResource'>, 'application/vnd.reviewboard.org.user-file-attachment': <class 'rbtools.api.resource.user_file_attachment.UserFileAttachmentItemResource'>, 'application/vnd.reviewboard.org.user-file-attachments': <class 'rbtools.api.resource.user_file_attachment.UserFileAttachmentListResource'>, 'application/vnd.reviewboard.org.users': <class 'rbtools.api.resource.user.UserListResource'>, 'application/vnd.reviewboard.org.validation': <class 'rbtools.api.resource.validation.ValidationResource'>, 'application/vnd.reviewboard.org.watched': <class 'rbtools.api.resource.watched.WatchedResource'>, 'application/vnd.reviewboard.org.watched-review-group': <class 'rbtools.api.resource.watched_review_group.WatchedReviewGroupItemResource'>, 'application/vnd.reviewboard.org.watched-review-groups': <class 'rbtools.api.resource.watched_review_group.WatchedReviewGroupListResource'>, 'application/vnd.reviewboard.org.watched-review-request': <class 'rbtools.api.resource.watched_review_request.WatchedReviewRequestItemResource'>, 'application/vnd.reviewboard.org.watched-review-requests': <class 'rbtools.api.resource.watched_review_request.WatchedReviewRequestListResource'>, 'application/vnd.reviewboard.org.webhook': <class 'rbtools.api.resource.webhook.WebHookItemResource'>, 'application/vnd.reviewboard.org.webhooks': <class 'rbtools.api.resource.webhook.WebHookListResource'>, 'text/plain': <class 'rbtools.api.resource.plain_text.PlainTextResource'>}¶

Map from MIME type to resource class.

rbtools.api.resource.base.RequestMethodResult = rbtools.api.request.HttpRequest | rbtools.api.resource.base.Resource | None[source]¶

The resulting type of a resource method.

Added in version 6.0.

class rbtools.api.resource.base.Resource(transport: Transport, payload: JSONDict, url: str, token: str | None = 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.

__firstlineno__ = 606¶

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

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.

__static_attributes__ = ('_expanded_info', '_links', '_payload', '_token', '_transport', '_url')¶

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

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.

property links: ResourceDictField[source]¶

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[source]¶

Return the response payload used to create the resource.

Returns:

The response payload.

Return type:

dict

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

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).

__abstractmethods__ = frozenset({})¶

__delitem__(name: str) → None[source]¶

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.

__firstlineno__ = 1065¶

__getattr__(name: str) → Any[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 (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[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 (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.

__init__(resource: Resource, fields: dict[str, Any]) → None[source]¶

Initialize the field.

Parameters:

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

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

__iter__() → Iterator[Any][source]¶

Iterate through the dictionary.

Yields:

object – Each item in the dictionary.

__len__() → int[source]¶

Return the number of items in the dictionary.

Returns:

The number of items.

Return type:

int

__repr__() → str[source]¶

Return a string representation of the dictionary field.

Returns:

The string representation.

Return type:

str

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

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.

__static_attributes__ = ('_fields', '_resource')¶

fields() → Iterator[str][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.

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

Bases: ResourceDictField

Wrapper for extra_data fields on resources.

Added in version 3.1.

__abstractmethods__ = frozenset({})¶

__annotations_cache__ = {'_fields': 'dict[str, Any]', '_resource': 'Resource'}¶

__firstlineno__ = 1346¶

__static_attributes__ = ()¶

copy() → dict[str, Any][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

class rbtools.api.resource.base.ResourceLink[source]¶

Bases: TypedDict

Type for a link within a payload.

Added in version 6.0.

__firstlineno__ = 515¶

__static_attributes__ = ()¶

href: str¶

The link URL.

method: str¶

The HTTP method to use for the link.

mimetype: NotRequired[str]¶

The MIME type of the object located at the link.

title: NotRequired[str]¶

The user-visible title of the object located at the link.

class rbtools.api.resource.base.ResourceLinkField(resource: Resource, field_payload: JSONDict)[source]¶

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.

__abstractmethods__ = frozenset({})¶

__firstlineno__ = 1290¶

__init__(resource: Resource, field_payload: JSONDict) → None[source]¶

Initialize the resource.

Parameters:

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

• field_payload (dict) – The field content.

__static_attributes__ = ('_transport',)¶

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

Fetch the link.

Parameters:

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

Returns:

The HTTP request.

Return type:

rbtools.api.request.HttpRequest

rbtools.api.resource.base.ResourceLinks[source]¶

Type for link data within the payload.

Added in version 6.0.

alias of dict[str, ResourceLink]

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

Bases: Generic[_TListValue], list[_TListValue]

Wrapper for lists returned from a resource.

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

__firstlineno__ = 1418¶

__getitem__(key: int) → _TListValue[source]¶

Return the item at the given index.

Parameters:

key (int) – The index to fetch.

Returns:

The item at the given index.

Return type:

object

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

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.

__iter__() → Iterator[_TListValue][source]¶

Iterate through the list.

Yields:

object – Each item in the list.

__repr__() → str[source]¶

Return a string representation of the field.

Returns:

A string representation of the field.

Return type:

str

__static_attributes__ = ('_item_mimetype', '_resource')¶

rbtools.api.resource.base.TextType[source]¶

Constants for text type fields.

Added in version 6.0.

alias of Literal[‘plain’, ‘markdown’, ‘html’]

rbtools.api.resource.base.api_stub(f: Callable[[_P], _T]) → Callable[[_P], _T][source]¶

Mark a method as being an API stub.

Added in version 6.0.

Parameters:

f (callable) – The stub method.

Returns:

The stub method.

Return type:

callable

rbtools.api.resource.base.is_api_stub(f: Callable[[...], Any]) → bool[source]¶

Return whether a given method is an API stub.

Added in version 6.0.

Parameters:

f (callable) – The method to check.

Returns:

True if the method was decorated with api_stub(). False, otherwise.

Return type:

bool

rbtools.api.resource.base.replace_api_stub(obj: Resource, attr: str, stub: Callable[[...], Any], implementation: Callable[[...], Any]) → None[source]¶

Replace an API stub with a real implementation.

Added in version 6.0.

Parameters:

• obj (Resource) – The resource object which owns the method.

• attr (str) – The name of the method.

• stub (callable) – The stub method.

• implementation (callable) – The method implementation.

rbtools.api.resource.base.request_method(f: Callable[[_P], HttpRequest]) → Callable[[_P], HttpRequest | Resource | None][source]¶

Wrap a method returned from a resource to capture HttpRequests.

When a method which returns HttpRequests is called, it will pass the method and arguments off to the transport to be executed.

This wrapping allows the transport to skim arguments off the top of the method call, and modify any return values (such as executing a returned HttpRequest).

However, if called with the internal argument set to True, the method itself will be executed and the value returned as-is. Thus, any method calls embedded inside the code for another method should use the internal argument to access the expected value.

Changed in version 6.0: Moved and renamed from rbtools.api.decorators.request_method_decorator.

Parameters:

f (callable) – The method to wrap.

Returns:

The wrapped method.

Return type:

callable

class rbtools.api.resource.base.request_method_returns[source]¶

Bases: Generic[_TResource]

Decorator to mark request methods with a specific return type.

When the return type of a method is known to be a specific type, this decorator can be used in place of @request_method, and will rewrite the annotation of the return value of the decorated method.

Added in version 6.0.

__annotations_cache__ = {}¶

__call__(f: Callable[[_P], HttpRequest]) → Callable[[_P], _TResource][source]¶

Decorate the method.

Parameters:

f (callable) – The method to decorate.

__firstlineno__ = 1031¶

__static_attributes__ = ()¶

rbtools.api.resource.base.resource_mimetype(mimetype: str) → Callable[[_TResourceClass], _TResourceClass][source]¶

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

Parameters:

mimetype (str) – The MIME type for the resource.

Returns:

A decorator to apply to a resource class.

Return type:

callable