rbtools.clients.perforce¶

A client for Perforce.

Classes

`P4Wrapper`(options)	A wrapper around p4 commands.
`PerforceClient`([p4_class])	A client for Perforce.
`PerforcePatcher`(, scmclient, *kwargs)	A patcher that applies Perforce patches to a tree.

class rbtools.clients.perforce.P4Wrapper(options)[source]¶

Bases: object

A wrapper around p4 commands.

All calls out to p4 go through an instance of this class. It keeps a separation between all the standard SCMClient logic and any parsing and handling of p4 invocation and results.

COUNTERS_RE = re.compile('^([^ ]+) = (.+)$')[source]¶

KEYVAL_RE = re.compile('^([^:]+): (.+)$')[source]¶

__annotations_cache__ = {}¶

__firstlineno__ = 49¶

__init__(options)[source]¶

Initialize the wrapper.

Parameters:: options (argparse.Namespace) – The parsed command line options.

__static_attributes__ = ('options',)¶

change(changenum: int, marshalled: Literal[True] = True) → Sequence[Mapping[str, Any]][source]¶

change(changenum: int, marshalled: Literal[False]) → str

Return the contents of a p4 change description.

Parameters:

changenum (int) – The number of the changeset to list.
marshalled (bool, optional) – Whether to return the data in marshalled form.

Returns:

The contents of the change description, either as a unicode object or a list depending on the value of marshalled.

Return type:

object

check_dependencies() → None[source]¶

Check whether all base dependencies are available.

This checks for the presence of p4 in the system path.

Added in version 4.0.

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

counters()[source]¶

Return the Perforce counters.

Returns:: The parsed Perforce counters.
Return type:: dict

filelog(path: str) → Sequence[Mapping[str, Any]][source]¶

Return a list of all the changed files within the given path.

Parameters:: path (str) – The Perforce path to check. This is expected to be a path with two revision markers (//...@X,Y).
Returns:: A list of the various changed files and how they were changed.
Return type:: list

files(path: str) → Sequence[Mapping[str, Any]][source]¶

Return the opened files within the given path.

Parameters:: path (str) – The Perforce path to check. This can be a mix of file paths (//...) and revisions (...@X).
Returns:: A list of the opened files.
Return type:: list

fstat(depot_path: str, fields: Sequence[str] | None = None) → Mapping[str, str][source]¶

Run p4 fstat on a given depot path.

Parameters:

depot_path (str) – The file path to stat.
fields (list of str, optional) – The fields to fetch.

Returns:

The file stat info.

Return type:

dict

info()[source]¶

Run p4 info and return the results.

Returns:: The parsed output from p4 info.
Return type:: dict

is_supported()[source]¶

Check whether the p4 command is usable.

Returns:: True if there’s an executable p4.
Return type:: bool

modify_change(new_change_spec: str, *, changenum: str | None = None) → None[source]¶

Modify a change description.

Parameters:

new_change_spec (str) – The new changeset description. This must contain the changelist number.
changenum (str, optional) – The change number to modify.

opened(changenum: int) → Sequence[Mapping[str, Any]][source]¶

Return the list of opened files in the given changeset.

Parameters:: changenum (int) – The number of the changeset.
Returns:: A list of the opened files in the given changeset.
Return type:: list

print_file(depot_path: str, out_file: str | None = None) → str[source]¶

Print the contents of the given file.

Parameters:

depot_path (str) – A Perforce path, including filename and revision.
out_file (str, optional) – A filename to write to. If not specified, the data will be returned.

Returns:

The output of the print operation.

Return type:

str

run_p4(p4_args: Sequence[str], *args, marshalled: Literal[True], **kwargs: Unpack[RunProcessKwargs]) → Sequence[Mapping[str, Any]][source]¶

run_p4(p4_args: Sequence[str], *args, marshalled: Literal[False] = False, **kwargs: Unpack[RunProcessKwargs]) → RunProcessResult

Invoke p4.

Changed in version 6.0: Updated to use run_process() instead of rbtools.utils.execute(). This means in cases where marshalled is False, this method now returns a RunProcessResult.

Parameters:

p4_args (list) – Additional arguments to pass to p4.
marshalled (bool, optional) – Whether to return the data in marshalled format. This will return a more computer-readable version.
*args (list) – Additional arguments to pass through to rbtools.utils.process.execute().
**kwargs (dict) – Additional keyword arguments to pass through to rbtools.utils.process.execute().

Returns:

If passing marshalled=True, then this will be a list of dictionaries containing results from the command.

In all other cases, this will return the result of RunProcessResult.

Return type:

object

Raises:

rbtools.clients.errors.SCMError – There was an error with the call to Perforce. Details are in the error message.

where(depot_path: str) → Sequence[Mapping[str, Any]][source]¶

Return the local path for a depot path.

Parameters:: depot_path (str) – A Perforce path to a file in the depot.
Returns:: A marshalled representation of the data showing where the file exists in the local client.
Return type:: list

class rbtools.clients.perforce.PerforceClient(p4_class=<class 'rbtools.clients.perforce.P4Wrapper'>, **kwargs)[source]¶

Bases: BaseSCMClient

A client for Perforce.

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

DATE_RE = re.compile(b'(\\w+)\\s+(\\w+)\\s+(\\d+)\\s+(\\d\\d:\\d\\d:\\d\\d)\\s+(\\d\\d\\d\\d)')[source]¶

ENCODED_COUNTER_URL_RE = re.compile('reviewboard.url\\.(\\S+)')[source]¶

REVISION_CURRENT_SYNC = '--rbtools-current-sync'[source]¶

REVISION_DEFAULT_CLN = 'default'[source]¶

REVISION_PENDING_CLN_PREFIX = '--rbtools-pending-cln:'[source]¶

__firstlineno__ = 788¶

__init__(p4_class=<class 'rbtools.clients.perforce.P4Wrapper'>, **kwargs)[source]¶

Initialize the client.

Parameters:

p4_class (type, optional) – The class type to use for the wrapper.
**kwargs (dict) – Keyword arguments to pass through to the superclass.

__static_attributes__ = ('_p4_info', 'p4', 'p4d_version')¶

amend_commit_description(message, revisions)[source]¶

Update a commit message to the given string.

Since local changelists on Perforce have no ordering with respect to each other, the revisions argument is mandatory.

Parameters:

message (unicode) – The commit message to use when amending the commit.
revisions (dict) – A dictionary of revisions, as returned by parse_revision_spec().

Raises:

rbtools.clients.errors.AmendError – The given changelist could not be amended.

can_amend_commit: bool = True[source]¶

Whether commits can be amended.

Type:: bool

can_get_file_content: bool = True[source]¶

Whether the tool can get files at specific revisions.

Added in version 5.0.

Type:: bool

check_dependencies() → None[source]¶

Check whether all base dependencies are available.

This checks for the presence of p4 in the system path.

Added in version 4.0.

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

diff(revisions: SCMClientRevisionSpec | None, *, include_files: Sequence[str] | None = None, exclude_patterns: Sequence[str] | None = None, extra_args: Sequence[str] | None = None, **kwargs) → SCMClientDiffResult[source]¶

Perform a diff using the given revisions.

This goes through the hard work of generating a diff on Perforce in order to take into account adds/deletes and to provide the necessary revision information.

Parameters:

revisions (dict) – A dictionary of revisions, as returned by parse_revision_spec().
include_files (list of unicode, optional) – A list of files to whitelist during the diff generation.
exclude_patterns (list of unicode, optional) – A list of shell-style glob patterns to blacklist during diff generation.
extra_args (list of str) – Additional arguments to be passed to the diff generation.
**kwargs (dict, unused) – Unused keyword arguments.

Returns:

A dictionary containing the following keys:

diff (bytes):: The contents of the diff to upload.
changenum (unicode):: The number of the changeset being posted (if revisions represents a single changeset).

Return type:

dict

get_changenum(revisions)[source]¶

Return the change number for the given revisions.

This is only used when the client is supposed to send a change number to the server (such as with Perforce).

Parameters:: revisions (dict) – A revisions dictionary as returned by parse_revision_spec.
Returns:: The change number to send to the Review Board server.
Return type:: unicode

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

Return the contents of a file at a given revision.

Added 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

Raises:

rbtools.clients.errors.SCMError – The file could not be found.

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

Return the size of a file at a given revision.

Added 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

Raises:

rbtools.client.errors.SCMError – An error occurred while attempting to get the file size.

get_local_path() → str | None[source]¶

Return the local path to the working tree.

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

get_raw_commit_message(revisions)[source]¶

Extract the commit message based on the provided revision range.

Since local changelists in Perforce are not ordered with respect to one another, this implementation looks at only the tip revision.

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

get_repository_info() → RepositoryInfo | None[source]¶

Return repository information for the current working tree.

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

get_repository_name()[source]¶

Return any repository name configured in the repository.

This is used as a fallback from the standard config options, for repository types that support configuring the name in repository metadata.

Returns:: The configured repository name, or None.
Return type:: unicode

name: str = 'Perforce'[source]¶

The name of the client.

Type:: str

normalize_exclude_patterns(patterns)[source]¶

Normalize the set of patterns so all non-depot paths are absolute.

A path with a leading // is interpreted as a depot pattern and remains unchanged. A path with a leading path separator is interpreted as being relative to the Perforce client root. All other paths are interpreted as being relative to the current working directory. Non-depot paths are transformed into absolute paths.

Parameters:: patterns (list of unicode) – A list of shell-style glob patterns to blacklist during diff generation.
Returns:: The normalized patterns.
Return type:: list of unicode

parse_revision_spec(revisions: Sequence[str] | None = None) → 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].

If zero revisions are passed in, this will return the current sync changelist as “tip”, and the upstream branch as “base”. The result may have special internal revisions or prefixes based on whether the changeset is submitted, pending, or shelved.

If a single revision is passed in, this will return the parent of that revision for “base” and the passed-in revision for “tip”.

If two revisions are passed in, they need to both be submitted changesets.

Parameters:

revisions (list of str, optional) – A list of revisions as specified by the user. Items in the list do not necessarily represent a single revision, since the user can use SCM-native syntaxes such as r1..r2 or r1:r2. SCMTool-specific overrides of this method are expected to deal with such syntaxes.

Returns:

The parsed revision spec.

See SCMClientRevisionSpec for the format of this dictionary.

This always populates the base and tip keys.

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.

patcher_cls[source]¶: alias of PerforcePatcher

requires_diff_tool: bool | Sequence[str] = True[source]¶

Whether this tool requires a command line diff tool.

This may be a boolean or a list.

If a boolean, then this must be False if no command line tool is required, or True if any command line tool supported by RBTools is available (in which case the SCMClient is responsible for ensuring compatibility).

If a list, then this must be a list of registered diff tool IDs that are compatible.

Added in version 4.0.

Type:: bool or list

scan_for_server(repository_info)[source]¶

Find if a Review Board server has been defined in the p4 counters.

This checks the Perforce counters to see if the Review Board server’s URL is specified. Since Perforce only started supporting non-numeric counter values in server version 2008.1, we support both a normal counter reviewboard.url with a string value and embedding the URL in a counter name like reviewboard.url.http:||reviewboard.example.com. Note that forward slashes aren’t allowed in counter names, so pipe (‘|’) characters should be used. These should be safe because they should not be used unencoded in URLs.

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

scmclient_id: str = 'perforce'[source]¶

The unique ID of the client.

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

Type:: str

server_tool_ids: ClassVar[Sequence[str] | None] = ['perforce'][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.

Added in version 5.0.1.

Type:: str

server_tool_names: ClassVar[str | None] = 'Perforce'[source]¶

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

Added in version 3.0.

Type:: str

supports_changesets: bool = True[source]¶

Whether the SCM uses server-side changesets

Added in version 3.0.

Type:: bool

supports_diff_exclude_patterns: bool = True[source]¶

Whether the SCM client supports excluding files from the diff.

Type:: bool

supports_diff_extra_args: bool = True[source]¶

Whether the SCM client’s diff method takes the extra_args parameter.

Type:: bool

supports_empty_files() → bool[source]¶

Return whether the Review Board server supports empty files.

Returns:: True if the Review Board server can support showing empty files. False if it cannot.
Return type:: bool

supports_patch_revert: bool = True[source]¶

Whether the SCM client supports reverting patches.

Type:: bool

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

Bases: SCMClientPatcher[PerforceClient]

A patcher that applies Perforce patches to a tree.

This applies patches using the standard patch command, but taking care to specially-handle added and deleted empty files.

Added in version 5.1.

ADDED_FILES_RE = re.compile(b'^==== //(\\S+)#\\d+ ==A== \\S+ ====$', re.MULTILINE)[source]¶

DELETED_FILES_RE = re.compile(b'^==== //(\\S+)#\\d+ ==D== \\S+ ====$', re.MULTILINE)[source]¶

__annotations_cache__ = {'_patched': 'bool', '_patching': 'bool', 'applied_patch_results': 'list[PatchResult]', 'can_commit': 'bool', 'can_patch_empty_files': 'bool', 'commit': 'bool', 'dest_path': 'Path', 'patches': 'Sequence[Patch]', 'repository_info': 'RepositoryInfo | None', 'revert': 'bool', 'run_commit_editor': 'bool', 'scmclient': 'TSCMClient', 'squash': 'bool'}¶

__firstlineno__ = 510¶

__static_attributes__ = ()¶

apply_binary_file(binary_file: BinaryFilePatch) → tuple[bool, str | None][source]¶

Apply a single binary file.

Added in version 6.0.

Parameters:

binary_file (rbtools.diffs.patches.BinaryFilePatch) – The binary file to apply.

Returns:

A 2-tuple of:

Tuple:

0 (bool) – Whether the operation was a success.
1 (str or None) – The error, if the operation failed.

Return type:

tuple

apply_patch_for_empty_files(patch: Patch) → bool[source]¶

Return whether any empty files in the patch are applied.

Parameters:: patch (rbtools.diffs.patches.Patch) – The opened patch to check and possibly apply.
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.

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

Apply a single patch.

This is an internal method that will take a single patch and apply it. It may be applied to files that already contain other modifications or have had other patches applied to it.

Added in version 6.0.

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

Raises:

rbtools.diffs.errors.ApplyPatchResult – There was an error attempting to apply the patch. This won’t be raised simply for conflicts or normal patch failures. It may be raised for errors encountered during the patching process.

handle_add_file(path: str, content: bytes) → None[source]¶

Add a file.

Added in version 6.0.

Parameters:

path (str) – The path to the file.
content (bytes) – The content for the file.

Raises:

OSError – A file operation failed.
Exception – An error occurred when running p4.

handle_move_file(old_path: str, new_path: str) → None[source]¶

Move a file.

Added in version 6.0.

Parameters:

old_path (str) – The old filename.
new_path (str) – The new filename.

Raises:

OSError – A file operation failed.
Exception – An error occurred when running p4.

handle_remove_file(path: str) → None[source]¶

Delete a file.

Added in version 6.0.

Parameters:: path (str) – The path to the file to delete.
Raises:: Exception – An error occurred when running p4.

handle_write_file(path: str, content: bytes) → None[source]¶

Write the content of a file.

Added in version 6.0.

Parameters:

path (str) – The path to the file.
content (bytes) – The content for the file.

Raises:

Exception – An error occurred when running p4.
OSError – A file operation failed.