Release Notes for
P4Python, the Python interface to the Perforce SCM System
Version 2009.1
Introduction
This document lists all user-visible changes to P4Python
starting from release 2007.3, the first supported P4Python release.
Perforce numbers releases YYYY.R/CCCCC, for example, 2007.3/30547.
YYYY is the year; R is the release of that year; CCCCC is the
bug fix change level. Each bug fix in these release notes is
marked by its change number. Any build includes all bug fixes
of all previous releases and all bug fixes of the current
release up to the bug fix change level.
To display the version of P4Python you have installed,
start Python and issue the following commands:
>>> import P4
>>> print P4.P4.identify()
--------------------------------------------------------------------------
Installing P4Python
Windows users can download an installer containing pre-built packages for
P4Python from the Perforce FTP site. Users on other platforms must
build from source, as detailed below.
--------------------------------------------------------------------------
Upgrading P4Python
Before installing P4Python 2009.1, uninstall any older versions of
P4Python. Some earlier versions of P4Python consisted of the following
files, which must be deleted before installing a later version.
p4.py
p4.pyc
p4.pyo
P4Client.pyd
--------------------------------------------------------------------------
Building P4Python from Source
1. Download the appropriate Perforce C++ API build from the Perforce FTP
site at "ftp.perforce.com/perforce". OS X users must get the universal
binary version of the API in the "bin.darwin*u" directory.
Windows users must get "p4api_vs2003_static.zip" in the
"bin.ntx86" directory.
2. Extract the API archive into a new, empty directory.
3. Modify the file setup.cfg to reflect the location of the API by
setting p4_api=<api-dir>
4. Build P4Python with the following command:
python setup.py build
For a clean installation, remove the directory named "build" and its
contents. To verify that the build succeeded, run the test script:
python p4test.py
The Perforce server executable "p4d" must be in the PATH.
5. To install P4Python, run the following command. On UNIX systems,
this step must be run as root:
python setup.py install
Ensure that the umask is set correctly (typically 0022) before
running the install. With a umask of 027, for example, the resulting
installed files are accessible only by users of group root.
--------------------------------------------------------------------------
Compatibility Statements
Server Compatibility
You can use any release of P4Python with any release of the Perforce
server later than 2001.1
API Compatibility
The 2009.1 release of P4Python requires the 2009.1 Perforce API. Older
releases (down to 2008.2) might work but are not supported.
Python compatibility
The 2009.1 release of P4Python is compatible with Python 2.5.x and
Python 2.6 when built from source. The build included in the Windows
installer is compatible with Python 2.5.x.
Platform compatibility
This release is certified on the following platforms:
Linux 2.6 x86
Solaris 10 x86
NT x86
FreeBSD 6 x86
Mac OSX 10.5 x86
Compiler Compatibility
To build P4Python from source, you must use a version of
P4Python that has been compiled with the same compiler used to
build the Perforce C++ API. For most platforms, use gcc/g++.
Attempting to use a different compiler or a different version
of the compiler causeslinker errors due to
differences in name handling between compilers.
On Windows platforms, Python 2.5.1 and the P4Python installer
are built with Visual Studio 2003. You can download the
static version of the Perforce API for this compiler from the
Perforce FTP site and build P4Python yourself. Visual Studio
2005 cannot be used to compile Python or P4Python. Use the
P4Python Windows installer available from the Perforce web
site.
Compatibility with Previous Releases of P4Python
P4Python 2009.1 is compatible with previous releases of
P4Python from Perforce Software, unless otherwise specified.
Compatibility with the P4Python from the Public Depot
Perforce P4Python is significantly different from the version of
P4Python in the Perforce Public Depot. Perforce P4Python
contains several improvements and interface changes
intended to make P4Python consistent with the other scripting
interfaces and with Python in general.
If you are migrating from Public Depot version of P4Python, edit your
scripts to ensure that the scripts comply with the new
interface. The differences are detailed below.
New module name
---------------
The P4Python module has been renamed from p4 to P4. For example:
Old:
>>> import p4
>>> p4c = p4.P4()
New:
>>> import P4
>>> p4 = P4.P4()
By convention, Public Depot P4Python used "p4c" as an instance variable
because "p4" was used as a module name. Because the module has been
renamed "P4", you can use "p4" for your instance variables. All demos
and tests use the new convention.
Deleted methods
---------------
The following methods have been deleted from the P4 class and
are no longer available.
dropped Use connected()
parse_forms Form parsing is now always on
tagged See tagged attribute below
New methods
-----------
The following methods are new to Perforce P4Python.
connected Returns True if the client is connected
format_xxx Converts a dict-based specification into a
string (replace xxx with spec type, for
example: format_client)
identify Returns information about P4Python
parse_xxx Converts a string into a P4.Spec object
(replace xxx with spec type)
run_filelog Runs 'p4 filelog' and returns an array of
P4.DepotFile objects
run_login Runs "p4 login" using current password
run_password Runs "p4 passwd" with old and new password
run_submit Runs "p4 submit"
Attributes
----------
Perforce P4Python provides the following attributes. Attributes
can be set 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'
Most attributes can be set and read. Attributes are strings unless noted otherwise.
api_level API compatibility level, INTEGER
charset The character set to use. String,
not a constant as in previous versions
client Client to use (P4CLIENT)
cwd Current Working Directory
debug Debug level (for debugging P4Python), INTEGER
errors Array of errors returned by the server
(Read-Only), LIST
exception_level Determines whether exceptions are thrown,
INTEGER
host Client Host
input Input for next command, can be STRING, LIST or
DICTIONARY
maxlocktime MaxLockTime for commands, INTEGER
maxresults MaxResults for commands, INTEGER
maxscanrows MaxScanRows for commands, INTEGER
p4config_file Returns the config file path (Read-Only)
password Value of P4PASSWD
port Value of P4PORT
prog Name of the script, shown in the server log
server_level Returns the server level (Read-Only)
tagged Boolean value, determines whether to use tagged
mode, INTEGER
ticket_file Returns the name of the ticket file
user Value of P4USER
warnings Array of warnings returned by the server
(Read-Only), LIST
Tagged mode and form parsing
----------------------------
In Perforce P4Python 2007.3, form parsing and tagged
output are enabled by default. (In Public Depot P4Python,
tagged output and form parsing mode were disabled by default,
but most scripts enabled them immediately.)
Form parsing cannot be disabled explicitly, but tagged output can
be enabled or disabled by setting p4.tagged as follows:
p4.tagged = False # Disabled
p4.tagged = True # Enabled
This method can be used to disable form parsing, because
form parsing does not work when tagged output is
disabled.
--------------------------------------------------------------------------
Key to symbols used in change notes below.
* -- requires new p4python
** -- requires new p4d server program
*** -- requires new P4API
--------------------------------------------------------------------------------
Major new functionality in 2009.1
#191476 (Bug #26731) *
Support for the Python "with" statement:
P4.connect() now returns a Contect Management object that can be
used in a "with" statement with a block. When the block is finished,
the connection is automatically disconnected:
import P4
p4 = P4.P4()
with p4.connect():
# execute statements here
# p4 is now disconnected
Also, there are two new methods, P4.while_tagged() and
P4.at_exception_level() that, when used in a "with" statement,
set the tagged mode and exception_level for the block and then
reset it back to the original state. For example:
with p4.at_exception_level(P4.RAISE_ERROR): # no exceptions for warnings
p4.run_sync("//depot/main/...")
Bugs fixed in 2009.1
#192108 (Bug #32920) *
P4Python now correctly parses jobs when the jobspec contains
fields with names ending in numbers.
#191458 (Bug #32834) *
Charset can now be reset to the empty string ''.
--------------------------------------------------------------------------
New functionality in 2008.2
#164805 (Bug #30704) *
P4Python now builds under CYGWIN.
#163103 (Bug #30363) *
#166832 *
A new class P4.Map has been defined in P4Python
that allows users to create, and work with, Perforce mappings
without requiring a connection to a server. Methods in the P4.Map
class are:
P4.Map() Constructor.
P4.Map.join() Class method. Joins two maps to create a
third.
P4.Map.clear() Empties the map
P4.Map.count() Returns the number of entries in the map
P4.Map.is_empty() Returns True if the map is empty
P4.Map.insert() Adds new entries to the map
P4.Map.translate() Translates a string through the map
P4.Map.includes() Returns True if the supplied string is
visible through the map
P4.Map.reverse() Swap left and right sides of the mapping
P4.Map.lhs() Returns the left-hand-side of the map
P4.Map.rhs() Returns the right-hand-side of the map
P4.Map.as_array() Returns the map as an array
Bugs fixed in 2008.2
#176515 (Bug #31367) *
Using P4.run_print() in untagged mode throws an exception:
IndexError: list index out of range
This is now fixed. P4.run_print() can be used both in tagged and
untagged mode.
#157855 (Bug #29933) *
P4Python now correctly loads the value of P4CHARSET from the
environment.
--------------------------------------------------------------------------
--------------------------------------------------------------------------
New functionality in 2008.1
#157600 *
Added support for P4.run_resolve(). The default for run_resolve() is
now to accept the merge hint provided by the server unless the hint is
"e", indicating a conflict. In this case, run_resolve() will skip the
resolve.
P4.run_resolve() can also accept a "resolver" keyword argument, which
should point to an instance of a subclass of P4.Resolver. The subclass
should overwrite the method P4.Resolver.resolve(self, mergeData) and return
a string indicating how the resolve should proceed.
To get the old behaviour of "resolve", run the command P4.run("resolve"). You will
need to set P4.input to the correct response in this case.
#152008 (Bug #28761) *
Added support for Python 2.4.
#152362 (Bug #29024) *
The 'P4.env( var )' method has been added to the
P4 class. This instance method enables the caller to interrogate the
Perforce environment, including reading Perforce variables
from P4CONFIG files and, on Windows, the registry. P4.cwd
now loads any P4CONFIG file settings that are appropriate to
the new working directory.
#153547 (Bug #29310) *
P4Python now supports Mac OSX 10.5.
Bugs fixed in 2008.1
#175062 (Bug #31637) *
P4Python sometimes incorrectly decrements the reference count of None
when calling p4.run_filelog(). In certain circumstances, this could
cause Python to deallocate None, causing a fatal error.
This problem has been fixed.
#168966 (Bug #31180) *
P4Python did not release its output variable correctly. This caused
a crash on 64 bit versions of Python when the P4 object went out of
scope. This is now fixed.
#166644 (Bug #30723) *
P4Python connections were not being correctly cleaned up when
they were discarded due to a reference counting problem.
This problem has been corrected.
#161025 (Bug #30076) *
Fixed a serious memory leak problem in P4Python. Basically, all
results returned from P4.run() had too many reference counts,
which prevented the Python garbage collector from being able to clean
up these objects. Now P4Python is memory neutral, as can be checked
with the debug version of Python, which shows the total number of
reference counts.
#157844 (Bug #28653) *
Fixed an error with p4.run_filelog() when tagged output is off.
The "df" variable is now correctly initialized on line 333 of P4.py.
#156847 (Bug #28770) *
Calling print to retrieve the contents of a file no longer truncates
content.
#155969 (Bug #29703) *
When trying to create an illegal field in a Spec, P4Python would
try to raise a P4Error, only to fail because the wrong number
of arguments was provided to the Exception. This has been fixed.
--------------------------------------------------------------------------
--------------------------------------------------------------------------
Bugs fixed in 2007.3
#149927 (Bug #28703) *
The presence of deleted revisions in a file's history could lead
to P4Python throwing an error message. This occurred because
deleted revisions do not have 'digest' or 'fileSize' fields.
This problem has been corrected.
#146116 (Bug #28260) *
The P4Python test harness, p4test.py, was omitted from the source
distribution in error. This problem has been corrected.
#146024 (Bug #28077) *
P4.Revision doesn't have a depot_file, or depotFile attribute as
its counterparts in P4Perl and P4Ruby do. This is now fixed.