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.

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

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

__init__(options)[source]¶

Initialize the wrapper.

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

check_dependencies() → None[source]¶

Check whether all base dependencies are available.

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

New in version 4.0.

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

is_supported()[source]¶

Check whether the p4 command is usable.

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

counters()[source]¶

Return the Perforce counters.

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

change(changenum, marshalled=True)[source]¶

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

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

Modify a change description.

Parameters:: new_change_spec (unicode) – The new changeset description. This must contain the changelist number.

files(path)[source]¶

Return the opened files within the given path.

Parameters:: path (unicode) – 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

filelog(path)[source]¶

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

Parameters:: path (unicode) – 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

fstat(depot_path, fields=[])[source]¶

Run p4 fstat on a given depot path.

Parameters:

depot_path (unicode) – The file path to stat.
fields (list of unicode, 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

opened(changenum)[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, out_file=None)[source]¶

Print the contents of the given file.

Parameters:

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

Returns:

The output of the print operation.

Return type:

unicode

where(depot_path)[source]¶

Return the local path for a depot path.

Parameters:: depot_path (unicode) – 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

run_p4(p4_args, marshalled=False, ignore_errors=False, input_string=None, *args, **kwargs)[source]¶

Invoke p4.

In the current implementation, the arguments ‘marshalled’ and ‘input_string’ cannot be used together, i.e. this command doesn’t allow inputting and outputting at the same time.

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.
ignore_errors (bool, optional) – Whether to ignore return codes that typically indicate error conditions.
input_string (unicode, optional) – A string to pass to p4 on stdin.
*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.

If passing input_string, this will always return None.

In all other cases, this will return the result of execute(), depending on the arguments provided.

Return type:

object

Raises:

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

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

Bases: SCMClientPatcher

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.

New 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]¶

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.

__parameters__ = ()¶

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.

scmclient_id: str = 'perforce'[source]¶

The unique ID of the client.

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

Type:: str

name: str = 'Perforce'[source]¶

The name of the client.

Type:: str

server_tool_names: ClassVar[Optional[str]] = 'Perforce'[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]]] = ['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.

New in version 5.0.1.

Type:: str

patcher_cls[source]¶: alias of PerforcePatcher

requires_diff_tool: Union[bool, List[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.

New in version 4.0.

Type:: bool or list

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.

New in version 5.0.

Type:: bool

supports_changesets: bool = True[source]¶

Whether the SCM uses server-side changesets

New 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_patch_revert: bool = True[source]¶

Whether the SCM client supports reverting patches.

Type:: bool

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_PENDING_CLN_PREFIX = '--rbtools-pending-cln:'[source]¶

REVISION_DEFAULT_CLN = 'default'[source]¶

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

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

check_dependencies() → None[source]¶

Check whether all base dependencies are available.

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

New in version 4.0.

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

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

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

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

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.

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

diff(revisions: SCMClientRevisionSpec, *, include_files: List[str] = [], exclude_patterns: List[str] = [], extra_args: List[str] = [], **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, unused) – Additional arguments to be passed to the diff generation. Unused for git.
**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_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

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

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.

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

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.

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

Raises:

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