rbtools.clients.mercurial¶

A client for Mercurial.

Classes

`MercurialClient`(*[, executable])	A client for Mercurial.
`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.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: Optional[str] = 'Mercurial,Subversion'[source]¶

A comma-separated list of SCMClient names on the server

New in version 3.0.

Type:: str

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

PRE_CREATION = '/dev/null'[source]¶

PRE_CREATION_DATE = 'Thu Jan 01 00:00:00 1970 +0000'[source]¶

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

apply_patch(patch_file: str, base_path: Optional[str] = None, base_dir: Optional[str] = None, p: Optional[str] = None, revert: bool = False) → PatchResult[source]¶

Apply the given patch.

This will take the given patch file and apply it to the working directory.

Parameters:

patch_file (str) – The name of the patch file to apply.
base_path (str, unused) – The base path that the diff was generated in. All hg diffs are absolute to the repository root, so this is unused.
base_dir (str, unused) – The path of the current working directory relative to the root of the repository. All hg diffs are absolute to the repository root, so this is unused.
p (str, optional) – The prefix level of the diff.
revert (bool, optional) – Whether the patch should be reverted rather than applied.

Returns:

The result of the patch operation.

Return type:

rbtools.clients.base.patch.PatchResult

apply_patch_for_empty_files(patch: bytes, p_num: str, revert: bool = False) → bool[source]¶

Return whether any empty files in the patch are applied.

Parameters:

patch (bytes) – The contents of the patch.
p_num (str) – The prefix level of the diff.
revert (bool, optional) – Whether the patch should be reverted rather than applied.

Returns:

True if there are empty files in the patch. False if there were no empty files, or if an error occurred while applying the patch.

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