vcs.utils

This module provides some useful tools for vcs like annotate/diff html output. It also includes some internal helpers.

Public API

• Annotate utils
• Diffs utils
• Helpers

Private API

• Lazy attributes utils

Annotate utils

vcs.utils.annotate.annotate_highlight(filenode, annotate_from_changeset_func=None, order=None, headers=None, **options)

Returns html portion containing annotated table with 3 columns: line numbers, changeset information and pygmentized line of code.

Parameters:

• filenode – FileNode object
• annotate_from_changeset_func – function taking changeset and returning single annotate cell; needs break line at the end
• order – ordered sequence of ls (line numbers column), annotate (annotate column), code (code column); Default is ['ls', 'annotate', 'code']
• headers – dictionary with headers (keys are whats in order parameter)

Diffs utils

class vcs.utils.diffs.DiffProcessor(diff, differ='diff', format='udiff')

Give it a unified diff and it returns a list of the files that were mentioned in the diff together with a dict of meta information that can be used to render it in a HTML template.

Parameters:

• diff – a text in diff format or generator
• format – format of diff passed, udiff or gitdiff

as_html(table_class='code-difftable', line_class='line', new_lineno_class='lineno old', old_lineno_class='lineno new', code_class='code')

Return udiff as html table with customized css classes

copy_iterator()

make a fresh copy of generator, we should not iterate thru an original as it’s needed for repeating operations on this instance of DiffProcessor

prepare()

Prepare the passed udiff for HTML rendering. It’l return a list of dicts

raw_diff()

Returns raw string as udiff

stat()

Returns tuple of adde,and removed lines for this instance

vcs.utils.diffs.get_gitdiff(filenode_old, filenode_new, ignore_whitespace=True)

Returns git style diff between given filenode_old and filenode_new.

Parameters:ignore_whitespace – ignore whitespaces in diff

vcs.utils.diffs.get_udiff(filenode_old, filenode_new, show_whitespace=True)

Returns unified diff between given filenode_old and filenode_new.

Helpers

Utitlites aimed to help achieve mostly basic tasks.

vcs.utils.helpers.get_dict_for_attrs(obj, attrs)

Returns dictionary for each attribute from given obj.

vcs.utils.helpers.get_highlighted_code(name, code, type='terminal')

If pygments are available on the system then returned output is colored. Otherwise unchanged content is returned.

vcs.utils.helpers.get_repo_paths(path)

Returns path’s subdirectories which seems to be a repository.

vcs.utils.helpers.get_scm(path, search_up=False, explicit_alias=None)

Returns one of alias from ALIASES (in order of precedence same as shortcuts given in ALIASES) and top working dir path for the given argument. If no scm-specific directory is found or more than one scm is found at that directory, VCSError is raised.

Parameters:

• search_up – if set to True, this function would try to move up to parent directory every time no scm is recognized for the currently checked path. Default: False.
• explicit_alias – can be one of available backend aliases, when given it will return given explicit alias in repositories under more than one version control, if explicit_alias is different than found it will raise VCSError

vcs.utils.helpers.get_scms_for_path(path)

Returns all scm’s found at the given path. If no scm is recognized - empty list is returned.

Parameters:path – path to directory which should be checked. May be callable. Raises VCSError:  if given path is not a directory

vcs.utils.helpers.get_total_seconds(timedelta)

Backported for Python 2.5.

See http://docs.python.org/library/datetime.html.

vcs.utils.helpers.parse_changesets(text)

Returns dictionary with start, main and end ids.

Examples:

>>> parse_changesets('aaabbb')
{'start': None, 'main': 'aaabbb', 'end': None}
>>> parse_changesets('aaabbb..cccddd')
{'start': 'aaabbb', 'main': None, 'end': 'cccddd'}

vcs.utils.helpers.parse_datetime(text)

Parses given text and returns datetime.datetime instance or raises ValueError.

Parameters:text – string of desired date/datetime or something more verbose, like yesterday, 2weeks 3days, etc.

vcs.utils.helpers.run_command(cmd, *args)

Runs command on the system with given args.

Lazy attributes utils

vcs.utils.lazy.LazyProperty

Decorator for easier creation of property from potentially expensive to calculate attribute of the class.

Usage:

class Foo(object):
    @LazyProperty
    def bar(self):
        print 'Calculating self._bar'
        return 42

Taken from http://blog.pythonisito.com/2008/08/lazy-descriptors.html and used widely.

vcs.utils.lazy.ThreadLocalLazyProperty

Same as above but uses thread local dict for cache storage.