Package perforce :: Module api :: Class ClientApi

Class ClientApi

object --+
         |
        ClientApi

A Perforce ClientApi object.

Instance Methods

__new__(T, S, ...)
Returns: a new object with type S, a subtype of T

final()
Close the connection with the Perforce server.

getCharset()
The character set used to encode Unicode files and data.

getClient()
The name of the client that Perforce commands that operate on a client (eg.

getConfig()
The config file currently being used by this object.

getCwd()
This path is used to resolve relative local file system paths to absolute file system paths.

getHost()
The hostname of the machine to identify to Perforce as.

getLanguage()
The language that Perforce messages should be displayed to the client in

getOs()
Returns: str

getPassword()
The password used to authenticate the current user with Perforce for subsequent commands.

getPort()
The address and port of the Perforce server to connect to.

getProtocol(capability)
Query a Perforce server protocol capability.

getUser()
The username used to authenticate with the Perforce server.

init()
Attempt to connect to the Perforce server.

run(command, ui)
Run a command on the Perforce server.

setArgs(args)
Set the arguments to pass to subsequent run() commands.

setBreak(keepalive)
Set a callback function that Perforce can call periodically during long running operations to check whether or not to keep processing.

setCharset(charset)
Set the new character set used to encode Unicode files and data.

setClient(client)
Set the new Perforce client to be used for subsequent commands.

setCwd(cwd)
Set the new working directory to be used for subsequent commands.

setHost(hostname)
Set the new hostname to be used for subsequent commands.

setIgnorePassword()
Clear any default values for the password obtained from the environment.

setLanguage(language)
Set the new language to be used for subsequent commands.

setPassword(password)
Set the new password to be used for subsequent commands.

setPort(port)
Set the port and address of the Perforce server.

setProg(name)
Set the program name for the active connection.

setProtocol(capability, value)
Set the value of a Perforce client protocol capability.

setTicketFile(path)
Set the new location of the ticket file to use for subsequent commands.

setTrans(output, content=..., fnames=..., dialog=...=...)
Set the character set used to translate unicode strings.

setUser(username)
Set the user to authenticate as for subsequent commands.

setVersion(version)
Set the program version for the active connection.

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

Properties
Inherited from `object`: `__class__`

Method Details

new(T, S, ...)

Returns:

a new object with type S, a subtype of T

Overrides: object.__new__

final()

Close the connection with the Perforce server.

A no-op if the connection is not currently connected.

Returns:

int

See Also: init

getCharset()

The character set used to encode Unicode files and data.

Returns:

str

See Also: setCharset, setTrans

getClient()

The name of the client that Perforce commands that operate on a client (eg. 'p4 sync') will operate on.

Returns:

str or unicode

See Also: setClient

getConfig()

The config file currently being used by this object.

The current directory and its parents are searched for a P4CONFIG file whenever the current working directory changes.

Returns:

str or unicode

See Also: setCwd

getCwd()

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

Returns:

str or unicode

See Also: setCwd

getHost()

The hostname of the machine to identify to Perforce as.

Returns:

str

See Also: setHost

getLanguage()

The language that Perforce messages should be displayed to the client in

Returns:

str or unicode

Note: This requires that the appropriate language pack be installed for the Perforce server.

See Also: setLanguage

getOs()

Returns:

str

getPassword()

The password used to authenticate the current user with Perforce for subsequent commands.

Returns:

str or unicode

See Also: setPassword, getUser

getPort()

The address and port of the Perforce server to connect to.

Returns:

str

See Also: setPort, init

getProtocol(capability)

Query a Perforce server protocol capability.

Some common protocol capabilities are:

'nocase' - Set to '1' if the server is case-insensitive.
'server2' - Set to the server protocol version. For example:
- '0' - Server version not set, need to run a command.
- '9' - Perforce 2000.1
- '10' - Perforce 2000.2
- '11' - Perforce 2001.1
- '13' - Perforce 2002.1
- '15' - Perforce 2002.2
- '16' - Perforce 2003.1
- '17' - Perforce 2003.2
- '18' - Perforce 2004.2
- '19' - Perforce 2005.1
- '20' - Perforce 2005.2

Parameters:

capability (str) - The protocol capability to query.

Returns:

str or None

Note: This function reports on the server protocol parameters currently in use and so only returns useful values after the connection has been made and a command has been run.

See Also: setProtocol, run

getUser()

The username used to authenticate with the Perforce server.

Returns:

str or unicode

See Also: setUser, getPassword

init()

Attempt to connect to the Perforce server.

The connection may be disconnected later by calling final()

Returns:

None

Raises:

perforce.api.ConnectionFailed - If the client could not connect to the server.

Note: setPort and setProtocol must be called before init to have any effect.

See Also: setPort, setProtocol, final

run(command, ui)

Run a command on the Perforce server.

Arguments may be passed to the command by calling setArgs()

Output from the command is received through calls to methods of the ui object. Clients may wish to subclass the ClientUser class and override its methods to provide custom handling of output.

Parameters:

command (str or unicode) - The name of the command to run on the Perforce server. eg. 'sync'
ui (ClientUser or a subclass) - The ClientUser object to receive output from running this command.

Returns:

None

Raises:

perforce.api.ConnectionDropped - If the connection was dropped before the command could be completed.
RuntimeError - If the client is not connected yet

Notes:

The client must be connected first by calling init()
The specified ui can only be used to handle results from multiple simultaneous commands if they are all using the same charset.

See Also: init, setArgs, ClientUser

setArgs(args)

Set the arguments to pass to subsequent run() commands.

Parameters:

args (tuple of str or unicode) - A tuple of strings containing the arguments.

Returns:

None

setBreak(keepalive)

Set a callback function that Perforce can call periodically during long running operations to check whether or not to keep processing.

Use this to enable cancelling of long-running options.

Parameters:

keepalive (callable or NoneType) - A callable object that will be called periodically during long running operations with no arguments to check whether to keep the connection alive. The function should return True to keep the connection alive and False to terminate the connection and cause the call to run() to raise ConnectionDropped.

Returns:

None

Raises:

TypeError - If keepalive is not callable or None.

Note: Must be called after init to have any effect.

setCharset(charset)

Set the new character set used to encode Unicode files and data.

Parameters:

charset (str) - One of the strings returned by calling str() on a CharSet instance or None.

Returns:

None

See Also: getCharset, CharSet

setClient(client)

Set the new Perforce client to be used for subsequent commands.

Parameters:

client (str or unicode) - The name of the Perforce client to use.

Returns:

None

See Also: setClient

setCwd(cwd)

Set the new working directory to be used for subsequent commands.

Parameters:

cwd (str or unicode) - The path of the new working directory.

Returns:

None

Note: Changing the current directory may cause a new P4CONFIG file to be loaded which can override other environment values.

See Also: getCwd

setHost(hostname)

Set the new hostname to be used for subsequent commands.

Parameters:

hostname (str or unicode) - The hostname to identify to the Perforce server as.

Returns:

None

See Also: getHost

setIgnorePassword()

Clear any default values for the password obtained from the environment.

This means that any password will either need to come from a ticket file or be set manually using setPassword().

Returns:

None

See Also: getPassword, setPassword, setTicketFile

setLanguage(language)

Set the new language to be used for subsequent commands.

Parameters:

language (str or unicode) - The language to use.

Returns:

None

Note: The Perforce server must have the appropriate language pack installed to support messages in different languages.

See Also: getLanguage

setPassword(password)

Set the new password to be used for subsequent commands.

A ticket returned from a 'p4 login' command may also be used as the password if the Perforce server supports tickets.

Parameters:

password (str or unicode) - The password or ticket to use for authentication.

Returns:

None

See Also:: getPassword, setTicketFile

setPort(port)

Set the port and address of the Perforce server.

Parameters:

port (str or unicode) - The port of the Perforce server to use. The port must be a string of the form 'hostname:portnum'. eg. 'perforce:1666'

Returns:

None

Note: The port must be set before init() is called in order to take effect.

See Also: getPort, init

setProg(name)

Set the program name for the active connection.

This value is used by 'p4 monitor' to identify the client application for a particular connection.

Parameters:

name (str or unicode) - The program name to use.

Returns:

None

Note: Must be called after init() in order to take effect.

See Also:: init, setVersion

setProtocol(capability, value)

Set the value of a Perforce client protocol capability.

Some common protocol parameters are:

'tag' - Output of commands is in tagged form if defined.
'specstring' - The form spec string is sent with the form data.
'api' - The client protocol version to use. Typical values:
- '55' for Perforce 2003.1
- '56' for Perforce 2003.2
- '57' for Perforce 2004.1, 2004.2, 2005.1
- '58' for Perforce 2005.2

Parameters:

capability (str) - The name of the protocol capability to set.
value (str) - The value of the protocol capability.

Returns:

None

Note: Must be called before init() to have an effect.

See Also: getProtocol, init

setTicketFile(path)

Set the new location of the ticket file to use for subsequent commands.

The ticket file stores tickets from the 'p4 login' command.

Parameters:

path (str or unicode) - The path to the ticket file. Must be full pathname to the file and not a directory.

Returns:

None

setTrans(output, content=..., fnames=..., dialog=...=...)

Set the character set used to translate unicode strings.

If output is CharSet.NOCONV then content, fnames and dialog parameters are ignored. Otherwise if output is not CharSet.NOCONV and content, fnames or dialog are CharSet.NOCONV then their value is set to the same as output.

Parameters:

output (perforce.api.CharSet) - Translation to use for message output and input arguments. Cannot be one of the UTF-16 character sets.
content (perforce.api.CharSet) - Translation to use for 'unicode' file content written using the perforce.api.FileSys objects. If not specified then this value remains unchanged.
fnames (perforce.api.CharSet) - Translation to use for file system path names passed to perforce.api.FileSys objects. If not specified then this value remains unchanged. Cannot be one of the UTF-16 character sets.
dialog (perforce.api.CharSet) - Translation to use for form specification dialog files output during interactive form-editing commands. If not specified then this value remains unchanged. Cannot be one of the UTF-16 character sets.

Returns:

None

setUser(username)

Set the user to authenticate as for subsequent commands.

Parameters:

username (str or unicode) - The username to use.

Returns:

None

See Also: getUser, setPassword

setVersion(version)

Set the program version for the active connection.

This value is used by 'p4 monitor' to identify the client application for a particular connection.

Parameters:

version (str or unicode) - The version string to use.

Returns:

None

Note: Must be called after init() in order to take effect.

See Also: setProg