NAME

P4Python - Python OO interface to the Perforce SCM System.

SYNOPSIS

  from p4 import P4

  p4 = P4()
  p4.port = "1666"
  p4.user = "fred"
  p4.client = "fred-ws"
  p4.connect()

  try:
      info = p4.run("info")
      p4.run("edit", "file.txt")
      p4.disconnect()
  except:
    for e in p4.errors:
        print e

DESCRIPTION

This module provides an OO interface to the Perforce SCM system that is designed to be intuitive to Python users. Data is returned in Python arrays and dictionaries (hashes) and input can also be supplied in these formats.

Each P4 object represents a connection to the Perforce Server, and multiple commands may be executed (serially) over a single connection (which of itself can result in substantially improved performance if executing lots of perforce commands).

BASE METHODS

p4.P4()
Construct a new P4 object. e.g. 
  p4 = p4.P4()

p4.connect()
Initializes the Perforce client and connects to the server. Returns false on failure and true on success.

 

p4.dropped()
Returns true if the TCP/IP connection between client and server has been dropped.

 

p4.errors
Returns an array containing the error messages received during execution of the last command.

 

p4.disconnect()
Terminate the connection and clean up. Should be called before exiting.

 

p4.client = string
Sets the name of your Perforce client. If you don't call this method, then the clientname will default according to the normal Perforce conventions. i.e. 
    1. Value from file specified by P4CONFIG
    2. Value from $ENV{P4CLIENT}
    3. Hostname
p4.client
Returns the setting of the current Perforce client name. This may have previously been set, or may be taken from the environment or P4CONFIG file if any. If all that fails, it will be your hostname.

 

p4.cwd = path
Sets the current working directory for the client. This should be called after the Connect() and before the Run().

p4.cwd
Returns the current working directory as your Perforce client sees it.

 

p4.host = string
Sets the name of the client host - overriding the actual hostname. This is equivalent to 'p4 -H <hostname>', and really only useful when you want to run commands as if you were on another machine. If you don't know when or why you might want to do that, then don't do it.

p4.host
Returns the client hostname. Defaults to your hostname, but can be overridden by setting it.
 

p4.password = string
Set the password for the Perforce user, overriding all defaults.
p4.password
Returns your Perforce password. When getting, it may extracted from the environment (P4PASSWD), or a P4CONFIG file.

 

p4.port = string
Set the port on which your Perforce server is listening in usual "<host>:<port>" syntax. Defaults to: 
    1. Value from file specified by P4CONFIG
    2. Value from $ENV{P4PORT}
    3. perforce:1666
p4.port
Property to get or set the port address for your Perforce server. When getting may be taken from a previous set call or from environment (P4PORT} or a P4CONFIG file.

 

p4.run(cmd, [arg, ...])
Run a Perforce command returning the results. Since Perforce commands can partially succeed and partially fail, you should check for errors using p4.errors.

Results are returned as an array of results.

Through the magic of the getattr(), you can also treat the Perforce commands as methods, so:

 p4.run_edit("filename.txt")

is equivalent to

 p4.run("edit", "filename.txt")

Note that the format of the array results you get depends on (a) whether you're using tagged (or form parsing) mode (b) the command you've executed (c) the arguments you supplied and (d) your Perforce server version.

In tagged or form parsing mode, ideally each result element will be a dictionary, but this is dependent on the command you ran and your server version.

In non-tagged mode (the default), the each result element will be a string. In this case, also note that as the Perforce server sometimes asks the client to write a blank line between result elements, some of these result elements can be empty.

Mostly you will want to use form parsing (and hence tagged) mode. See parse_forms().

Note that the return values of individual Perforce commands are not documented because they may vary between server releases.

If you want to be correlate the results returned by the P4 interface with those sent to the command line client try running your command with RPC tracing enabled. For example:

 Tagged mode:           p4 -Ztag -vrpc=1 describe -s 4321
 Non-Tagged mode:       p4 -vrpc=1 describe -s 4321

Pay attention to the calls to client-FstatInfo(), client-OutputText(), client-OutputData() and client-HandleError(). Each call to one of these functions results in either a result element, or an error element.
 

p4.user = string
Set your Perforce username. Defaults to: 
    1. Value from file specified by P4CONFIG
    2. Value from P4USER in environment
    3. OS username
p4.user
Returns your Perforce username.
p4.warnings
Returns the array of warnings from the last command 
 p4.warnings

SHORTCUT METHODS

The following methods are simply wrappers around the base methods designed to make common actions easy to code.

p4.tagged()
Equivalent to SetProtocol( "tag", "" ). Responses from commands that support tagged output will be in the form of a hash ref rather than plain text. Must be called prior to calling Connect().

p4.parse_forms()
Request that forms returned by commands such as p4.fetch_change(), or p4.run_client("-o") be parsed and returned as a hash reference for easy manipulation. Equivalent to calling SetProtocol( "tag", "" ) and SetProtocol( "specstring", "" ). Must be called prior to calling connect().

p4.fetch_<cmd>()
Shorthand for running pr.run("cmd", "-o") and returning the results. eg. 
    label      = p4.fetch_label(labelname)
    change     = p4.fetch_change(changeno)
    clientspec = p4.fetch_client(clientname)

p4.save_<cmd>()>
Shorthand for: 
    p4.set_input(spec)
    p4.run("cmd", "-i")
    
e.g.
    p4.save_label(label)
    p4.save_change(changeno)
    p4.save_client(clientspec)
    
    change = p4.fetch_change()
    change["Description"] = "some text...";
    p4.save_submit(change)
 
p4.input = string/dict
Save the supplied argument, which should be a dictionary or a string, as input to be supplied to a subsequent ``p4 XXXX -i''. 

 

COMPATIBILITY WITH PREVIOUS VERSIONS

This version of P4 is largely backwards compatible with previous versions with the following exceptions:

None.

LICENCE

Copyright (c) 2004-05, Vaccaperna Systems Ltd. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PERFORCE SOFTWARE, INC. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

AUTHOR

Robert Cowham, Vaccaperna Systems Ltd (robert at vaccaperna dot co dot uk)

Thanks to Tony Smith for the documentation for P4Perl on which this is based.

SEE ALSO

Perforce API documentation.