<!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:[email protected]" /> </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 p4c.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> </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>Copyright (c) 2004-05, Vaccaperna Systems Ltd. All rights reserved.</p> <p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p> <p>1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.</p> <p>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.</p> <p>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.</p> <p> </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> </body> </html>
| # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #1 | 5578 | Shawn Hladky | branching P4Python | ||
| //guest/robert_cowham/perforce/API/python/main/P4.html | |||||
| #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. | ||