rbtools.commands.post¶

Implementation of rbt post.

Classes

class rbtools.commands.post.DiffHistory(entries: ForwardRef('Sequence[DiffHistoryEntry]'), parent_diff: ForwardRef('bytes'), base_commit_id: ForwardRef('str'), validation_info: ForwardRef('Sequence[str]'), cumulative_diff: ForwardRef('bytes'), review_request_extra_data: ForwardRef('JSONDict'))[source]¶

Bases: NamedTuple

A series of diffs that each correspond to a single revision.

Changed in version 3.1: Added review_request_extra_data.

__annotations_cache__ = {'base_commit_id': ForwardRef('str'), 'cumulative_diff': ForwardRef('bytes'), 'entries': ForwardRef('Sequence[DiffHistoryEntry]'), 'parent_diff': ForwardRef('bytes'), 'review_request_extra_data': ForwardRef('JSONDict'), 'validation_info': ForwardRef('Sequence[str]')}¶

__firstlineno__ = 130¶

__getnewargs__()¶

Return self as a plain tuple. Used by copy and pickle.

__match_args__ = ('entries', 'parent_diff', 'base_commit_id', 'validation_info', 'cumulative_diff', 'review_request_extra_data')¶

static __new__(_cls, entries: ForwardRef('Sequence[DiffHistoryEntry]'), parent_diff: ForwardRef('bytes'), base_commit_id: ForwardRef('str'), validation_info: ForwardRef('Sequence[str]'), cumulative_diff: ForwardRef('bytes'), review_request_extra_data: ForwardRef('JSONDict'))¶

Create new instance of DiffHistory(entries, parent_diff, base_commit_id, validation_info, cumulative_diff, review_request_extra_data)

__replace__(**kwds)¶

Return a new DiffHistory object replacing specified fields with new values

__repr__()¶

Return a nicely formatted representation string

__slots__ = ()¶

__static_attributes__ = ()¶

base_commit_id: ForwardRef('str')¶

The ID of the commit that the diff and parent diff are relative to.

This is required for SCMs like Mercurial that do not use blob IDs for files.

cumulative_diff: ForwardRef('bytes')¶

The cumulative diff of the entire history.

entries: ForwardRef('Sequence[DiffHistoryEntry]')¶

A list of the history entries.

parent_diff: ForwardRef('bytes')¶

The contents of the parent diff.

review_request_extra_data: ForwardRef('JSONDict')¶

State to store in the review request’s extra_data field.

Added in version 3.1.

validation_info: ForwardRef('Sequence[str]')¶

Validation metadata from the commit validation resource.

class rbtools.commands.post.DiffHistoryEntry[source]¶

Bases: TypedDict

An entry in the list of history entries.

Added in version 6.0.

__firstlineno__ = 90¶

__static_attributes__ = ()¶

author_date: str¶

The date and time the commit was authored, in ISO-8601 format.

author_email: str¶

The e-mail address of the commit author.

author_name: str¶

The name of the commit author.

commit_id: str¶

The unique identifier for the commit.

For SCMs like Git, this is a SHA-1 hash.

commit_message: str¶

The message associated with the commit.

committer_date: NotRequired[str]¶

The date and time the commit was created, in ISO-8601 format.

committer_email: NotRequired[str]¶

The e-mail address of the committer.

committer_name: NotRequired[str]¶

The name of the committer.

diff: bytes¶

The contents of the diff.

parent_id: str¶

The unique identifier of the parent commit.

class rbtools.commands.post.Post(transport_cls: type[Transport] = <class 'rbtools.api.transport.sync.SyncTransport'>, stdout: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, stderr: TextIO = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, stdin: TextIO = <_io.TextIOWrapper name='<stdin>' mode='r' encoding='utf-8'>)[source]¶

Bases: BaseCommand

Create and update review requests.

GUESS_AUTO = 'auto'[source]¶

GUESS_CHOICES = ('auto', 'yes', 'no')[source]¶

GUESS_NO = 'no'[source]¶

GUESS_NO_INPUT_VALUES = (False, 'no', 0, '0')[source]¶

GUESS_YES = 'yes'[source]¶

GUESS_YES_INPUT_VALUES = (True, 'yes', 1, '1')[source]¶

__firstlineno__ = 163¶

__static_attributes__ = ('_global_options', 'can_upload_binary_files', 'cmd_args', 'diff_file_attachments_resource', 'revisions')¶

args: ClassVar[str] = '[revisions]'[source]¶

Usage text for what arguments the command takes.

Arguments for the command are anything passed in other than defined options (for example, revisions passed to rbt post).

Type:

str

author: ClassVar[str] = 'The Review Board Project'[source]¶

The author of the command.

Type:

str

can_upload_binary_files: bool¶

Whether both the server and tool can upload binary files to diffs.

Added in version 5.0.

check_guess_fields()[source]¶

Checks and handles field guesses for the review request.

This will attempt to guess the values for the summary and description fields, based on the contents of the commit message at the provided revisions, if requested by the caller.

If the backend doesn’t support guessing, or if guessing isn’t requested, or if explicit values were set in the options, nothing will be set for the fields.

create_parser(*args, **kwargs) → argparse.ArgumentParser[source]¶

Create and return the argument parser for this command.

Added in version 6.0.

Parameters:

• *args (tuple) – Positional arguments to pass to the parent method.

• **kwargs (dict) – Keyword arguments to pass to the parent method.

Returns:

The argument parser.

Return type:

argparse.ArgumentParser

description: ClassVar[str] = 'Uploads diffs to create and update review requests.'[source]¶

A short description of the command, suitable for display in usage text.

Type:

str

diff_file_attachments_resource: DiffFileAttachmentListResource | None¶

The DiffFileAttachments resource for the repository.

Added in version 5.0.

main(*args)[source]¶

Create and update review requests.

Parameters:

*args (tuple) – Command line arguments.

Raises:

rbtools.commands.CommandError – An error occurred while posting.

name: ClassVar[str] = 'post'[source]¶

The name of the command.

Type:

str

needs_api: ClassVar[bool] = True[source]¶

Whether the command needs the API client.

If this is set, the initialization of the command will set api_client and api_root.

Added in version 3.0.

Type:

bool

needs_diffs: ClassVar[bool] = True[source]¶

Whether the command needs to generate diffs.

If this is set, the initialization of the command will check for the presence of a diff tool compatible with the chosen type of repository.

This depends on needs_repository and needs_scm_client both being set to True.

Added in version 4.0.

Type:

bool

needs_repository: ClassVar[bool] = True[source]¶

Whether the command needs the remote repository object.

If this is set, the initialization of the command will set repository.

Setting this will imply setting both needs_api and needs_scm_client to True.

Added in version 3.0.

Type:

bool

needs_scm_client: ClassVar[bool] = True[source]¶

Whether the command needs the SCM client.

If this is set, the initialization of the command will set repository_info and tool.

Added in version 3.0.

Type:

bool

normalize_guess_value(guess, arg_name)[source]¶

option_list: ClassVar[list[Option | OptionGroup]] = [<rbtools.commands.base.options.OptionGroup object>, <rbtools.commands.base.options.OptionGroup object>, <rbtools.commands.base.options.OptionGroup object>, <rbtools.commands.base.options.OptionGroup object>, <rbtools.commands.base.options.OptionGroup object>, <rbtools.commands.base.options.OptionGroup object>, <rbtools.commands.base.options.OptionGroup object>, <rbtools.commands.base.options.OptionGroup object>, <rbtools.commands.base.options.OptionGroup object>, <rbtools.commands.base.options.OptionGroup object>][source]¶

Command-line options for this command.

Type:

list of Option or OptionGroup

post_process_options()[source]¶

Post-process options for the command.

This can validate and update options before the command is invoked.

Raises:

rbtools.commands.base.errors.CommandError – There was an error found with an option.

post_request(review_request: ReviewRequestItemResource | None = None, diff_history: DiffHistory | None = None, squashed_diff: SquashedDiff | None = None, submit_as: str | None = None) → tuple[int, str][source]¶

Create or update a review request, uploading a diff in the process.

Parameters:

• review_request (rbtools.api.resources.ReviewRequestItemResource, optional) –

  The review request to update.

  If not provided, a new review request will be created.

• diff_history (DiffHistory, optional) –

  The diff history to post for multi-commit review requests.

  Exactly one of diff_history and squashed_diff must be specified.

• squashed_diff (SquashedDiff, optional) –

  The squashed diff information to upload when uploading a traditional-style review request.

  Exactly one of diff_history and squashed_diff must be specified.

• submit_as (str, optional) – The username to submit the review request as.

Returns:

A 2-tuple of:

• The review request ID.

• The review request URL.

Return type:

tuple

Raises:

• rbtools.commands.CommandError – An error occurred while posting the review request.

• ValueError – The function was called without one of diff_history or squashed_diff.

reserved_fields = ('description', 'testing-done', 'summary')[source]¶

Reserved built-in fields that can be set using the --field argument.

class rbtools.commands.post.SquashedDiff(diff: ForwardRef('bytes'), parent_diff: ForwardRef('bytes'), base_commit_id: ForwardRef('str'), base_dir: ForwardRef('str'), commit_id: ForwardRef('str'), changenum: ForwardRef('str | None'), review_request_extra_data: ForwardRef('JSONDict'))[source]¶

Bases: NamedTuple

A squashed diff that may be the product of one or more revisions.

Changed in version 3.1: Added review_request_extra_data.

__annotations_cache__ = {'base_commit_id': ForwardRef('str'), 'base_dir': ForwardRef('str'), 'changenum': ForwardRef('str | None'), 'commit_id': ForwardRef('str'), 'diff': ForwardRef('bytes'), 'parent_diff': ForwardRef('bytes'), 'review_request_extra_data': ForwardRef('JSONDict')}¶

__firstlineno__ = 51¶

__getnewargs__()¶

Return self as a plain tuple. Used by copy and pickle.

__match_args__ = ('diff', 'parent_diff', 'base_commit_id', 'base_dir', 'commit_id', 'changenum', 'review_request_extra_data')¶

static __new__(_cls, diff: ForwardRef('bytes'), parent_diff: ForwardRef('bytes'), base_commit_id: ForwardRef('str'), base_dir: ForwardRef('str'), commit_id: ForwardRef('str'), changenum: ForwardRef('str | None'), review_request_extra_data: ForwardRef('JSONDict'))¶

Create new instance of SquashedDiff(diff, parent_diff, base_commit_id, base_dir, commit_id, changenum, review_request_extra_data)

__replace__(**kwds)¶

Return a new SquashedDiff object replacing specified fields with new values

__repr__()¶

Return a nicely formatted representation string

__slots__ = ()¶

__static_attributes__ = ()¶

base_commit_id: ForwardRef('str')¶

The ID of the commit that the diff and parent diff are relative to.

This is required for SCMs like Mercurial that do not use blob IDs for files.

base_dir: ForwardRef('str')¶

The directory that the diff is relative to.

changenum: ForwardRef('str | None')¶

The change number that the diff corresponds to.

This is used for SCMs such as Perforce that use change numbers. For others, this will be None.

commit_id: ForwardRef('str')¶

The ID of the commit the diff corresponds to (if applicable).

diff: ForwardRef('bytes')¶

The contents of the diff.

parent_diff: ForwardRef('bytes')¶

The contents of the parent diff.

review_request_extra_data: ForwardRef('JSONDict')¶

State to store in the review request’s extra_data field.

Added in version 3.1.