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:
Return type:libvcs.svn.SubversionRepo, libvcs.git.GitRepo, or libvcs.hg.MercurialRepo.

Examples

>>> 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:
Return type:libvcs.svn.SubversionRepo, libvcs.git.GitRepo, or libvcs.hg.MercurialRepo.

Examples

>>> 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 :func:libvcs.shortcuts.create_repo and :func:libvcs.shortcuts.create_repo_from_pip_url are just wrappers around instantiated these classes.

See examples below of git, mercurial, and subversion.

Git

class libvcs.git.GitRepo(url, **kwargs)

Bases: libvcs.base.BaseRepo

static chomp_protocol(url)

Return clean VCS url from RFC-style url

Parameters:url (str) – PIP-style url
Returns:URL as VCS software would accept it
Return type:str
get_current_remote_name()

Retrieve name of the remote / upstream of currently checked out branch.

Returns:If upstream the same, returns branch_name. If upstream mismatches, returns remote_name/branch_name.
Return type:str
get_git_version()

Return current version of git binary

Returns:git version
Return type:str
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(name, **kwargs)

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

Parameters:name (str) – The remote name used to define the fetch and push URL
Returns:Remote name and url in tuple form
Return type:[GitRemote](libvcs.git.GitRemote)
remotes(flat=False)

Return remotes like git remote -v.

Parameters:flat (bool) – Return a dict of tuple instead of dict, default False.
Returns:dict of git upstream / remote URLs
Return type:dict
set_remote(name, url, overwrite=False)

Set remote with name and URL like git remote add.

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

Retrieve status of project in dict format.

Wraps git status --sb --porcelain=2. Does not include changed files, yet.

Returns:Status of current checked out repository
Return type:dict

Examples

>>> git_repo.status()
{
    "branch_oid": 'de6185fde0806e5c7754ca05676325a1ea4d6348',
    "branch_head": 'fix-current-remote-name',
    "branch_upstream": 'origin/fix-current-remote-name',
    "branch_ab": '+0 -0',
    "branch_ahead": '0',
    "branch_behind": '0'
}
class libvcs.git.GitRemote(name, fetch_url, push_url)

Bases: tuple

Structure containing git repo information.

Supports collections.namedtuple._asdict()

fetch_url

Alias for field number 1

name

Alias for field number 0

push_url

Alias for field number 2

libvcs.git.extract_status(value)

Returns git status -sb --porcelain=2 extracted to a dict

Returns:Dictionary of git repo’s status
Return type:dict

Mercurial

aka hg(1)

class libvcs.hg.MercurialRepo(url, **kwargs)

Bases: libvcs.base.BaseRepo

Subversion

aka svn(1)

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

Bases: libvcs.base.BaseRepo

get_revision(location=None)

Return 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 libvcs.base.BaseRepo.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 libvcs.base.BaseRepo.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 libvcs.base.BaseRepo.path of the repo.

Parameters:
  • cwd (str) – dir command is run from, defaults to libvcs.base.BaseRepo.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

Utility stuff

Utility functions for libvcs.

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
  • repo_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 or str, or single str, if shell=True) – the command to run
  • shell (boolean) – 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. Defaults to path.
  • log_in_real_time (boolean) – boolean indicating whether to read stdout from the subprocess in real time instead of when the process finishes.
  • check_returncode (bool) – Indicate whether a libvcs.exc.CommandError should be raised if return code is different from 0.
  • callback (callable) –

    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.
Returns:

Path to binary

Return type:

str