rbtools.clients.perforce¶
A client for Perforce.
Classes
|
A wrapper around p4 commands. |
|
A client for Perforce. |
- 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.
- __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:
- counters()[source]¶
Return the Perforce counters.
- Returns:
The parsed Perforce counters.
- Return type:
- 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.
- info()[source]¶
Run p4 info and return the results.
- Returns:
The parsed output from p4 info.
- Return type:
- 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 torbtools.utils.process.execute()
.**kwargs (
dict
) – Additional keyword arguments to pass through torbtools.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 returnNone
.In all other cases, this will return the result of
execute()
, depending on the arguments provided.- Return type:
- Raises:
rbtools.clients.errors.SCMError – There was an error with the call to Perforce. Details are in the error message.
- 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:
- server_tool_names: Optional[str] = 'Perforce'[source]¶
A comma-separated list of SCMClient names on the server
New in version 3.0.
- Type:
- 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, orTrue
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.
- can_get_file_content: bool = True[source]¶
Whether the tool can get files at specific revisions.
New in version 5.0.
- Type:
- supports_changesets: bool = True[source]¶
Whether the SCM uses server-side changesets
New in version 3.0.
- Type:
- supports_diff_exclude_patterns: bool = True[source]¶
Whether the SCM client supports excluding files from the diff.
- Type:
- supports_diff_extra_args: bool = True[source]¶
Whether the SCM client’s diff method takes the
extra_args
parameter.- Type:
- supports_patch_revert: bool = True[source]¶
Whether the SCM client supports reverting patches.
- Type:
- DATE_RE = re.compile(b'(\\w+)\\s+(\\w+)\\s+(\\d+)\\s+(\\d\\d:\\d\\d:\\d\\d)\\s+(\\d\\d\\d\\d)')[source]¶
- __init__(p4_class=<class 'rbtools.clients.perforce.P4Wrapper'>, **kwargs)[source]¶
Initialize the client.
- 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:
- get_repository_info() Optional[RepositoryInfo] [source]¶
Return repository information for the current working tree.
- Returns:
The repository info structure.
- Return type:
- 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:
- 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
ofstr
, 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 asr1..r2
orr1: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
andtip
keys.- Return type:
- 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 likereviewboard.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:
- 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 byparse_revision_spec()
.include_files (
list
ofunicode
, optional) – A list of files to whitelist during the diff generation.exclude_patterns (
list
ofunicode
, 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:
- 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).
- 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.
- apply_patch_for_empty_files(patch, p_num, revert=False)[source]¶
Return whether any empty files in the patch are applied.
- Parameters:
- 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.
- 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.
- 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 byparse_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:
- Returns:
The read file.
- Return type:
- Raises:
rbtools.clients.errors.SCMError – The file could not be found.