API Reference#

Commands#

pyforce.p4(
connection: Connection,
command: list[str],
stdin: Dict[str, str] | None = None,
max_severity: MessageSeverity = MessageSeverity.EMPTY,
) → list[Dict[str, str]]#

Run a p4 command and return its output.

This function uses marshal (using p4 -G) to load stdout and dump stdin.

Parameters:

  • connection – The connection to execute the command with.

  • command – A p4 command to execute, with arguments.

  • stdin – Write a dict to the standard input file using marshal.dump.

  • max_severity – Raises an exception if the output error severity is above that threshold.

Returns:

The command output.

Raises:
pyforce.login(connection: Connection, password: str) → None#

Login to Perforce Server.

Raises:

AuthenticationError – Failed to login.

pyforce.get_user(
connection: Connection,
user: str,
) → User#

Get user specification.

Command:

p4 user.

Parameters:

  • connection – Perforce connection.

  • user – Perforce username.

pyforce.get_client(
connection: Connection,
client: str,
) → Client#

Get client workspace specification.

Command:

p4 client.

Parameters:

  • connection – Perforce connection.

  • client – Perforce client name.

pyforce.get_change(
connection: Connection,
change: int,
) → Change#

Get changelist specification.

Command:

p4 change.

Parameters:

  • connection – Perforce connection.

  • change – The changelist number.

Raises:

ChangeUnknownError – change not found.

pyforce.get_revisions(
connection: Connection,
filespecs: list[str],
*,
long_output: bool = False,
) → Iterator[list[Revision]]#

List all revisions of files matching filespecs.

Command:

p4 filelog.

Parameters:

  • connection – Perforce Connection.

  • filespecs – A list of File specifications.

  • long_output – List long output, with full text of each changelist description.

Warning

The lists are not intentionally sorted despite being naturally sorted by descending revision (highest to lowset) due to how p4 filelog data are processed. This behavior could change in the future, the order is not guaranteed.

pyforce.create_changelist(
connection: Connection,
description: str,
) → ChangeInfo#

Create and return a new changelist.

Command:

p4 change.

Parameters:

  • connection – Perforce connection.

  • description – Changelist description.

pyforce.add(
connection: Connection,
filespecs: list[str],
*,
changelist: int | None = None,
preview: bool = False,
) → tuple[list[ActionMessage], list[ActionInfo]]#

Open filespecs in client workspace for addition to the depot.

Command:

p4 add.

Parameters:

  • connection – Perforce connection.

  • filespecs – A list of File specifications.

  • changelist – Open the files within the specified changelist. If not set, the files are linked to the default changelist.

  • preview – Preview which files would be opened for add, without actually changing any files or metadata.

Returns:

ActionInfo and ActionMessage objects. ActionInfo are only included if something unexpected happened during the operation.

pyforce.edit(
connection: Connection,
filespecs: list[str],
*,
changelist: int | None = None,
preview: bool = False,
) → tuple[list[ActionMessage], list[ActionInfo]]#

Open filespecs in client workspace for edit.

Command:

p4 edit.

Parameters:

  • connection – Perforce connection.

  • filespecs – A list of File specifications.

  • changelist – Open the files within the specified changelist. If not set, the files are linked to the default changelist.

  • preview – Preview the result of the operation, without actually changing any files or metadata.

Returns:

ActionInfo and ActionMessage objects. ActionInfo are only included if something unexpected happened during the operation.

pyforce.delete(
connection: Connection,
filespecs: list[str],
*,
changelist: int | None = None,
preview: bool = False,
) → tuple[list[ActionMessage], list[ActionInfo]]#

Open filespecs in client workspace for deletion from the depo.

Command:

p4 delete.

Parameters:

  • connection – Perforce connection.

  • filespecs – A list of File specifications.

  • changelist – Open the files within the specified changelist. If not set, the files are linked to the default changelist.

  • preview – Preview the result of the operation, without actually changing any files or metadata.

Returns:

ActionInfo and ActionMessage objects. ActionInfo are only included if something unexpected happened during the operation.

pyforce.sync(
connection: Connection,
filespecs: list[str],
) → list[Sync]#

Update filespecs to the client workspace.

Parameters:
pyforce.fstat(
connection: Connection,
filespecs: list[str],
*,
include_deleted: bool = False,
) → Iterator[FStat]#

List files information.

Local files (not in depot and not opened for add) are not included.

Command:

p4 fstat.

Parameters:

  • connection – Perforce connection.

  • filespecs – A list of File specifications.

  • include_deleted – Include files with a head action of delete or move/delete.

User#

pydantic model pyforce.User#

A Perforce user specification.

field access: PerforceDateTime (alias 'Access')#

The date and time this user last ran a Helix Server command.

field auth_method: AuthMethod (alias 'AuthMethod')#
field email: str (alias 'Email')#
field full_name: str (alias 'FullName')#
field name: str (alias 'User')#
field type: UserType (alias 'Type')#
field update: PerforceDateTime (alias 'Update')#

The date and time this user was last updated.

enum pyforce.UserType(value)#

Types of user enum.

Member Type:

str

Valid values are as follows:

STANDARD = <UserType.STANDARD: 'standard'>#
OPERATOR = <UserType.OPERATOR: 'operator'>#
SERVICE = <UserType.SERVICE: 'service'>#
enum pyforce.AuthMethod(value)#

User authentication enum.

Member Type:

str

Valid values are as follows:

PERFORCE = <AuthMethod.PERFORCE: 'perforce'>#
LDAP = <AuthMethod.LDAP: 'ldap'>#

Client#

pydantic model pyforce.Client#

A Perforce client workspace specification.

field access: PerforceDateTime (alias 'Access')#

The date and time that the workspace was last used in any way.

field description: str (alias 'Description')#
field host: str (alias 'Host')#

The name of the workstation on which this workspace resides.

field name: str (alias 'Client')#
field options: ClientOptions (alias 'Options')#
field owner: str (alias 'Owner')#

The name of the user who owns the workspace.

field root: pathlib.Path (alias 'Root')#

Workspace root directory on the local host

All the file in views are relative to this directory.

field stream: str | None (alias 'Stream')#
field submit_options: SubmitOptions (alias 'SubmitOptions')#
field type: ClientType (alias 'Type')#
field update: PerforceDateTime (alias 'Update')#

The date the workspace specification was last modified.

field views: List[View]#

Specifies the mappings between files in the depot and files in the workspace.

class pyforce.View#

A perforce View specification.

static from_string(string: str) → View#

New instance from a view string.

Example

>>> View.from_string("//depot/foo/... //ws/bar/...")
View(left='//depot/foo/...', right='//ws/bar/...')
left: str#

Alias for field number 0

right: str#

Alias for field number 1

class pyforce.ClientOptions#

A set of switches that control particular Client options.

__init__(
allwrite: bool,
clobber: bool,
compress: bool,
locked: bool,
modtime: bool,
rmdir: bool,
) → None#
classmethod from_string(string: str) → ClientOptions#

Instanciate class from an option line returned by p4.

enum pyforce.ClientType(value)#

Types of client workspace.

Member Type:

str

Valid values are as follows:

STANDARD = <ClientType.STANDARD: 'writeable'>#
OPERATOR = <ClientType.OPERATOR: 'readonly'>#
SERVICE = <ClientType.SERVICE: 'partitioned'>#
enum pyforce.SubmitOptions(value)#

Options to govern the default behavior of p4 submit.

Member Type:

str

Valid values are as follows:

SUBMIT_UNCHANGED = <SubmitOptions.SUBMIT_UNCHANGED: 'submitunchanged'>#
SUBMIT_UNCHANGED_AND_REOPEN = <SubmitOptions.SUBMIT_UNCHANGED_AND_REOPEN: 'submitunchanged+reopen'>#
REVERT_UNCHANGED = <SubmitOptions.REVERT_UNCHANGED: 'revertunchanged'>#
REVERT_UNCHANGED_AND_REOPEN = <SubmitOptions.REVERT_UNCHANGED_AND_REOPEN: 'revertunchanged+reopen'>#
LEAVE_UNCHANGED = <SubmitOptions.LEAVE_UNCHANGED: 'leaveunchanged'>#
LEAVE_UNCHANGED_AND_REOPEN = <SubmitOptions.LEAVE_UNCHANGED_AND_REOPEN: 'leaveunchanged+reopen'>#

Change#

pydantic model pyforce.Change#

A Perforce changelist specification.

Command:

p4 change

field change: int (alias 'Change')#
field client: str (alias 'Client')#
field date: PerforceDateTime (alias 'Date')#

Date the changelist was last modified.

field description: str (alias 'Description')#
field files: List[str]#

The list of files being submitted in this changelist.

field shelve_access: PerforceDateTime | None (alias 'shelveAccess')#
field shelve_update: PerforceDateTime | None (alias 'shelveUpdate')#
field status: ChangeStatus (alias 'Status')#
field type: ChangeType (alias 'Type')#
field user: str (alias 'User')#

Name of the change owner.

pydantic model pyforce.ChangeInfo#

A Perforce changelist.

Compared to a Change, this model does not contain the files in the changelist.

Command:

p4 changes

field change: int#
field client: str#
field date: PerforceTimestamp (alias 'time')#

Date the changelist was last modified.

field description: str (alias 'desc')#
field status: ChangeStatus#
field type: ChangeType (alias 'changeType')#
field user: str#

Name of the change owner.

enum pyforce.ChangeType(value)#

Types of changelist.

Member Type:

str

Valid values are as follows:

RESTRICTED = <ChangeType.RESTRICTED: 'restricted'>#
PUBLIC = <ChangeType.PUBLIC: 'public'>#
enum pyforce.ChangeStatus(value)#

Types of changelist status.

Member Type:

str

Valid values are as follows:

PENDING = <ChangeStatus.PENDING: 'pending'>#
SHELVED = <ChangeStatus.SHELVED: 'shelved'>#
SUBMITTED = <ChangeStatus.SUBMITTED: 'submitted'>#

Action#

pydantic model pyforce.ActionInfo#

The result of an action operation.

Actions can be, for example, add, edit or remove.

field action: str#
field client_file: str (alias 'clientFile')#
field depot_file: str (alias 'depotFile')#
field file_type: str (alias 'type')#
field work_rev: int (alias 'workRev')#

Open revision.

enum pyforce.Action(value)#

A file action.

Member Type:

str

Valid values are as follows:

ADD = <Action.ADD: 'add'>#
EDIT = <Action.EDIT: 'edit'>#
DELETE = <Action.DELETE: 'delete'>#
BRANCH = <Action.BRANCH: 'branch'>#
MOVE_ADD = <Action.MOVE_ADD: 'move/add'>#
MOVE_DELETE = <Action.MOVE_DELETE: 'move/delete'>#
INTEGRATE = <Action.INTEGRATE: 'integrate'>#
IMPORT = <Action.IMPORT: 'import'>#
PURGE = <Action.PURGE: 'purge'>#
ARCHIVE = <Action.ARCHIVE: 'archive'>#
class pyforce.ActionMessage#

Information on a file during an action operation.

Actions can be, for example, add, edit or remove.

Notable messages:

  • “can’t add (already opened for edit)”

  • “can’t add existing file”

  • “empty, assuming text.”

  • “also opened by user@client”

__init__(
path: str,
message: str,
level: MessageLevel,
) → None#
classmethod from_info_data(
data: Dict[str, str],
) → ActionMessage#

Create instance from an ‘info’ dict of an action command.

Revision#

pydantic model pyforce.Revision#

A file revision information.

field action: Action#

The operation the file was open for.

field change: int#

The number of the submitting changelist.

field client: str#
field depot_file: str (alias 'depotFile')#
field description: str (alias 'desc')#
field digest: str | None#

MD5 digest of the file. None if action is Action.DELETE.

field file_size: int | None#

File length in bytes. None if action is Action.DELETE.

field file_type: str (alias 'type')#
field revision: int (alias 'rev')#
field time: PerforceTimestamp#
field user: str#

The name of the user who submitted the revision.

Sync#

pydantic model pyforce.Sync#

The result of a file sync operation.

field action: str#
field client_file: str (alias 'clientFile')#
field depot_file: str (alias 'depotFile')#
field file_size: int (alias 'fileSize')#
field revision: int (alias 'rev')#

FStat#

pydantic model pyforce.FStat#

A file information.

field client_file: str (alias 'clientFile')#
field depot_file: str (alias 'depotFile')#
field have_rev: int | None (alias 'haveRev')#

Revision last synced to workspace, if on workspace.

field head: HeadInfo | None#
field is_mapped: bool (alias 'isMapped')#

Is the file is mapped to client workspace.

field others_open: List[OtherOpen] | None#
pydantic model pyforce.HeadInfo#

Head revision information.

field action: Action (alias 'headAction')#
field change: int (alias 'headChange')#
field file_type: str (alias 'headType')#
field mod_time: PerforceTimestamp (alias 'headModTime')#

Revision modification time.

The time that the file was last modified on the client before submit.

field revision: int (alias 'headRev')#

Revision number.

If you used a Revision specifier in your query, this field is set to the specified value. Otherwise, it’s the head revision.

field time: PerforceTimestamp (alias 'headTime')#

Revision changelist time.

class pyforce.OtherOpen#

Other Open information.

__init__(
action: Action,
change: int | Literal['default'],
user: str,
client: str,
) → None#

Exceptions#

exception pyforce.AuthenticationError#

Raised when login to the Helix Core Server failed.

__init__(*args, **kwargs)#
exception pyforce.ConnectionExpiredError#

Raised when the connection to the Helix Core Server has expired.

You need to log back in.

__init__(*args, **kwargs)#
exception pyforce.CommandExecutionError#

Raised when an error occured during the execution of a p4 command.

Parameters:

  • message – Error message.

  • command – The executed command.

  • data – Optional marshalled output returned by the command.

__init__(
message: str,
command: list[str],
data: dict[str, str] | None = None,
) → None#
exception pyforce.ChangeUnknownError#

Raised when a changelist is request but doesn’t exists.

__init__(*args, **kwargs)#

Other#

class pyforce.Connection#

Perforce connection informations.

client: str | None#

Client workspace name (P4CLIENT).

port: str#

Perforce host and port (P4PORT).

user: str | None#

Helix server username (P4USER).

enum pyforce.MessageSeverity(value)#

Perforce message severity levels.

Member Type:

int

Valid values are as follows:

EMPTY = <MessageSeverity.EMPTY: 0>#
INFO = <MessageSeverity.INFO: 1>#
WARNING = <MessageSeverity.WARNING: 2>#
FAILED = <MessageSeverity.FAILED: 3>#
FATAL = <MessageSeverity.FATAL: 4>#
enum pyforce.MarshalCode(value)#

Values of the code field from a marshaled P4 response.

The output dictionary from p4 -G must have a code field.

Member Type:

str

Valid values are as follows:

STAT = <MarshalCode.STAT: 'stat'>#
ERROR = <MarshalCode.ERROR: 'error'>#
INFO = <MarshalCode.INFO: 'info'>#
enum pyforce.MessageLevel(value)#

Perforce generic ‘level’ codes, as described in P4.Message.

Member Type:

int

Valid values are as follows:

NONE = <MessageLevel.NONE: 0>#
USAGE = <MessageLevel.USAGE: 1>#
UNKNOWN = <MessageLevel.UNKNOWN: 2>#
CONTEXT = <MessageLevel.CONTEXT: 3>#
ILLEGAL = <MessageLevel.ILLEGAL: 4>#
NOTYET = <MessageLevel.NOTYET: 5>#
PROTECT = <MessageLevel.PROTECT: 6>#
EMPTY = <MessageLevel.EMPTY: 17>#
FAULT = <MessageLevel.FAULT: 33>#
CLIENT = <MessageLevel.CLIENT: 34>#
ADMIN = <MessageLevel.ADMIN: 35>#
CONFIG = <MessageLevel.CONFIG: 36>#
UPGRADE = <MessageLevel.UPGRADE: 37>#
COMM = <MessageLevel.COMM: 38>#
TOOBIG = <MessageLevel.TOOBIG: 39>#
class pyforce.utils.PerforceDateTime#

Alias of datetime.datetime

class pyforce.utils.PerforceTimestamp#

Alias of datetime.datetime