API Reference¶

Creating a repo object¶

Helper methods are available in libvcs.shortcuts which can return a repo object from a single entry-point.

libvcs.shortcuts.create_repo(url, vcs, **kwargs)¶

Return a object representation of a VCS repository.

Returns:	instance of a repository object
Return type:	`libvcs.svn.SubversionRepo`, `libvcs.git.GitRepo` or `libvcs.hg.MercurialRepo`.

Usage Example:

>>> from libvcs.shortcuts import create_repo

>>> r = create_repo(
...         url='https://www.github.com/you/myrepo',
...         vcs='git',
...         repo_dir='/tmp/myrepo')

>>> r.update_repo()
|myrepo| (git)  Repo directory for myrepo (git) does not exist @ \
    /tmp/myrepo
|myrepo| (git)  Cloning.
|myrepo| (git)  git clone https://www.github.com/tony/myrepo \
    /tmp/myrepo
Cloning into '/tmp/myrepo'...
Checking connectivity... done.
|myrepo| (git)  git fetch
|myrepo| (git)  git pull
Already up-to-date.

libvcs.shortcuts.create_repo_from_pip_url(pip_url, **kwargs)¶

Return a object representation of a VCS repository via pip-style url.

Returns:	instance of a repository object
Return type:	`libvcs.svn.SubversionRepo`, `libvcs.git.GitRepo` or `libvcs.hg.MercurialRepo`.

Usage Example:

>>> from libvcs.shortcuts import create_repo_from_pip_url

>>> r = create_repo_from_pip_url(
...         pip_url='git+https://www.github.com/you/myrepo',
...         repo_dir='/tmp/myrepo')

>>> r.update_repo()
|myrepo| (git)  Repo directory for myrepo (git) does not exist @ \
    /tmp/myrepo
|myrepo| (git)  Cloning.
|myrepo| (git)  git clone https://www.github.com/tony/myrepo \
    /tmp/myrepo
Cloning into '/tmp/myrepo'...
Checking connectivity... done.
|myrepo| (git)  git fetch
|myrepo| (git)  git pull
Already up-to-date.

Instantiating a repo by hand¶

Tools like libvcs.shortcuts.create_repo() and :func:`libvcs.shortcuts.create_repo_from_pip_url are just wrappers around instantiated these classes.

class libvcs.git.GitRepo(url, remotes=None, **kwargs)¶

Bases: libvcs.base.BaseRepo

static chomp_protocol(url)¶

Return clean VCS url from RFC-style url

Parameters:	url (str) – url
Return type:	str
Returns:	url as VCS software would accept it
Seealso:	#14

get_revision()¶: Return current revision. Initial repositories return ‘initial’.

classmethod get_url_and_revision_from_pip_url(pip_url)¶: Prefixes stub URLs like ‘user@hostname:user/repo.git’ with ‘ssh://’. That’s required because although they use SSH they sometimes doesn’t work with a ssh:// scheme (e.g. Github). But we need a scheme for parsing. Hence we remove it again afterwards and return it as a stub. The manpage for git-clone(1) refers to this as the “scp-like styntax”.

obtain()¶: Retrieve the repository, clone if doesn’t exist.

remote_get(remote='origin')¶

Get the fetch and push URL for a specified remote name.

Parameters:	remote (str) – the remote name used to define the fetch and push URL
Returns:	remote name and url in tuple form
Return type:	tuple

remote_set(url, name='origin')¶

Set remote with name and URL like git remote add.

Parameters:	url (str) – defines the remote URL name (str) – defines the remote name.

remotes_get¶

Return remotes like git remote -v.

Return type:	dict of tuples

class libvcs.hg.MercurialRepo(url, **kwargs)¶: Bases: libvcs.base.BaseRepo

class libvcs.svn.SubversionRepo(url, **kwargs)¶

Bases: libvcs.base.BaseRepo

get_revision(location=None)¶: Return the maximum revision for all files under a given location

get_revision_file(location)¶: Return revision for a file.

classmethod get_url_and_revision_from_pip_url(pip_url)¶: Return repo URL and revision by parsing url.

Adding your own VCS¶

Extending libvcs can be done through subclassing BaseRepo.

class libvcs.base.BaseRepo(url, repo_dir, progress_callback=None, *args, **kwargs)¶

Bases: libvcs.util.RepoLoggingAdapter, object

Base class for repositories.

Extends logging.LoggerAdapter.

bin_name = ''¶: vcs app name, e.g. ‘git’

check_destination(*args, **kwargs)¶: Assure destination path exists. If not, create directories.

classmethod get_url_and_revision_from_pip_url(pip_url)¶: Return repo URL and revision by parsing url.

log_in_real_time = None¶: log command output to buffer

run(cmd, cwd=None, check_returncode=True, log_in_real_time=None, *args, **kwargs)¶

Return combined stderr/stdout from a command.

This method will also prefix the VCS command bin_name. By default runs using the cwd path of the repo.

Parameters:	cwd (str) – dir command is run from, defaults `path`. check_returncode (`bool`) – Indicate whether a `CommandError` should be raised if return code is different from 0.
Returns:	combined stdout/stderr in a big string, newlines retained
Return type:	str

Logging¶

class libvcs.util.RepoLoggingAdapter(*args, **kwargs)¶

Bases: logging.LoggerAdapter

Adapter for adding Repo related content to logger.

Extends logging.LoggerAdapter’s functionality.

The standard library logging facility is pretty complex, so this warrants and explanation of what’s happening.

Any class that subclasses this will have its class attributes for:

bin_name -> repo_vcs

name -> repo_name

Added to a dictionary of context information in :py:meth:` logging.LoggerAdapter.process()` to be made use of when the user of this library wishes to use a custom logging.Formatter to output results.

process(msg, kwargs)¶: Add additional context information for loggers.

Utility stuff¶

Utility functions for libvcs.

libvcs.util¶

class libvcs.util.RepoLoggingAdapter(*args, **kwargs)

Adapter for adding Repo related content to logger.

Extends logging.LoggerAdapter’s functionality.

The standard library logging facility is pretty complex, so this warrants and explanation of what’s happening.

Any class that subclasses this will have its class attributes for:

bin_name -> repo_vcs

name -> repo_name

Added to a dictionary of context information in :py:meth:` logging.LoggerAdapter.process()` to be made use of when the user of this library wishes to use a custom logging.Formatter to output results.

process(msg, kwargs): Add additional context information for loggers.

libvcs.util.mkdir_p(path)¶

Make directories recursively.

Parameters:	path (str) – path to create

libvcs.util.run(cmd, shell=False, cwd=None, log_in_real_time=True, check_returncode=True, callback=None)¶

Run ‘cmd’ in a shell and return the combined contents of stdout and stderr (Blocking). Throws an exception if the command exits non-zero.

Parameters:

cmd – list of str (or single str, if shell==True) indicating the command to run
shell – boolean indicating whether we are using advanced shell features. Use only when absolutely necessary, since this allows a lot more freedom which could be exploited by malicious code. See the warning here: http://docs.python.org/library/subprocess.html#popen-constructor
cwd (str) – dir command is run from.
log_in_real_time – boolean indicating whether to read stdout from the subprocess in real time instead of when the process finishes.
check_returncode (bool) – Indicate whether a CommandError should be raised if return code is different from 0.
cwd – dir command is run from, defaults path.

callback (func) –

callback to return output as a command executes, accepts a function signature of (output, timestamp). Example usage:

def progress_cb(output, timestamp):
    sys.stdout.write(output)
    sys.stdout.flush()
run(['git', 'pull'], callback=progrses_cb)

libvcs.util.which(exe=None, default_paths=['/bin', '/sbin', '/usr/bin', '/usr/sbin', '/usr/local/bin'])¶

Return path of bin. Python clone of /usr/bin/which.

from salt.util - https://www.github.com/saltstack/salt - license apache

Parameters:	exe (str) – Application to search PATHs for. default_path (list) – Application to search PATHs for.
Return type:	str