rbtools.clients.mercurial¶

A client for Mercurial.

Classes

`MercurialClient`(*[, executable])	A client for Mercurial.
`MercurialPatcher`(, scmclient, *kwargs)	A patcher that applies Mercurial patches to a tree.
`MercurialRefType`()	Types of references in Mercurial.

class rbtools.clients.mercurial.MercurialRefType[source]¶

Bases: object

Types of references in Mercurial.

REVISION = 'revision'[source]¶: Revision hashes.

BRANCH = 'branch'[source]¶: Branch names.

BOOKMARK = 'bookmark'[source]¶: Bookmark names.

TAG = 'tag'[source]¶: Tag names.

UNKNOWN = 'unknown'[source]¶: Unknown references.

class rbtools.clients.mercurial.MercurialPatcher(*, scmclient: TSCMClient, **kwargs: Unpack[PatcherKwargs])[source]¶

Bases: SCMClientPatcher

A patcher that applies Mercurial patches to a tree.

This applies patches using hg import and to manually handle added and deleted empty files.

The patcher supports tracking conflicts and partially-applied patches.

New in version 5.1.

apply_patches() → Iterator[PatchResult][source]¶

Internal function to apply the patches.

If applying files without committing, we’ll open all the files and apply in one hg import operation, helping Mercurial apply them correctly and without triggering an “uncommitted changes” error.

If we’re applying while committing, we’ll use the default Patcher logic to apply and commit them one-by-one.

Yields:: rbtools.diffs.patches.PatchResult – The result of each patch application, whether the patch applied successfully or with normal patch failures.
Raises:: rbtools.diffs.errors.ApplyPatchResult – There was an error attempting to apply a patch. This won’t be raised simply for conflicts or normal patch failures. It may be raised for errors encountered during the patching process.

apply_single_patch(*, patch: Patch, patch_num: int) → PatchResult[source]¶

Internal function to apply a single patch.

This will take a single patch and apply it using Subversion.

Parameters:

patch (rbtools.diffs.patches.Patch) – The patch to apply, opened for reading.
patch_num (int) – The 1-based index of this patch in the full list of patches.

Returns:

The result of the patch application, whether the patch applied successfully or with normal patch failures.

Return type:

rbtools.diffs.patches.PatchResult

__parameters__ = ()¶

class rbtools.clients.mercurial.MercurialClient(*, executable: str = 'hg', **kwargs)[source]¶

Bases: BaseSCMClient

A client for Mercurial.

This is a wrapper around the hg executable that fetches repository information and generates compatible diffs.

scmclient_id: str = 'mercurial'[source]¶

The unique ID of the client.

New in version 4.0: This will be required in RBTools 5.0.

Type:: str

name: str = 'Mercurial'[source]¶

The name of the client.

Type:: str

server_tool_names: ClassVar[Optional[str]] = 'Mercurial,Subversion'[source]¶

A comma-separated list of SCMClient names on the server.

New in version 3.0.

Type:: str

server_tool_ids: ClassVar[Optional[List[str]]] = ['mercurial', 'subversion'][source]¶

A comma-separated list of SCMClient IDs on the server.

This supersedes server_tool_names when running on a version of Review Board that supports passing tool IDs to the repositories list API.

New in version 5.0.1.

Type:: str

patcher_cls[source]¶: alias of MercurialPatcher

supports_commit_history: bool = True[source]¶

Whether the SCM client can generate a commit history.

Type:: bool

supports_diff_exclude_patterns: bool = True[source]¶

Whether the SCM client supports excluding files from the diff.

Type:: bool

supports_parent_diffs: bool = True[source]¶

Whether the SCM client supports generating parent diffs.

New in version 3.0.

Type:: bool

can_bookmark: bool = True[source]¶

Whether new bookmarks can be created.

Type:: bool

can_branch: bool = True[source]¶

Whether new branches can be created.

Type:: bool

can_get_file_content: bool = True[source]¶

Whether the tool can get files at specific revisions.

New in version 5.0.

Type:: bool

can_merge: bool = True[source]¶

Whether the SCM can create merges.

Type:: bool

NO_PARENT = '0000000000000000000000000000000000000000'[source]¶

__init__(*, executable: str = 'hg', **kwargs) → None[source]¶

Initialize the client.

Parameters:

executable (str, optional) – The name of the Mercurial executable to use.
**kwargs (dict) – Keyword arguments to pass through to the superclass.

hgrc: dict[str, Any]¶: The loaded .hgrc content.

check_dependencies() → None[source]¶

Check whether all base dependencies are available.

This checks for the presence of hg (or whichever executable is passed in to the client’s constructor) in the system path.

New in version 4.0.

Raises:: rbtools.clients.errors.SCMClientDependencyError – A hg tool could not be found.

property hidden_changesets_supported: bool[source]¶

Return whether the repository supports hidden changesets.

Mercurial 1.9 and above support hidden changesets. These are changesets that have been hidden from regular repository view. They still exist and are accessible, but only if the –hidden command argument is specified.

Since we may encounter hidden changesets (e.g. the user specifies hidden changesets as part of the revision spec), we need to be aware of hidden changesets.

Type:: bool

property hg_root: Optional[str][source]¶

Return the root of the working directory.

This will return the root directory of the current repository. If the current working directory is not inside a mercurial repository, this returns None.

Type:: str

get_commit_history(revisions: SCMClientRevisionSpec) → Optional[list[SCMClientCommitHistoryItem]][source]¶

Return the commit history specified by the revisions.

Parameters:: revisions (dict) – A dictionary of revisions to generate history for, as returned by parse_revision_spec().
Returns:: This list of history entries, in order.
Return type:: list of dict
Raises:: rbtools.clients.errors.SCMError – The history is non-linear or there is a commit with no parents.

get_local_path() → Optional[str][source]¶

Return the local path to the working tree.

Returns:: The filesystem path of the repository on the client system.
Return type:: str

get_repository_info() → Optional[RepositoryInfo][source]¶

Return repository information for the current working tree.

Returns:: The repository info structure.
Return type:: rbtools.clients.base.repository.RepositoryInfo

parse_revision_spec(revisions: list[str] = []) → SCMClientRevisionSpec[source]¶

Parse the given revision spec.

These will be used to generate the diffs to upload to Review Board (or print). The diff for review will include the changes in (base, tip], and the parent diff (if necessary) will include (parent, base].

If zero revisions are passed in, this will return the outgoing changes from the parent of the working directory.

If a single revision is passed in, this will return the parent of that revision for “base” and the passed-in revision for “tip”. This will result in generating a diff for the changeset specified.

If two revisions are passed in, they will be used for the “base” and “tip” revisions, respectively.

In all cases, a parent base will be calculated automatically from changesets not present on the remote.

Parameters:

revisions (list of str, optional) – A list of revisions as specified by the user.

Returns:

The parsed revision spec.

See SCMClientRevisionSpec for the format of this dictionary.

This always populates base and tip.

commit_id and parent_base may also be populated.

Return type:

dict

Raises:

rbtools.clients.errors.InvalidRevisionSpecError – The given revisions could not be parsed.
rbtools.clients.errors.TooManyRevisionsError – The specified revisions list contained too many revisions.

get_hg_ref_type(ref: str) → str[source]¶

Return the type of a reference in Mercurial.

This can be used to determine if something is a bookmark, branch, tag, or revision.

Parameters:: ref (str) – The reference to return the type for.
Returns:: The reference type. This will be a value in MercurialRefType.
Return type:: str

get_raw_commit_message(revisions: SCMClientRevisionSpec) → str[source]¶

Return the raw commit message.

This extracts all descriptions in the given revision range and concatenates them, most recent ones going first.

Parameters:: revisions (dict) – A dictionary containing base and tip keys.
Returns:: The commit messages of all commits between (base, tip].
Return type:: str

diff(revisions: SCMClientRevisionSpec, *, include_files: list[str] = [], exclude_patterns: list[str] = [], with_parent_diff: bool = True, **kwargs) → SCMClientDiffResult[source]¶

Perform a diff using the given revisions.

This will generate a Git-style diff and parent diff (if needed) for the provided revisions. The diff will contain additional metadata headers used by Review Board to locate the appropriate revisions from the repository.

Parameters:

revisions (dict) – A dictionary of revisions, as returned by parse_revision_spec().
include_files (list of str, optional) – A list of files to whitelist during the diff generation.
exclude_patterns (list of str, optional) – A list of shell-style glob patterns to blacklist during diff generation.
with_parent_diff (bool, optional) – Whether or not to include the parent diff in the result.
**kwargs (dict, unused) – Unused keyword arguments.

Returns:

A dictionary containing keys documented in SCMClientDiffResult.

Return type:

dict

create_commit(message: str, author: PatchAuthor, run_editor: bool, files: list[str] = [], all_files: bool = False) → None[source]¶

Commit the given modified files.

This is expected to be called after applying a patch. This commits the patch using information from the review request, opening the commit message in $EDITOR to allow the user to update it.

Parameters:

message (str) – The commit message to use.
author (rbtools.clients.base.scmclient.PatchAuthor) – The author of the commit. This is expected to have fullname and email attributes.
run_editor (bool) – Whether to run the user’s editor on the commit message before committing.
files (list of str, optional) – The list of filenames to commit.
all_files (bool, optional) – Whether to commit all changed files, ignoring the files argument.

Raises:

rbtools.clients.errors.CreateCommitError – The commit message could not be created. It may have been aborted by the user.

merge(target: str, destination: str, message: str, author: PatchAuthor, squash: bool = False, run_editor: bool = False, close_branch: bool = False, **kwargs) → None[source]¶

Merge the target branch with destination branch.

Parameters:

target (str) – The name of the branch to merge.
destination (str) – The name of the branch to merge into.
message (str) – The commit message to use.
author (rbtools.clients.base.scmclient.PatchAuthor) – The author of the commit. This is expected to have fullname and email attributes.
squash (bool, optional) – Whether to squash the commits or do a plain merge. This is not used for Mercurial.
run_editor (bool, optional) – Whether to run the user’s editor on the commit message before committing.
close_branch (bool, optional) – Whether to delete the branch after merging.
**kwargs (dict, unused) – Additional keyword arguments passed, for future expansion.

Raises:

rbtools.clients.errors.MergeError – An error occurred while merging the branch.

scan_for_server(repository_info: RepositoryInfo) → Optional[str][source]¶

Find the Review Board server matching this repository.

Parameters:: repository_info (rbtools.clients.base.repository.RepositoryInfo) – The repository information structure.
Returns:: The Review Board server URL, if available.
Return type:: str

has_pending_changes() → bool[source]¶

Check if there are changes waiting to be committed.

Returns:: True if the working directory has been modified, otherwise returns False.
Return type:: bool

supports_empty_files() → bool[source]¶

Return whether the RB server supports added/deleted empty files.

Returns:: True if the Review Board server supports showing empty files.
Return type:: bool

get_current_bookmark() → str[source]¶

Return the name of the current bookmark.

Returns:: A string with the name of the current bookmark.
Return type:: str

get_file_content(*, filename: str, revision: str) → bytes[source]¶

Return the contents of a file at a given revision.

New in version 5.0.

Parameters:

filename (str) – The file to fetch.
revision (str) – The revision of the file to get.

Returns:

The read file.

Return type:

bytes

get_file_size(*, filename: str, revision: str) → int[source]¶

Return the size of a file at a given revision.

New in version 5.0.

Parameters:

filename (str) – The file to check.
revision (str) – The revision of the file to check.

Returns:

The size of the file, in bytes.

Return type:

int