This programmer's reference gives complete and detailed infomation on the pysvn API.
The pysvn Programmer's Guide gives an tutorial introduction to the pysvn module.
The pysvn module has the following variables:
The pysvn module has three classes:
The following enumerations are provided:
Use python builtin dir() to list all available values in an enumeration:
print dir( pysvn.wc_notify_action )
Interface summary:
client = pysvn.Client() client = pysvn.Client( config_dir )
The default subversion configuration directory is used if the config_dir is ommitted or set to ''.
The configuration directory is automatically created if it is missing.
A Client object can only be used on one thread at a time. If two threads attempt to call methods of Client at the same time one of the threads will get a pysvn.ClientError exception with the value 'client in use on another thread'.
Variables | Callbacks | Methods |
exception_style allows you to control the style of exception raised by pysvn.
exception_style is used to control how pysvn raises ClientError exceptions.
The default value, 0, makes pysvn raise exceptions as it did prior to pysvn 1.1.2.
exception_style can be set to 0 or 1, see ClientError for details of effect of the style on the exception raised.
pysvn uses callback functions to allow for realtime feedback and credential handling.
callback_cancel allows you to cancel a long running subversion command.
callback_notify gives feedback as commands runs.
callback_get_log_message is called when a log message is required.
callback_get_login is called to get a username and password to access a repository.
callback_ssl_server_trust_prompt is called when using HTTPS to a server whoes certificate needs is trust verifing.
It is possible to use the Client object without setting up any calls backs. Make sure that all nessesary usernames, passwords and SSL certificate information are stored in the subversion configuration directory.
import pysvn cancel_command = False def cancel(): return cancel_command client = pysvn.Client() client.callback_cancel = cancel
The callback_cancel function is called frequently during long running commands. Return True to cause the command to cancel, return False to allow the command to continue.
import pysvn log_message = "reason for change" def get_log_message(): return rc, log_message client = pysvn.Client() client.callback_get_log_message = get_log_message
The callback_get_log_message is called when a log message is required to complete the current command. Return the True in rc and a log message as a string. Returning False in rc will cause the command to be cancelled. An empty log_message is not allowed and may cause the command to be cancelled.
unicode strings cannot be handled. If you have a unicode string convert to UTF-8.
import pysvn def get_login( realm, username, may_save ): return retcode, username, password, save client = pysvn.Client() client.callback_get_login = get_login
callback_get_login is called each time subversion needs a username and password in the realm to access a repository and has no cached credentials.
The may_save parameter is true if subversion is willing to save the answers returned by the callback_get_login function.
pysvn expect the callback_get_login to return a tuple of four values (retcode, username, password, save).
import pysvn def notify( event_dict ): return client = pysvn.Client() client.callback_notify = notify
The callback_notify is called as a command runs each time an interesting event occurs. The details of the event are passed to the callback_notify function as a dictionary.
The dictionary contains the following values:
import pysvn def ssl_client_cert_password_prompt( realm, may_save ): return retcode, password, save client = pysvn.Client() client.callback_ssl_client_cert_password_prompt = ssl_client_cert_password_prompt
callback_ssl_client_cert_password_prompt is called each time subversion needs a password in the realm to use a client certificate and has no cached credentials.
The may_save parameter is true if subversion is willing to save the answers returned by the callback_ssl_client_cert_password_prompt function.
pysvn expect the callback_ssl_client_cert_password_prompt to return a tuple of three values (retcode, password, save).
import pysvn def ssl_client_cert_prompt(): return retcode, certfile client = pysvn.Client() client.callback_ssl_client_cert_prompt = ssl_client_cert_prompt
callback_ssl_client_cert_prompt is called each time subversion needs a client certificate.
pysvn expect the callback_ssl_client_cert_prompt to return a tuple of two values (retcode, certfile).
import pysvn def ssl_server_prompt( ): return client = pysvn.Client() client.callback_ssl_server_prompt = ssl_server_prompt
NOT IMPLEMENTED - what it used for?
import pysvn def ssl_server_trust_prompt( trust_dict ): return retcode, accepted_failures, save client = pysvn.Client() client.callback_ssl_server_trust_prompt = ssl_server_trust_prompt
The callback_ssl_server_trust_prompt is called each time an HTTPS server presents a certificate and subversion is not sure if it should be trusted. callback_ssl_server_trust_prompt is called with information about the certificate in trust dict.
pysvn expect the callback_ssl_server_trust_prompt to return a tuple of three values (retcode, accepted_failures, save).
add( path, recurse=True, force=False ) add( [path,path], recurse=True, force=False )
Schedules all the files or directories specfied in the paths for addition to the repository. Set recurse to True to recursively add a directory's children. Files are added at the next checkin.
Note: The force parameter is only available for svn 1.1.0 or later
file_annotation = \ annotate( url_or_path, revision_start=pysvn.Revision( opt_revision_kind.number, 0 ), revision_end=pysvn.Revision( opt_revision_kind.head ) )
Return the annotation for each line in the url_or_path from revision_start to revision_end. The file_annotation is a list of dictionaries, one per line. The dictionaries contains:
file_text = \ cat( url_or_path, revision=pysvn.Revision( opt_revision_kind.head ) )
Return the contents of url_or_path for the specified revision as a string, file_text.
revision = \ checkin( path, log_message, recurse=True ) revision = \ checkin( [path,path], log_message, recurse=True )
checkin the files in the path_list to the repository with the specifed log_message. Set recurse to True to recursively checkin a directory's children with the same log message.
checkin returns a pysvn.Revision containing the number of the checked in revision.
revision = \ checkout( url, path, recurse=True, revision=pysvn.Revision( opt_revision_kind.head ) )
checkout the repository at url into the location specified by path. Set recurse to True to recursively check out a directory's children. Specify a revision to check out a particular version of the source tree.
checkout returns a pysvn.Revision containing the number of the checked out revision. Note: Subversion seems to return 0 rather then the actual revision. Use a notify callback and record the revision reported for the pysvn.wc_notify_action.update_completed event. This is what the svn command does.
copy( src_url_or_path, dest_url_or_path, src_revision=pysvn.Revision( opt_revision_kind.head ))
Duplicate something in working copy or repos, remembering history. The src_revision defaults to pysvn.Revision( opt_revision_kind.head ) if the src_path is a URL otherwise to pysvn.Revision( opt_revision_kind.working ).
src_url_or_path and dest_url_or_path can each be either a working copy (WC) path or URL:
If the destination is a URL the client_get_log_message callback must be implemented to return a log message.
cleanup( path )
Clean up any locks in the working copy at path. Usually such locks are the result of a failed or interrupted operation.
diff_text = \ diff( tmp_path, url_or_path, revision1=pysvn.Revision( opt_revision_kind.base ), revision2=pysvn.Revision( opt_revision_kind.working ), recurse=True, ignore_ancestry=False, diff_deleted=True )
return the differences between two revisions of the path. diff uses tmp_path to create any temporary files needed. Set recurse to True to recursively diff a directory's children. diff_text is a string containing the diff.
revision = \ export( src_url_or_path, dest_path, force=False, revision=pysvn.Revision(), native_eol=None )
Create an unversioned copy of the src_path at revision in dest_path.
native_eol parameter allows the line ending of files with svn:eol-style propery set to native to be overriden. Use None to use the eol-style of the Operating System, use "LF" to use "\n", "CR" to use "\r" and "CRLF" to use "\r\n".
export returns a pysvn.Revision containing the number of the checked in revision.
Note: The native_eol parameter is only available for svn 1.1.0 or later
enabled = get_auth_cache()
return true if credential caching is enabled, otherwise return false.
enabled = get_auto_props()
Returns true When svn will automatically set properties when adding files otherwise return false.
revision = \ import_( path, url, log_message, recurse=True )
Commit an unversioned file or tree into the repository.
Recursively commit a copy of PATH to URL. Parent directories are created as necessary in the repository.
import_ returns a pysvn.Revision containing the number of the checked in revision.
entry = info( path )
return information on path as a Entry object.
entry_list = \ info2( url_or_path, revision=pysvn.Revision( opt_revision_kind.unspecified ), peg_revision=pysvn.Revision( opt_revision_kind.unspecified ), recurse=True )
return information on url_or_path as a list of (path, info_dict) tuples.
The info_dict contains:
Note: The info2 command is only available with svn 1.2.0 or later
rc = \ is_url( url )
return True if the url is a known subversion url.
lock( url_or_path, lock_comment, force=False )
lock the url_or_path with lock_comment. Set force to True to override any lock held by another user.
Note: The lock command is only available with svn 1.2.0 or later
log_messages = \ log( url_or_path, revision_start=pysvn.Revision( opt_revision_kind.head ), revision_end=pysvn.Revision( opt_revision_kind.number, 0 ), discover_changed_paths=False, strict_node_history=True )
return the log messages for the specifed url_or_path between revisions start and end.
log returns a list of log messges each log messages is a dictionary. The dictionary contains:
entries_list = \ ls( url_or_path, revision=pysvn.Revision( opt_revision_kind.head ), recurse=True )
Returns a list of dictionaries for each file the given path at the provided revision. The dictionary contains:
merge( url_or_path1, revision1, url_or_path2, revision2, local_path, force=False, recurse=True )
Apply the differences between two sources to a working copy path.
mkdir( url_or_path, log_message ) mkdir( [url_or_path,url_or_path], log_message )
Create a new directory under revision control.
Create version controlled directories.
If url_or_path is a path, each directory is scheduled for addition upon the next commit.
If url_or_path is a URL, the directories are created in the repository via an immediate commit.
url_or_path can be a list of URLs and paths
In both cases, all the intermediate directories must already exist.
move( src_url_or_path, dest_url_or_path, src_revision=pysvn.Revision(), force=False )
Move/rename something in working copy or repository.
The src_revision defaults to pysvn.Revision( opt_revision_kind.head ) if the src_url_or_path is a URL otherwise to pysvn.Revision( opt_revision_kind.working ).
NOTE: this command is equivalent to a 'copy' and 'delete'.
src_path and dest_path can both be working copy (WC) paths or URLs:
If src_url_or_path is a path, each item is scheduled for deletion upon the next commit. Files, and directories that have not been committed, are immediately removed from the working copy. The command will not remove PATHs that are, or contain, unversioned or modified items; set force=True to override this behaviour.
If src_url_or_path is a URL, the items are deleted from the repository via an immediate commit.
rev = \ propdel( prop_name, url_or_path, revision=pysvn.Revision(), recurse=False )
delete the property prop_name from url_or_path
The src_revision defaults to pysvn.Revision( opt_revision_kind.head ) if the src_path is a URL otherwise to pysvn.Revision( opt_revision_kind.working ).
prop_list = \ propget( prop_name, url_or_path, revision=pysvn.Revision(), recurse=False )
Returns a list of tuples (url_or_path, prop_dict). The prop_dict contains the prop_name and its value if set on the url_or_path.
The src_revision defaults to pysvn.Revision( opt_revision_kind.head ) if the url_or_path is a URL otherwise to pysvn.Revision( opt_revision_kind.working ).
prop_list = \ proplist( url_or_path, revision=pysvn.Revision(), recurse=False )
Returns a list of tuples (path, prop_dict). The prop_dict contains the prop_names and their values if set on the path.
The src_revision defaults to pysvn.Revision( opt_revision_kind.head ) if the url_or_path is a URL otherwise to pysvn.Revision( opt_revision_kind.working ).
rev = \ propset( prop_name, prop_value, url_or_path, revision=pysvn.Revision(), recurse=False )
set the property prop_name to prop_value in path
The src_revision defaults to pysvn.Revision( opt_revision_kind.head ) if the url_or_path is a URL otherwise to pysvn.Revision( opt_revision_kind.working ).
relocate( from_url, to_url, path, recurse=True)
relocate the working copy from from_url to to_url of path
remove( url_or_path_list, force=False )
If url_or_path is a path, each item is scheduled for deletion upon the next commit. Files, and directories that have not been committed, are immediately removed from the working copy. The command will not remove paths that are, or contain, unversioned or modified items; set force=True to override this behaviour.
If url_or_path is a URL, the items are deleted from the repository via an immediate commit.
resolved( path, recurse=True )
Mark the conflicted file at path as resolved.
revert( path, recurse=False ) revert( [path,path], recurse=False )
Discard any changes in the working copy at path. Set recurse to True to recursively revert a directory's children.
pysvn.Client.revpropdelrev = \ revpropdel( prop_name, url, revision=pysvn.Revision( opt_revision_kind.head ), force=False )
Delete the revision property prop_name from url
rev_prop = \ revpropget( prop_name, url, revision=pysvn.Revision( opt_revision_kind.head ) )
Returns a tuple (rev, prop_val) where the prop_val contains the revision property value
rev_prop_dict = \ revproplist( url, revision=pysvn.Revision( opt_revision_kind.head ) )
Returns a tuple (revision, prop_dict) where the prop_dict contains the revision properies and their values
rev = \ revpropset( prop_name, prop_value, url, revision=pysvn.Revision( opt_revision_kind.head ), force=False )
set the revision property prop_name to prop_value in path. The revision updated is returned.
set_auth_cache( enable )
When enable is True subversion will remember authentication credentials in the configuration directory.
set_auto_props( enable )
When enabled subversion will automatically set properties when adding files otherwise when disabled will not.
status_list = \ status( path, recurse=False, get_all=False, update=False, no_ignore=False )
If path is a directory status is returned for all files in the directory path in status_list. If path is a single file status is returned for that single file in status_list.
The status_list is list of status objects.
switch( path, url, recurse=True, revision=pysvn.Revision( opt_revision_kind.head ) )
Update the working copy to a different URL.
unlock( url_or_path, force=False )
unlock the url_or_path. Set force to True to unlock any lock held by another user.
Note: The unlock command is only available with svn 1.2.0 or later
revision = \ update( path, recurse=True, revision=pysvn.Revision( opt_revision_kind.head ) )
Update the file in the working copy at path to the specified revision. Set recurse to True to recursively update a directory's children.
update returns a pysvn.Revision containing the number of the revision the working copy was updated to.
This command is typically used to get the latest changes from the repository. Note that updating to an older revision does not change the current revision. To make the current version identical to an older revision, use a merge followed by a commit.
Interface summary:
transaction = pysvn.Transaction() transaction = pysvn.Transaction( repos_path, transaction_name )
The Transaction object allows you to implement hook code for the SVN repository. The pre-commit and pre-revprop-change hooks are the only hooks that are currently appropiate in SVN. See the SVN documentation for details on hook scripts.
A Transaction object can only be used on one thread at a time. If two threads attempt to call methods of Transaction at the same time one of the threads will get a pysvn.TransactionError exception with the value 'transaction in use on another thread'.
cat | changed | ||
propdel | propget | proplist | propset |
revpropdel | revpropget | revproplist | revpropset |
file_text = \ cat( path )
Return the contents of path as a string, file_text.
file_text = \ changed()
Return a dict of all changes in the transaction. The keys in the dict are the path names and the values are tuples contraining action, kind, text_mod, prop_mod.
propdel( prop_name, path )
Delete the property prop_name from path in the transaction.
prop_value = \ propget( prop_name, path )
Returns the prop_value as a string or None if the prop_name is not in the transaction.
prop_dict = \ proplist( path )
Returns a prop_dict. The prop_dict contains the prop_names and their values if set on the path in the transaction.
propset( prop_name, prop_value, path )
Set the property prop_name to prop_value in path in the transaction.
revpropdel( prop_name )
Delete the revision property prop_name in the transaction.
prop_val = \ revpropget( prop_name )
Returns the prop_val with the revision property value or None if not set in the transaction.
prop_dict = \ revproplist()
Returns a prop_dict where the prop_dict contains the revision properies and their values in the transaction.
rev = \ revpropset( prop_name, prop_value )
set the revision property prop_name to prop_value in path in the transaction. The revision updated is returned.
The Revision object has three member variables:
Interface summary:
import pysvn import time revhead = pysvn.Revision( pysvn.opt_revision_kind.head ) revdate = pysvn.Revision( pysvn.opt_revision_kind.date, time.time() ) revnum = pysvn.Revision( pysvn.opt_revision_kind.number, 4721 )
ClientError exception is raised when any of the subversion functions called by pysvn return an error.
The Client.exception_style variable controls the information stored in the ClientError object.
The arg property is set to a single string parameter containing the whole error message. '\n' is used to seperate message parts.
Use str() to get the string description of the exception raised by pysvn.
import pysvn client = pysvn.Client() client.exception_style = 0 try: client.update( '' ) except pysvn.ClientError, e: # convert to a string print str(e) # or access the string in arg directly print e.arg
The arg property is set to a tuple contain two values.
arg[0] is set to a string parameter containing the whole error message. '\n' is used to seperate message parts.
arg[1] is set to a list of tuples containing the message string and the error code. The error code values are defined by SVN and APR.
import pysvn client = pysvn.Client() client.exception_style = 1 try: client.update( '' ) except pysvn.ClientError, e: # print the whole message print e.arg[0] # or process the error list for message, code in e.arg[1]: print 'Code:',code,'Message:',message
Each status object has the following fields: