Helix Core P4Python Developer Guide (2020.1)

P4Python Classes

The P4 module consists of several public classes:

The following tables provide more details about each public class, including methods and attributes. Attributes are readable and writable unless indicated otherwise. They can be strings, objects, or integers.

You can set attributes in the P4() constructor or by using their setters and getters. For example:

import P4
p4 = P4.P4(client="myclient", port="1666")
p4.user = 'me'

P4

Helix server client class. Handles connection and interaction with the Helix server. There is one instance of each connection.

The following table lists attributes of the class P4 in P4Python.

Attribute Description

api_level

API compatibility level. (Lock server output to a specified server level.)

charset

Charset for Unicode servers.

client

P4CLIENT, the name of the client workspace to use.

cwd

Current working directory.

disable_tmp_cleanup

Disable cleanup of temporary objects.

encoding

Encoding to use when receiving strings from a non-Unicode server. If unset, use UTF8. Can be set to a legal Python encoding, or to raw to receive Python bytes instead of Unicode strings. Requires Python 3.

errors

An array containing the error messages received during execution of the last command.

exception_level

The exception level of the P4 instance. Values can be:

  • 0 : no exceptions are raised.
  • 1 : only errors are raised as exceptions.
  • 2 : warnings are also raised as exceptions.

The default value is 2.

handler

An output handler.

host

P4HOST, the name of the host used.

ignore_file

The path of the ignore file, P4IGNORE.

input

Input for the next command. Can be a string, a list or a dictionary.

maxlocktime

MaxLockTime used for all following commands

maxresults

MaxResults used for all following commands. This command must be set before the connection is made. If the command is set after the connection is made, the command is ignored.

maxscanrows

MaxScanRows used for all following commands.

messages

An array of P4.Message objects, one for each message sent by the server.

p4config_file

The location of the configuration file used (P4CONFIG). This attribute is read-only.

password

P4PASSWD, the password used.

port

P4PORT, the port used for the connection.

prog

The name of the script.

progress

A progress indicator.

server_case_insensitive

Detect whether or not the server is case sensitive.

server_level

Returns the current Helix server level.

server_unicode

Detect whether or not the server is in Unicode mode.

streams

To disable streams support, set the value to 0 or False. By default, streams output is enabled for servers at 2011.1 or higher.

tagged

To disable tagged output for the following commands, set the value to 0 or False. By default, tagged output is enabled.

track

To enable performance tracking for the current connection, set the value to 1 or True. By default, server tracking is disabled.

track_output

If performance tracking is enabled, returns an array containing performance tracking information received during execution of the last command.

ticket_file

P4TICKETS, the ticket file location used.

user

P4USER, the user under which the connection is run.

version

The version of the script.

warnings

An array containing the warning messages received during execution of the last command.

The following table lists all public methods of the class P4. Many methods are wrappers around P4.run(), which sends a command to Helix server. Such methods are provided for your convenience.

Method Description

at_exception_level()

In the context of a with statement, temporarily set the exception level for the duration of a block.

clone()

Clones from another Perforce service into a local Perforce service, and returns a new P4 object.

connect()

Connects to the Helix server.

connected()

Returns True if connected and the connection is alive, otherwise False.

delete_<spectype>()

Deletes the spec <spectype>. Equivalent to:

P4.run( "<spectype>", "-d" )

disconnect()

Disconnects from the Helix server.

env()

Get the value of a Helix server environment variable, taking into account P4CONFIG files and (on Windows or OS X) the registry or user preferences.

fetch_<spectype>()

Fetches the spec <spectype>. Equivalent to:

p4.run( "<spectype>", "-o" ).pop( 0 )

format_<spectype>()

Converts the spec <spectype> into a string.

identify()

Returns a string identifying the P4Python module.

init()

Initializes a new personal (local) Helix server, and returns a new P4 object.

is_ignored()

Determines whether a particular file is ignored via the P4IGNORE feature.

iterate_<spectype>()

Iterate through specs of form <spectype>.

P4()

Returns a new P4 object.

parse_<spectype>()

Parses a string representation of the spec <spectype> and returns a dictionary.

run()

Runs a command on the server. Needs to be connected, or an exception is raised.

run_cmd()

Runs the command cmd. Equivalent to:

P4.run( "command" )

run_filelog()

This command returns a list of P4.DepotFile objects. Specialization for the P4.run() method.

run_login()

Logs in using the specified password or ticket.

run_password()

Convenience method: updates the password. Takes two arguments: oldpassword, newpassword

run_resolve()

Interface to p4 resolve.

run_submit()

Convenience method for submitting changelists. When invoked with a change spec, it submits the spec. Equivalent to:

p4.input = myspecp4.run( "submit", "-i" )

run_tickets()

Interface to p4 tickets.

save_<spectype>()

Saves the spec <spectype>. Equivalent to:

P4.run( "<spectype>", "-i" )

set_env()

On Windows or OS X, set a variable in the registry or user preferences.

temp_client()

Creates a temporary client.

while_tagged()

In the context of a with statement, temporarily toggle tagged behavior for the duration of a block.

P4.P4Exception

Exception class. Instances of this class are raised when errors and/or (depending on the exception_level setting) warnings are returned by the server. The exception contains the errors in the form of a string. P4Exception is a subclass of the standard Python Exception class.

P4.DepotFile

Container class returned by P4.run_filelog(). Contains the name of the depot file and a list of P4.Revision objects.

Attribute Description

depotFile

Name of the depot file.

revisions

List of P4.Revision objects

P4.Revision

Container class containing one revision of a P4.DepotFile object.

Attribute Description

action

Action that created the revision.

change

Changelist number

client

Client workspace used to create this revision.

desc

Short change list description.

depotFile

The name of the file in the depot.

digest

MD5 digest of the revision.

fileSize

File size of this revision.

integrations

List of P4.Integration objects.

rev

Revision.

time

Timestamp (as datetime.datetime object)

type

File type.

user

User that created this revision.

P4.Integration

Container class containing one integration for a P4.Revision object.

Attribute Description

how

Integration method (merge/branch/copy/ignored).

file

Integrated file.

srev

Start revision.

erev

End revision.

P4.Map

A class that allows users to create and work with Helix server mappings without requiring a connection to the Helix server.

Method Description

P4.Map()

Construct a new Map object (class method).

join()

Joins two maps to create a third (class method).

clear()

Empties a map.

count()

Returns the number of entries in a map.

is_empty()

Tests whether or not a map object is empty.

insert()

Inserts an entry into the map.

translate()

Translate a string through a map.

includes()

Tests whether a path is mapped.

reverse()

Returns a new mapping with the left and right sides reversed.

lhs()

Returns the left side as an array.

rhs()

Returns the right side as an array.

as_array()

Returns the map as an array

P4.MergeData

Class encapsulating the context of an individual merge during execution of a p4 resolve command. Passed to P4.run_resolve().

Attribute Description

your_name

Returns the name of "your" file in the merge. (file in workspace)

their_name

Returns the name of "their" file in the merge. (file in the depot)

base_name

Returns the name of "base" file in the merge. (file in the depot)

your_path

Returns the path of "your" file in the merge. (file in workspace)

their_path

Returns the path of "their" file in the merge. (temporary file on workstation into which their_name has been loaded)

base_path

Returns the path of the base file in the merge. (temporary file on workstation into which base_name has been loaded)

result_path

Returns the path to the merge result. (temporary file on workstation into which the automatic merge performed by the server has been loaded)

merge_hint

Returns hint from server as to how user might best resolve merge.

The P4.MergeData class also has one method:

run_merge()

If the environment variable P4MERGE is defined, run it and return a boolean based on the return value of that program.

P4.Message

Class for handling error messages in Helix server.

Method Description

severity

Returns the severity of the message.

generic

Returns the generic class of the error.

msgid

Returns the unique ID of the error message.

P4.OutputHandler

Handler class that provides access to streaming output from the server; set P4.handler to an instance of a subclass of P4.OutputHandler to enable callbacks:

Method Description

outputBinary

Process binary data.

outputInfo

Process tabular data.

outputMessage

Process information or errors.

outputStat

Process tagged output.

outputText

Process text data.

P4.Progress

Handler class that provides access to progress indicators from the server; set P4.progress to an instance of a subclass of P4.Progress to enable callbacks:

Method Description

init()

Initialize progress indicator as designated type.

setTotal()

Total number of units (if known).

setDescription()

Description and type of units to be used for progress reporting.

update()

If non-zero, user has requested a cancellation of the operation.

done()

If non-zero, operation has failed.

P4.Resolver

Class for handling resolves in Helix server.

Method Description

resolve()

Perform a resolve and return the resolve decision as a string.

P4.Spec

Class allowing access to the fields in a Helix server specification form.

Attribute Description

_fieldname

Value associated with the field named fieldname.

comments

Array containing comments in a spec object.

permitted_fields

Array containing the names of the fields that are valid for this spec object.