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=u'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=u'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.

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 = u''

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, stdout=-1, stderr=-2, 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=[u'/bin', u'/sbin', u'/usr/bin', u'/usr/sbin', u'/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