Home       Trees       Indices       Help   
PyPerforce
Package perforce :: Module connection :: Class Connection
[frames] | no frames]

Class Connection



object --+
         |
        Connection

A single connection to a Perforce server.

Use instances of this class to connect to a Perforce server and run Perforce commands on the server.

Example: 
 | c = Connection()
 | c.port = 'my-server:1666'
 | try:
 |   c.connect()
 |   c.client = 'my-client'
 |   results = c.run('sync')
 |   c.disconnect()
 |   for msg in results.messages:
 |     print str(msg)
 | except ConnectionFailed:
 |   print 'Could not connect to Perforce server.'
 | except ConnectionDropped:
 |   print 'Connection to Perforce server dropped.'


Instance Methods
 
__init__(self, **options)
Construct a new Perforce connection object.
 
__del__(self)
Destruct the Perforce connection object.
 
connect(self, **options)
Connect to the Perforce server.
 
disconnect(self)
Disconnect from the Perforce server.
 
run(self, command, *args, **kwargs)
Run a command on the connected Perforce server.

Inherited from object: __delattr__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __str__

Properties
boolean connected
Flag indicating whether the Connection object is currently connected to a Perforce server.
str api
The Perforce client protocol version used by the connection.
str server
The Perforce server protocol version used by the connection.
boolean nocase
Flag indicating whether the server is case insensitive.
str (may be set with perforce.CharSet or NoneType) charset
The character set to use for encoding unicode file data.
str or unicode client
The Perforce client to use for subsequent commands.
str or unicode cwd
The working directory to use for subsequent commands.
str (may be set using unicode) host
The hostname to identify as to the Perforce server.
callable or NoneType keepalive
A callback to check whether to keep the connection alive.
str or unicode language
The language to display Perforce messages in.
str os
The operating system as identified by Perforce.
str or unicode password
The password to use for running the next command.
str (may be set using unicode) port
The Perforce server address and port number.
str or unicode prog
The client program name to identify this connection with.
str or unicode user
The Perforce username to use for running the next command.
str or NoneType config
The config file currently being used by this connection.
str or unicode ticketFile
The P4TICKETS file to use for this connection.
str or unicode version
The client program version to identify this connection with.

Inherited from object: __class__

Method Details

__init__(self, **options)
(Constructor)

 

Construct a new Perforce connection object.

The connection is initially disconnected.
Parameters:
Overrides: object.__init__

See Also: connect, connected

__del__(self)
(Destructor)

 

Destruct the Perforce connection object.

Disconnects from the Perforce server if still connected.

See Also: disconnect

connect(self, **options)

 
Connect to the Perforce server.
Parameters:
  • options - Attributes to set after the connection is established.
  • prog (str or unicode) - The program to identify as on this connection. Convenience notation for setting self.prog after connecting.
  • version (str or unicode) - The version of the program to identify as on this conenction. Convenience notation for setting self.version after connecting.
  • keepalive (callable or NoneType) - A callback function that is called periodically during long operations to check if the client still needs the results. The object should be callable with no arguments and should return True to keep the connection alive or False if the connection should be dropped. Pass None to always keep the connection alive.
Raises:

Note: The port and api properties must be set before calling this method to have an effect.

disconnect(self)

 

Disconnect from the Perforce server.

If not connected then calling this method is a no-op.

run(self, command, *args, **kwargs)

 

Run a command on the connected Perforce server.

Example: 
 | c.run('sync', '-f', 'foo.txt#3', client='my-client')
Parameters:
  • command (str or unicode) - The Perforce command to run.
  • args (tuple of str or unicode) - The arguments to pass to the Perforce command.
  • ui (perforce.api.ClientUser) - Specify the ClientUser object to process the Perforce command events. Use of this parameter overrides the input and output parameters.
  • input (str, unicode, perforce.forms.Form or list of str or unicode) - Specify the input to give to the Perforce command. Pass some input to this parameter when running commands using the -i flag or running 'passwd' or 'login' commands.
  • output (adaptable to perforce.results.IOutputConsumer) - Specify an alternative output handler to be called when output of the command is received from the Perforce server. If not supplied then a perforce.results.Results object is used.
  • charset (str, perforce.CharSet or NoneType) - The override of the charset attribute to use for running this command.
  • client (str or unicode) - The override of the client attribute to use for running this command.
  • cwd (str or unicode) - The override of the cwd attribute to use for running this command.
  • host (str) - The override of the host attribute to use for running this command.
  • language (str or unicode) - The override of the language attribute to use for running this command.
  • user (str or unicode) - The override of the user attribute to use for running this command.
  • password (str or unicode) - The override of the password attribute to use for running this command.
Returns:
Returns the value passed to the output parameter if provided, otherwise returns a perforce.results.Results object populated with the output of running the command.
Raises:

Property Details

connected

Flag indicating whether the Connection object is currently connected to a Perforce server.
Get Method:
unreachable.fget(self)
Type:
boolean

See Also: connect, disconnect

api

The Perforce client protocol version used by the connection.

Typical values:
  • '58' for 2005.2
  • '57' for 2004.1, 2004.2, 2005.1
  • '56' for 2003.2
  • '55' for 2003.1
Example: 
 | c.api = '56'   # Limit to Perforce 2003.2 behaviour
 | c.connect()
Set Method:
unreachable.fset(self, value)
Type:
str

Note: Must be set prior to calling self.connect() to have an effect on the connection's protocol version.

See Also: server, connect

server

The Perforce server protocol version used by the connection.

Possible values:
  • '23' for 2007.2
  • '22' for 2006.2
  • '21' for 2006.1
  • '20' for 2005.2
  • '19' for 2005.1
  • '18' for 2004.2
  • '17' for 2003.2
  • '16' for 2003.1
  • '15' for 2002.2
  • '13' for 2002.1
  • '11' for 2001.1
  • '10' for 2000.2
  • '9' for 2000.1
  • '0' if server version not initialised, call run.
Get Method:
unreachable.fget(self)
Type:
str

Note: Is only initialised after running a command on this connection.

See Also: api, run

nocase

Flag indicating whether the server is case insensitive.
Get Method:
unreachable.fget(self)
Type:
boolean

Note: Can only be queried after running a command on this connection.

See Also: server, run

charset

The character set to use for encoding unicode file data.

Defaults to the value found in the P4CONFIG file if one exists, otherwise to the value of the P4CHARSET environment variable if set, otherwise to the value stored in the registry, otherwise to ''.

Set this attribute to something other than 'none' to enable 'unicode' mode and allow connections to Unicode-enabled Perforce servers.

Supported character sets:
  • 'none'
  • 'utf8'
  • 'utf8-bom' *
  • 'iso8859-1'
  • 'iso8859-5' *
  • 'iso8859-15'
  • 'utf16'
  • 'utf16-nobom' *
  • 'utf16le' *
  • 'utf16be' *
  • 'utf16le-bom' *
  • 'utf16be-bom' *
  • 'shiftjis'
  • 'eucjp'
  • 'winansi'
  • 'winoem'
  • 'macosroman'
  • 'cp1251' *
  • 'koi8-r' *
* - Only available for Perforce 2005.2 or later clients
Get Method:
unreachable.fget(self)
Set Method:
unreachable.fset(self, value)
Type:
str (may be set with perforce.CharSet or NoneType)

client

The Perforce client to use for subsequent commands.

Defaults to the value in the P4CONFIG file if one exists, otherwise to the value of the P4CLIENT environment variable if set, otherwise to the value stored in the registry, otherwise to the machine name.
Get Method:
unreachable.fget(self)
Set Method:
unreachable.fset(self, value)
Type:
str or unicode

cwd

The working directory to use for subsequent commands.

This path is used to resolve relative local file system paths provided to Perforce commands to absolute paths.

Defaults to the current working directory of the current process.
Get Method:
unreachable.fget(self)
Set Method:
unreachable.fset(self, value)
Type:
str or unicode

Note: Setting the working directory for the Connection causes Perforce to search for a new P4CONFIG file which, if found, may reset existing environment values.

See Also: config

host

The hostname to identify as to the Perforce server.

Defaults to the value in the P4CONFIG file if found, otherwise to the value of the P4HOST environment value, otherwise to the value in the registry, otherwise to the local machine name.
Get Method:
unreachable.fget(self)
Set Method:
unreachable.fset(self, value)
Type:
str (may be set using unicode)

keepalive

A callback to check whether to keep the connection alive.

The keepalive attribute should be set to an object that is callable with no arguments and should return True to keep the connection alive and False if the connection should be dropped. The callback is called periodically during long running operations to see if the client still wants to continue running the operation.

Returning False will result in the call to run() raising the ConnectionDropped exception.

Setting to None is equivalent to setting to a function that always returns True.
Set Method:
unreachable.fset(self, value)
Type:
callable or NoneType

Note: Setting this value has an effect only after a connection has been made to the Perforce server.

language

The language to display Perforce messages in.

Defaults to the value in the P4CONFIG file if found, otherwise to the value of the P4LANGUAGE environment value, otherwise to the value in the registry, otherwise to ''.
Get Method:
unreachable.fget(self)
Set Method:
unreachable.fset(self, value)
Type:
str or unicode

Note: The Perforce server must have the particular language pack installed to support translated messages.

os

The operating system as identified by Perforce.

Typical values:
  • 'NT' for Windows platforms
  • 'UNIX' for Linux and Cygwin platforms
Get Method:
unreachable.fget(self)
Type:
str

password

The password to use for running the next command.

May be set to the Perforce user's password or a valid ticket identifier returned from the 'p4 login' command. If a password or ticket is not provided then a ticket value is obtained from the P4TICKETS file.

Defaults to the value in the P4CONFIG file if one exists, otherwise to the value of the P4PASSWD environment variable, otherwise to the value in the registry, otherwise to ''.
Get Method:
unreachable.fget(self)
Set Method:
unreachable.fset(self, value)
Type:
str or unicode

See Also: ticketFile

port

The Perforce server address and port number.

Defaults to the value in the P4CONFIG file if one exists, otherwise to the value of the P4PORT environment variable, otherwise to the value in the registry, otherwise to 'perforce:1666'.
Get Method:
unreachable.fget(self)
Set Method:
unreachable.fset(self, value)
Type:
str (may be set using unicode)

Note: Must be set prior to calling connect() to have an effect.

prog

The client program name to identify this connection with.

The value set here shows up when running the 'p4 monitor' command and in the Perforce server logs.
Set Method:
unreachable.fset(self, value)
Type:
str or unicode

Note: Setting this value has an effect only after a connection has been made to the Perforce server.

user

The Perforce username to use for running the next command.

Defaults to the value in the P4CONFIG file if one exists, otherwise to the value of the P4USER environment variable, otherwise to the value in the registry, otherwise to the o/s username of the currently logged in user.
Get Method:
unreachable.fget(self)
Set Method:
unreachable.fset(self, value)
Type:
str or unicode

config

The config file currently being used by this connection.

The config file name is obtained from the P4CONFIG environment variable if set, otherwise from the value stored in the registry. The current working directory, cwd, and its ancestors are searched for a config file. If a config file is found then it its path is returned, otherwise None is returned.
Get Method:
unreachable.fget(self)
Type:
str or NoneType

Note: Only available in Perforce 2005.2 or later clients.

ticketFile

The P4TICKETS file to use for this connection.

This attribute may be set to specify the file to store the Perforce authentication tickets obtained by running the 'p4 login' command.

The path should be an absolute path.
Set Method:
unreachable.fset(self, value)
Type:
str or unicode

version

The client program version to identify this connection with.

The value set here shows up when running the 'p4 monitor' command and in the Perforce server logs.
Set Method:
unreachable.fset(self, value)
Type:
str or unicode
Notes:
  • Setting this value has an effect only after a connection has been made to the Perforce server.
  • Only available for Perforce 2005.2 or later clients.

See Also: prog


   Home       Trees       Indices       Help   
PyPerforce
Generated by Epydoc 3.0beta1 on Sun Aug 05 12:39:02 2007 http://epydoc.sourceforge.net