NAME

P4Python - Python OO interface to the Perforce SCM System.

SYNOPSIS

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

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

EXAMPLES

Don't forget to also look at the test harness which demonstrates lots of commands being run the output being parsed and checked.

Update a Client Workspace

Create and update a client workspace from a template.

  import p4

  template = "my-client-template"
  client_root = r"c:\work\my-root"

  p4c = p4.P4()
  p4c.parse_forms()	# This call is important to make handling specs objects like clients easier

  try:
      p4c.connect()
      # Run a "p4 client -t template -o" and convert it into a Python dictionary
      spec = p4c.fetch_client("-t", template)
      spec["Root"] = client_root
      p4c.save_client(spec)
      p4c.run_sync()

  except p4.P4Error:
    # If any errors occur, we'll jump in here. Just log them
    # and raise the exception up to the higher level
    for e in p4.errors:
        print e

Submit a Changelist

We create a changelist using the "p4 change -o" command, modify it and then do the submission ("p4 submit -i"). Error handling left to default exceptions being raised:

  import p4

  p4c = p4.P4()
  p4c.parse_forms()	# This call is important to make handling specs objects like clients easier
  p4c.connect()

  change = p4c.fetch_change()
  # Let us assume that files were opened elsewhere and we only want to submit a subset that we
  # already know about
  myfiles = ['//depot/some/path/file1.c', '//depot/some/path/file1.h']
  change["Description"] = "My changelist\nSubmitted from P4Python\n"
  change["Files"] = myfiles	# This attribute takes a python list

  result = p4c.save_submit(change)
  # May do some parsing of result to ensure it all worked although by default an exception
  # will be raised on an error.

Login Before Doing Other Stuff

May need to login to Perforce first:

  import p4

  p4c = p4.P4()
  p4c.user = "Robert"
  p4c.connect()
  p4c.login("Mypassword")

  opened = p4c.run_opened()

  etc...

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. 
  myp4 = p4.P4()

p4.P4Error
An Exception class raised if errors occur. Contents set to p4.errors/warnings arrays (see exception_level).
 
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.exception_level=
Set to 0 to raise no exceptions on errors - means you need to check p4.errors array.
Set to 1 (default) to raise an exception on errors but not on warnings
Set to 2 to raise an exception on errors or warnings (note warnings include things like sync and All Files up to date)
 
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.input = string/dict
Save the supplied argument, which should be a dictionary or a string, as input to be supplied to a subsequent ``p4 <cmd> -i''. Also applies to commands expecting input such as "login" and "passwd". See Shortcut methods for conveniences.
 
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.translate(output, content, fnames, dialog)
Set translation options for internationalised servers - values defined as P4 class constants (NOCONV, UTF_8, WIN_US_ANSI etc). You must call this function to avoid the error message: "Unicode server permits only unicode enabled clients."
Needs to be called before connect().
Note you can supply just the one parameter and the others will default to it. You may wish to set content=NOCONV and the others to an appropriate value to avoid translation of file contents, e.g.
    p4.translate(P4.NOCONV)
p4.user = string
Set your Perforce username. If not set, 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 first item from results array. eg. 
    label      = myp4.fetch_label(labelname)
    change     = myp4.fetch_change(changeno)
    clientspec = myp4.fetch_client(clientname)
are equivalent to:
    label      = myp4.run("label", "-o", labelname)[0]
    change     = myp4.run("change", "-o", changeno)[0]
    clientspec = myp4.run("client", "-o", clientname)[0]

p4.login(<password>)
Shorthand, the following are equivalent: 
    myp4.login("mypassword")
and 
    myp4.input = "password"
    myp4.run("login")
p4.passwd(<new-password>)
Shorthand, the following are equivalent: 
    myp4.passwd("mynewpassword")
and 
    myp4.input = "mynewpassword"
    myp4.run("passwd")
p4.save_<cmd>()>
Shorthand for: 
    myp4.input = spec
    myp4.run("cmd", "-i")
    
e.g.
    myp4.save_label(label)
    myp4.save_change(changeno)
    myp4.save_client(clientspec)
    
    change = myp4.fetch_change()
    change["Description"] = "some text...";
    myp4.save_submit(change)
 
 

COMPATIBILITY WITH PREVIOUS VERSIONS

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

In 0.6 a new P4Error exception class has been introduced. This exception will be thrown instead of P4Client.error (which should now never be thrown).

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.