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
orlibvcs.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
orlibvcs.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
()¶ 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:
-
remotes_get
¶ Return remotes like git remote -v.
Return type: dict of tuples
-
static
-
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: Returns: combined stdout/stderr in a big string, newlines retained
Return type:
-
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.
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 aCommandError
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: