<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>P4Python - Python interface to the Perforce SCM System.</title>
<link rev="made" href="mailto:rc@vaccaperna.co.uk" />
</head>
<body style="background-color: white">
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#examples">EXAMPLES</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#base_methods">BASE METHODS</a></li>
<li><a href="#shortcut_methods">SHORTCUT METHODS</a></li>
<li><a href="#compatibility_with_previous_versions">COMPATIBILITY WITH PREVIOUS VERSIONS</a></li>
<li><a href="#licence">LICENCE</a></li>
<li><a href="#author">AUTHOR</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>P4Python - Python OO interface to the Perforce SCM System.</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<PRE> import p4</PRE>
<PRE> 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 p4.P4Error:
for e in p4c.errors:
print e
</PRE>
<hr />
<h1><a name="examples">EXAMPLES</a></h1>
<p>Don't forget to also look at the <a href="test/test_p4python.py">test harness</a>
which demonstrates lots of commands being run the output being parsed and
checked.</p>
<h2>Update a Client Workspace</h2>
<p>Create and update a client workspace from a template.</p>
<PRE> 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</PRE>
<h2>Submit a Changelist</h2>
<p>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:</p>
<PRE> 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.</PRE>
<h2>Login Before Doing Other Stuff</h2>
<p>May need to login to Perforce first:</p>
<PRE> import p4
p4c = p4.P4()
p4c.user = "Robert"
p4c.connect()
p4c.login("Mypassword")
opened = p4c.run_opened()
etc...</PRE>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>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.</p>
<p>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).</p>
<p>
</p>
<hr />
<h1><a name="base_methods">BASE METHODS</a></h1>
<dl>
<dt><strong><a name="item_new">p4.P4()</a></strong><br />
</dt>
<dd>
Construct a new P4 object. e.g.
</dd>
<dd>
<pre>
myp4 = p4.P4()</pre>
</dd>
<p></p>
<dt><strong><a name="item_P4Errors">p4.P4Error</a></strong><br />
</dt>
<dd>
An Exception class raised if errors occur. Contents set to p4.errors/warnings arrays (see
<a href="#item_exception_level">exception_level</a>).<br>
<dt><strong><a name="item_connect">p4.connect()</a></strong><br />
</dt>
<dd>
Initializes the Perforce client and connects to the server.
Returns false on failure and true on success.
</dd>
<br>
<p></p>
<dt><strong><a name="item_dropped">p4.dropped()</a></strong><br />
</dt>
<dd>
Returns true if the TCP/IP connection between client and server has
been dropped.
</dd>
<br>
<p></p>
<dt><strong><a name="item_errors">p4.errors</a></strong><br />
</dt>
<dd>
Returns an array containing the error messages received during
execution of the last command.
</dd>
<br>
<p></p>
<dt><strong><a name="item_disconnect">p4.disconnect()</a></strong><br />
</dt>
<dd>
Terminate the connection and clean up. Should be called before exiting.
</dd>
<br>
<p></p>
<dt><strong><a name="item_setclient">p4.client =</a> string</strong><br />
</dt>
<dd>
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.
</dd>
<dd>
<pre>
1. Value from file specified by P4CONFIG
2. Value from $ENV{P4CLIENT}
3. Hostname</pre>
<dt><strong><a name="item_getclient">p4.client</a></strong><br />
</dt>
<dd>
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.
</dd>
<br>
<p></p>
<dt><strong><a name="item_setcwd">p4.cwd = path</a></strong><br />
</dt>
<dd>
Sets the current working directory for the client. This should be called after
the <a href="#item_connect"><code>Connect()</code></a> and before the Run().
</dd>
<p></p>
<dt><strong><a name="item_getcwd">p4.cwd</a></strong><br />
</dt>
<dd>
Returns the current working directory as your Perforce client sees
it.
</dd>
<br>
<p></p>
<dt><strong><a name="item_exception_level">p4.exception_level</a>=</strong><br />
</dt>
<dd>
Set to 0 to raise no exceptions on errors - means you need to check p4.errors
array.<dd>
Set to 1 (default) to raise an exception on errors but not on warnings<dd>
Set to 2 to raise an exception on errors or warnings (note warnings include
things like sync and All Files up to date)<br>
<dt><strong><a name="item_sethost">p4.host = string</a></strong><br />
</dt>
<dd>
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.
</dd>
<p></p>
<dt><strong><a name="item_gethost">p4.host</a></strong><br />
</dt>
<dd>
Returns the client hostname. Defaults to your hostname, but can be overridden by
setting it.<br>
<p></p>
<dt><strong><a name="item_setinput">p4.input = string/dict</a></strong><br />
</dt>
<dd>
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 <a href="#shortcut_methods">Shortcut methods</a> for
conveniences.</dd>
<dt> </dt>
<dt><strong><a name="item_setpassword">p4.password = string</a></strong><br />
</dt>
<dd>
Set the password for the Perforce user, overriding all defaults.
</dd>
<dt><strong><a name="item_getpassword">p4.password</a></strong><br />
</dt>
<dd>
Returns your Perforce password. When getting, it may extracted from the environment (P4PASSWD),
or a P4CONFIG file.
</dd>
<br>
<p></p>
<dt><strong><a name="item_setport">p4.port = string</a></strong><br />
</dt>
<dd>
Set the port on which your Perforce server is listening in usual "<host>:<port>"
syntax. Defaults
to:
</dd>
<dd>
<pre>
1. Value from file specified by P4CONFIG
2. Value from $ENV{P4PORT}
3. perforce:1666</pre>
<dt><strong><a name="item_getport">p4.port</a></strong><br />
</dt>
<dd>
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.
</dd>
<br>
<p></p>
<dd>
<p></p>
<dt><strong><a name="item_run">p4.run(cmd, [arg, ...])</a></strong><br />
</dt>
<dd>
Run a Perforce command returning the results. Since Perforce commands
can partially succeed and partially fail, you should check for errors
using <a href="#item_errorcount"><code>p4.errors</code></a>.
</dd>
<dd>
<p>Results are returned as an array of results.</p>
</dd>
<dd>
<p>Through the magic of the getattr(), you can also treat the
Perforce commands as methods, so:</p>
</dd>
<dd>
<pre>
p4.run_edit("filename.txt")</pre>
</dd>
<dd>
<p>is equivalent to</p>
</dd>
<dd>
<pre>
p4.run("edit", "filename.txt")</pre>
</dd>
<dd>
<p>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.</p>
</dd>
<dd>
<p>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.</p>
</dd>
<dd>
<p>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.</p>
</dd>
<dd>
<p>Mostly you will want to use form parsing (and hence tagged) mode. See
parse_forms().</p>
</dd>
<dd>
<p>Note that the return values of individual Perforce commands are not
documented because they may vary between server releases.</p>
</dd>
<dd>
<p>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:</p>
</dd>
<dd>
<pre>
Tagged mode: p4 -Ztag -vrpc=1 describe -s 4321
Non-Tagged mode: p4 -vrpc=1 describe -s 4321</pre>
</dd>
<dd>
<p>Pay attention to the calls to client-FstatInfo(), client-OutputText(),
client-OutputData() and client-HandleError(). <em>Each call to one of these
functions results in either a result element, or an error element.<br>
</em></p>
</dd>
<p></p>
<dd>
<p></p>
<dd>
</dd>
<p></p>
<dd>
<p></p>
<dd>
<p></p>
<dd>
<p></p>
<dt><strong><a name="item_translate">p4.translate(</a>output, content,
fnames, dialog)</strong><br />
</dt>
<dd>
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."</dd>
<dd>
Needs to be called before connect().</dd>
<dd>
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.<pre> p4.translate(P4.NOCONV)</pre>
</dd>
<dt><strong><a name="item_setuser">p4.user = string</a></strong><br />
</dt>
<dd>
Set your Perforce username. If not set, defaults to:
</dd>
<dd>
<pre>
1. Value from file specified by P4CONFIG
2. Value from P4USER in environment
3. OS username</pre>
<dt><strong><a name="item_getuser">p4.user</a></strong><br />
</dt>
<dd>
Returns your Perforce username.</dd>
<dt> </dt>
<dd>
</dd>
<dt><strong><a name="item_warnings">p4.warnings</a></strong><br />
</dt>
<dd>
Returns the array of warnings from the last command
</dd>
<dd>
<pre>
p4.warnings</pre>
<dt><strong><a name="item_api">p4.api(string)</level></a></strong><br />
</dt>
<dd>Specify the API compatibility level to use for this script. This is useful
when you want your script to continue to work on newer server versions (yet to
come out!), even if the new server adds tagged output or similar changes to
previously unsupported commands. The additional tagged output support can
change the server's output, and cause your scripts to break. Setting the API
level to a specific value allows you to lock the output to an older format, thus
increasing the compatibility of your script.</dd>
<dd>Must be called before calling connect(). e.g.</dd>
<dd>
<pre> p4c.api("57") # Lock to 2005.1 format
p4c.connect()
etc.</pre>
</dd>
<dd>
</dd>
<p></p></dl>
<p>
</p>
<hr />
<h1><a name="shortcut_methods">SHORTCUT METHODS</a></h1>
<p>The following methods are simply wrappers around the base methods
designed to make common actions easy to code.</p>
<dl>
<dt><strong><a name="item_tag">p4.tagged()</a></strong><br />
</dt>
<dd>
Equivalent to <a href="#item_setprotocol"><code>SetProtocol( "tag", "" )</code></a>. 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 <a href="#item_connect"><code>Connect()</code></a>.
</dd>
<p></p>
<dt><strong><a name="item_parseforms">p4.parse_forms()</a></strong><br />
</dt>
<dd>
Request that forms returned by commands such as <code>p4.fetch_change()</code>, or
<code>p4.run_client("-o")</code> be parsed and returned as a hash reference for easy
manipulation. Equivalent to calling <a href="#item_setprotocol"><code>SetProtocol( "tag", "" )</code></a> and
<a href="#item_setprotocol"><code>SetProtocol( "specstring", "" )</code></a>. Must be called prior to calling
<code><a href="#item_connect">c</a></code><a href="#item_connect"><code>onnect()</code></a>.
</dd>
<p> </p>
<p></p>
<dt><strong><a name="item_fetch">p4.fetch_<cmd>()</a></strong><br />
</dt>
<dd>
Shorthand for running <a href="#item_run"><code>pr.run("cmd", "-o")</code></a> and returning
the first item from results array. eg.
</dd>
<dd>
<pre>
label = myp4.fetch_label(labelname)
change = myp4.fetch_change(changeno)
clientspec = myp4.fetch_client(clientname)</pre>
are equivalent to:<pre>
label = myp4.run("label", "-o", labelname)[0]
change = myp4.run("change", "-o", changeno)[0]
clientspec = myp4.run("client", "-o", clientname)[0]</pre>
<p></p>
<dt><strong><a name="item_login">p4.login(</a><a name="item_passwd0"><password></a><a name="item_login">)</a></strong><br />
</dt>
<dd>
Shorthand, the following are equivalent:
</dd>
<dd>
<pre>
myp4.login("mypassword")</pre>
</dd>
<dd>
and
<pre>
myp4.input = "password"
myp4.run("login")
</pre>
</dd>
<dt><strong><a name="item_passwd">p4.passwd(<new-password>)</a></strong><br />
</dt>
<dd>
Shorthand, the following are equivalent:
</dd>
<dd>
<pre>
myp4.passwd("mynewpassword")</pre>
</dd>
<dd>
and
<pre>
myp4.input = "mynewpassword"
myp4.run("passwd")
</pre>
</dd>
<dt><strong><a name="item_save_cmd">p4.save_<cmd>()></a></strong><br />
</dt>
<dd>
Shorthand for:
</dd>
<dd>
<pre>
myp4.input = spec
myp4.run("cmd", "-i")
e.g.</pre>
</dd>
<dd>
<pre>
myp4.save_label(label)
myp4.save_change(changeno)
myp4.save_client(clientspec)
change = myp4.fetch_change()
change["Description"] = "some text...";
myp4.save_submit(change)</pre>
</dd>
<dt> </dt>
<dd>
<pre>
</pre>
</dd>
<p></p></dl>
<p>
</p>
<hr />
<h1><a name="compatibility_with_previous_versions">COMPATIBILITY WITH PREVIOUS VERSIONS</a></h1>
<p>This version of P4 is largely backwards compatible with previous
versions with the following exceptions:</p>
<p>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).</p>
<p>
</p>
<hr />
<h1><a name="licence">LICENCE</a></h1>
<p>
See <a href="LICENSE.txt">LICENSE.txt</a></p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Robert Cowham, Vaccaperna Systems Ltd (robert at vaccaperna dot co dot uk)</p>
<p>Thanks to Tony Smith for the documentation for P4Perl on which this is based.</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p>Perforce API documentation.</p>
<p>$Id: //guest/robert_cowham/perforce/API/python/main/P4.html#6 $</p>
</body>
</html>
| # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #6 | 6043 | Robert Cowham | Changed license (with Mike's agreement) to make it more easily distributable and also maintainable by Perforce | ||
| #5 | 5833 | Robert Cowham | - Fix typo in doc and document api() call. | ||
| #4 | 5101 | Robert Cowham | Updated docs and added new Linux binary. | ||
| #3 | 5059 | Robert Cowham | Tidied docs and ensured added to .zip file. | ||
| #2 | 5057 | Robert Cowham |
- Added P4Error class and catch all errors - shouldn't see P4Client.error any more! - Raise the error when appropriate. - Added translate() function to allow working with Internationalised servers. - Fix problem with diff2 and diff |
||
| #1 | 4964 | Robert Cowham | Saved first version of docs. |