vcs.backends

Implemented Backends

• vcs.backends.git
• vcs.backends.hg

Base Backend

vcs.backends.base

Base for all available scm backends

created_on:

Apr 8, 2010

copyright:

3. 2010-2011 by Marcin Kuzminski, Lukasz Balcerzak.

class vcs.backends.base.BaseChangeset

Each backend should implement it’s changeset representation.

Attributes

repository

repository object within which changeset exists

id

may be raw_id or i.e. for mercurial’s tip just tip

raw_id

raw changeset representation (i.e. full 40 length sha for git backend)

short_id

shortened (if apply) version of raw_id; it would be simple shortcut for raw_id[:12] for git/mercurial backends or same as raw_id for subversion

revision

revision number as integer

files

list of FileNode (Node with NodeKind.FILE) objects

dirs

list of DirNode (Node with NodeKind.DIR) objects

nodes

combined list of Node objects

author

author of the changeset, as unicode

message

message of the changeset, as unicode

parents

list of parent changesets

last

True if this is last changeset in repository, False otherwise; trying to access this attribute while there is no changesets would raise EmptyRepositoryError

added

Returns list of added FileNode objects.

as_dict()

Returns dictionary with changeset’s attributes and their values.

author

Returns Author for given commit

author_email

Returns Author email address for given commit

author_name

Returns Author name for given commit

changed

Returns list of modified FileNode objects.

children

Returns list of children changesets.

committer

Returns Committer for given commit

committer_email

Returns Author email address for given commit

committer_name

Returns Author name for given commit

fill_archive(stream=None, kind='tgz', prefix=None)

Fills up given stream.

Parameters:

• stream – file like object.
• kind – one of following: zip, tar, tgz or tbz2. Default: tgz.
• prefix –

  name of root directory in archive. Default is repository name and changeset’s raw_id joined with dash.

  repo-tip.<kind>

get_chunked_archive(**kwargs)

Returns iterable archive. Tiny wrapper around fill_archive method.

Parameters:chunk_size – extra parameter which controls size of returned chunks. Default:8k.

get_file_changeset(path)

Returns last commit of the file at the given path.

get_file_content(path)

Returns content of the file at the given path.

get_file_history(path)

Returns history of file as reversed list of Changeset objects for which file at given path has been modified.

get_file_mode(path)

Returns stat mode of the file at the given path.

get_file_size(path)

Returns size of the file at the given path.

get_filenodes_generator()

Returns generator that yields all file nodes.

get_node(path)

Returns Node object from the given path.

Raises NodeDoesNotExistError:  if there is no node at the given path

get_nodes(path)

Returns combined DirNode and FileNode objects list representing state of changeset at the given path.

Raises ChangesetError:  if node at the given path is not instance of DirNode

id

Returns string identifying this changeset.

next(branch=None)

Returns next changeset from current, if branch is gives it will return next changeset belonging to this branch

Parameters:branch – show changesets within the given named branch

parents

Returns list of parents changesets.

prev(branch=None)

Returns previous changeset from current, if branch is gives it will return previous changeset belonging to this branch

Parameters:branch – show changesets within the given named branch

raw_id

Returns raw string identifying this changeset.

removed

Returns list of removed FileNode objects.

revision

Returns integer identifying this changeset.

root

Returns RootNode object for this changeset.

short_id

Returns shortened version of raw_id attribute, as string, identifying this changeset, useful for web representation.

size

Returns total number of bytes from contents of all filenodes.

walk(topurl='')

Similar to os.walk method. Insted of filesystem it walks through changeset starting at given topurl. Returns generator of tuples (topnode, dirnodes, filenodes).

class vcs.backends.base.BaseInMemoryChangeset(repository)

Represents differences between repository’s state (most recent head) and changes made in place.

Attributes

repository

repository object for this in-memory-changeset

added

list of FileNode objects marked as added

changed

list of FileNode objects marked as changed

removed

list of FileNode or RemovedFileNode objects marked to be removed

parents

list of Changeset representing parents of in-memory changeset. Should always be 2-element sequence.

add(*filenodes)

Marks given FileNode objects as to be committed.

Raises:

• NodeAlreadyExistsError – if node with same path exists at latest changeset
• NodeAlreadyAddedError – if node with same path is already marked as added

change(*filenodes)

Marks given FileNode objects to be changed in next commit.

Raises:

• EmptyRepositoryError – if there are no changesets yet
• NodeAlreadyExistsError – if node with same path is already marked to be changed
• NodeAlreadyRemovedError – if node with same path is already marked to be removed
• NodeDoesNotExistError – if node doesn’t exist in latest changeset
• NodeNotChangedError – if node hasn’t really be changed

check_integrity(parents=None)

Checks in-memory changeset’s integrity. Also, sets parents if not already set.

Raises CommitError:  if any error occurs (i.e. NodeDoesNotExistError).

commit(message, author, parents=None, branch=None, date=None, **kwargs)

Performs in-memory commit (doesn’t check workdir in any way) and returns newly created Changeset. Updates repository’s revisions.

Note

While overriding this method each backend’s should call self.check_integrity(parents) in the first place.

Parameters:

• message – message of the commit
• author – full username, i.e. “Joe Doe <joe.doe@example.com>”
• parents – single parent or sequence of parents from which commit would be derieved
• date – datetime.datetime instance. Defaults to datetime.datetime.now().
• branch – branch name, as string. If none given, default backend’s branch would be used.

Raises CommitError:  

if any error occurs while committing

get_ipaths()

Returns generator of paths from nodes marked as added, changed or removed.

get_paths()

Returns list of paths from nodes marked as added, changed or removed.

remove(*filenodes)

Marks given FileNode (or RemovedFileNode) objects to be removed in next commit.

Raises:

• NodeAlreadyRemovedError – if node has been already marked to be removed
• NodeAlreadyChangedError – if node has been already marked to be changed

reset()

Resets this instance to initial state (cleans added, changed and removed lists).

class vcs.backends.base.BaseRepository(repo_path, create=False, **kwargs)

Base Repository for final backends

Attributes

DEFAULT_BRANCH_NAME

name of default branch (i.e. “trunk” for svn, “master” for git etc.

scm

alias of scm, i.e. git or hg

repo

object from external api

revisions

list of all available revisions’ ids, in ascending order

changesets

storage dict caching returned changesets

path

absolute path to the repository

branches

branches as list of changesets

tags

tags as list of changesets

Initializes repository. Raises RepositoryError if repository could not be find at the given repo_path or directory at repo_path exists and create is set to True.

Parameters:

• repo_path – local path of the repository
• create=False – if set to True, would try to craete repository.
• src_url=None – if set, should be proper url from which repository would be cloned; requires create parameter to be set to True - raises RepositoryError if src_url is set and create evaluates to False

add(filenode, **kwargs)

Commit api function that will add given FileNode into this repository.

Raises:

• NodeAlreadyExistsError – if there is a file with same path already in repository
• NodeAlreadyAddedError – if given node is already marked as added

commit(message, **kwargs)

Persists current changes made on this repository and returns newly created changeset.

Raises NothingChangedError:  if no changes has been made

get_changeset(revision=None)

Returns instance of Changeset class. If revision is None, most recent changeset is returned.

Raises EmptyRepositoryError:  if there are no revisions

get_changesets(start=None, end=None, start_date=None, end_date=None, branch_name=None, reverse=False)

Returns iterator of MercurialChangeset objects from start to end not inclusive This should behave just like a list, ie. end is not inclusive

Parameters:

• start – None or str
• end – None or str
• start_date –
• end_date –
• branch_name –
• reversed –

get_config_value(section, name, config_file=None)

Returns configuration value for a given [section] and name.

Parameters:

• section – Section we want to retrieve value from
• name – Name of configuration we want to retrieve
• config_file – A path to file which should be used to retrieve configuration from (might also be a list of file paths)

get_diff(rev1, rev2, path=None, ignore_whitespace=False, context=3)

Returns (git like) diff, as plain text. Shows changes introduced by rev2 since rev1.

Parameters:

• rev1 – Entry point from which diff is shown. Can be self.EMPTY_CHANGESET - in this case, patch showing all the changes since empty state of the repository until rev2
• rev2 – Until which revision changes should be shown.
• ignore_whitespace – If set to True, would not show whitespace changes. Defaults to False.
• context – How many lines before/after changed lines should be shown. Defaults to 3.

get_state()

Returns dictionary with added, changed and removed lists containing FileNode objects.

get_user_email(config_file=None)

Returns user’s email from global configuration file.

Parameters:config_file – A path to file which should be used to retrieve configuration from (might also be a list of file paths)

get_user_name(config_file=None)

Returns user’s name from global configuration file.

Parameters:config_file – A path to file which should be used to retrieve configuration from (might also be a list of file paths)

in_memory_changeset

Returns InMemoryChangeset object for this repository.

is_valid()

Validates repository.

remove(filenode, **kwargs)

Commit api function that will remove given FileNode into this repository.

Raises:

• EmptyRepositoryError – if there are no changesets yet
• NodeDoesNotExistError – if there is no file with given path

remove_tag(name, user, message=None, date=None)

Removes tag with the given name.

Parameters:

• name – name of the tag to be removed
• user – full username, i.e.: “Joe Doe <joe.doe@example.com>”
• message – message of the tag’s removal commit
• date – date of tag’s removal commit

Raises TagDoesNotExistError:  

if tag with given name does not exists

size

Returns combined size in bytes for all repository files

tag(name, user, revision=None, message=None, date=None, **opts)

Creates and returns a tag for the given revision.

Parameters:

• name – name for new tag
• user – full username, i.e.: “Joe Doe <joe.doe@example.com>”
• revision – changeset id for which new tag would be created
• message – message of the tag’s commit
• date – date of tag’s commit

Raises TagAlreadyExistError:  

if tag with same name already exists

workdir

Returns Workdir instance for this repository.

class vcs.backends.base.BaseWorkdir(repository)

Working directory representation of single repository.

Attribute :repository: repository object of working directory

checkout_branch(branch=None)

Checks out branch or the backend’s default branch.

Raises BranchDoesNotExistError if the branch does not exist.

commit(message, **kwargs)

Commits local (from working directory) changes and returns newly created Changeset. Updates repository’s revisions list.

Raises CommitError:  if any error occurs while committing

get_added()

Returns list of FileNode objects marked as new in working directory.

get_branch()

Returns name of current branch.

get_changed()

Returns list of FileNode objects changed in working directory.

get_changeset()

Returns current changeset.

get_removed()

Returns list of RemovedFileNode objects marked as removed in working directory.

get_status()

Returns dict with added, changed, removed and untracked lists.

get_untracked()

Returns list of FileNode objects which are present within working directory however are not tracked by repository.

update(revision=None)

Fetches content of the given revision and populates it within working directory.

class vcs.backends.base.EmptyChangeset(cs='0000000000000000000000000000000000000000', repo=None, requested_revision=None, alias=None, revision=-1, message='', author='', date=None)

An dummy empty changeset. It’s possible to pass hash when creating an EmptyChangeset

raw_id

Returns raw string identifying this changeset, useful for web representation.