`trac.versioncontrol.api` – Trac Version Control APIs¶

This module implements an abstraction layer over different kind of version control systems and the mechanism to access several heterogeneous repositories under a single “virtual” hierarchy.

This abstraction was derived from the original model built around the Subversion system (versioned tree, changesets). It gradually became more general, now aiming at supporting distributed version control systems (DVCS).

Interfaces¶

class trac.versioncontrol.api.IRepositoryConnector¶

Bases: trac.core.Interface

Provide support for a specific version control system.

get_repository(repos_type, repos_dir, params)¶: Return a Repository instance for the given repository type and dir.

get_supported_types()¶

Return the types of version control systems that are supported.

Yields (repotype, priority) pairs, where repotype is used to match against the repository’s type attribute.

If multiple provider match a given type, the priority is used to choose between them (highest number is highest priority).

If the priority returned is negative, this indicates that the connector for the given repotype indeed exists but can’t be used for some reason. The error property can then be used to store an error message or exception relevant to the problem detected.

class trac.versioncontrol.api.IRepositoryProvider¶

Bases: trac.core.Interface

Provide known named instances of Repository.

get_repositories()¶

Generate repository information for known repositories.

Repository information is a key,value pair, where the value is a dictionary which must contain at the very least either of the following entries:

'dir': the repository directory which can be used by the

connector to create a Repository instance. This defines a “real” repository.

'alias': the name of another repository. This defines an

alias to another (real) repository.

Optional entries:

'type': the type of the repository (if not given, the

default repository type will be used).

'description': a description of the repository (can

contain WikiFormatting).

'hidden': if set to 'true', the repository is hidden

from the repository index (default: 'false').

'sync_per_request': if set to 'true', the repository will be

synchronized on every request (default: 'false').

'url': the base URL for checking out the repository.

class trac.versioncontrol.api.IRepositoryChangeListener¶

Bases: trac.core.Interface

Listen for changes in repositories.

changeset_added(repos, changeset)¶: Called after a changeset has been added to a repository.

changeset_modified(repos, changeset, old_changeset)¶

Called after a changeset has been modified in a repository.

The old_changeset argument contains the metadata of the changeset prior to the modification. It is None if the old metadata cannot be retrieved.

Components¶

class trac.versioncontrol.api.RepositoryManager¶

Bases: trac.core.Component

Version control system manager.

change_listeners¶: List of components that implement IRepositoryChangeListener

connectors¶: List of components that implement IRepositoryConnector

default_repository_type¶

Default repository connector type.

This is used as the default repository type for repositories defined in the [TracIni#repositories-section repositories] section or using the “Repositories” admin panel.

get_all_repositories()¶: Return a dictionary of repository information, indexed by name.

get_default_repository(context)¶

Recover the appropriate repository from the current context.

Lookup the closest source or changeset resource in the context hierarchy and return the name of its associated repository.

get_real_repositories()¶: Return a sorted list of all real repositories (i.e. excluding aliases).

get_repositories()¶

Retrieve repositories specified in TracIni.

The [repositories] section can be used to specify a list of repositories.

get_repositories_by_dir(directory)¶

Retrieve the repositories based on the given directory.

Parameters:	directory – the key for identifying the repositories.
Returns:	list of `Repository` instances.

get_repository(reponame)¶

Retrieve the appropriate Repository for the given repository name.

Parameters:	reponame – the key for specifying the repository. If no name is given, take the default repository.
Returns:	if no corresponding repository was defined, simply return `None`.
Raises:	InvalidConnector – if the repository connector cannot be opened. InvalidRepository – if the repository cannot be opened.

get_repository_by_path(path)¶

Retrieve a matching Repository for the given path.

Parameters:	path – the eventually scoped repository-scoped path
Returns:	a `(reponame, repos, path)` triple, where `path` is the remaining part of `path` once the `reponame` has been truncated, if needed.

get_repository_id(reponame)¶

Return a unique id for the given repository name.

This will create and save a new id if none is found.

Note: this should probably be renamed as we’re dealing: exclusively with db repository ids here.

get_supported_types()¶: Return the list of supported repository types.

notify(event, reponame, revs)¶

Notify repositories and change listeners about repository events.

The supported events are the names of the methods defined in the IRepositoryChangeListener interface.

providers¶: List of components that implement IRepositoryProvider

read_file_by_path(path)¶

Read the file specified by path

Parameters:	path – the repository-scoped path. The repository revision may specified by appending `@` followed by the revision, otherwise the HEAD revision is assumed.
Returns:	the file content as a unicode string. `None` is returned if the file is not found.
Since:	1.2.2

reload_repositories()¶: Reload the repositories from the providers.

repositories_section¶

One of the methods for registering repositories is to populate the [repositories] section of trac.ini.

This is especially suited for setting up aliases, using a [TracIni#GlobalConfiguration shared configuration], or specifying repositories at the time of environment creation.

See [TracRepositoryAdmin#ReposTracIni TracRepositoryAdmin] for details on the format of this section, and look elsewhere on the page for information on other repository providers.

shutdown(tid=None)¶: Free Repository instances bound to a given thread identifier

class trac.versioncontrol.api.DbRepositoryProvider¶

Bases: trac.core.Component

Component providing repositories registered in the DB.

add_alias(reponame, target)¶: Create an alias repository.

add_repository(reponame, dir, type_=None)¶: Add a repository.

get_repositories()¶: Retrieve repositories specified in the repository DB table.

modify_repository(reponame, changes)¶: Modify attributes of a repository.

remove_repository(reponame)¶: Remove a repository.

Exceptions¶

exception trac.versioncontrol.api.InvalidConnector(message, title=None, show_traceback=False)¶

Bases: trac.core.TracError

Exception raised when a repository connector is invalid.

If message is an Element object, everything up to the first <p> will be displayed in the red box, and everything after will be displayed below the red box. If title is given, it will be displayed as the large header above the error message.

exception trac.versioncontrol.api.InvalidRepository(message, title=None, show_traceback=False)¶

Bases: trac.core.TracError

Exception raised when a repository is invalid.

If message is an Element object, everything up to the first <p> will be displayed in the red box, and everything after will be displayed below the red box. If title is given, it will be displayed as the large header above the error message.

Subclasses of ResourceNotFound.

exception trac.versioncontrol.api.NoSuchChangeset(rev)¶: Bases: trac.resource.ResourceNotFound

exception trac.versioncontrol.api.NoSuchNode(path, rev, msg=None)¶: Bases: trac.resource.ResourceNotFound

Abstract classes¶

class trac.versioncontrol.api.Repository(name, params, log)¶

Bases: object

Base class for a repository provided by a version control system.

Initialize a repository.

Parameters:	name – a unique name identifying the repository, usually a type-specific prefix followed by the path to the repository. params – a `dict` of parameters for the repository. Contains the name of the repository under the key “name” and the surrogate key that identifies the repository in the database under the key “id”. log – a logger instance.
Raises:	InvalidRepository – if the repository cannot be opened.

can_view(perm)¶: Return True if view permission is granted on the repository.

clear(youngest_rev=None)¶

Clear any data that may have been cached in instance properties.

youngest_rev can be specified as a way to force the value of the youngest_rev property (‘’will change in 0.12’‘).

close()¶: Close the connection to the repository.

display_rev(rev)¶

Return a string representation of a revision in the repos for displaying to the user.

This can be a shortened revision string, e.g. for repositories using long hashes.

Raises:	NoSuchChangeset – If the given `rev` isn’t found.
Since 1.2:	Always returns a string or `None`.

get_base()¶

Return the name of the base repository for this repository.

This function returns the name of the base repository to which scoped repositories belong. For non-scoped repositories, it returns the repository name.

get_changes(old_path, old_rev, new_path, new_rev, ignore_ancestry=1)¶

Generates changes corresponding to generalized diffs.

Generator that yields change tuples (old_node, new_node, kind, change) for each node change between the two arbitrary (path,rev) pairs.

The old_node is assumed to be None when the change is an ADD, the new_node is assumed to be None when the change is a DELETE.

get_changeset(rev)¶: Retrieve a Changeset corresponding to the given revision rev.

get_changeset_uid(rev)¶

Return a globally unique identifier for the ‘’rev’’ changeset.

Two changesets from different repositories can sometimes refer to the ‘’very same’’ changeset (e.g. the repositories are clones).

get_changesets(start, stop)¶: Generate Changeset belonging to the given time period (start, stop).

get_node(path, rev=None)¶

Retrieve a Node from the repository at the given path.

A Node represents a directory or a file at a given revision in the repository. If the rev parameter is specified, the Node corresponding to that revision is returned, otherwise the Node corresponding to the youngest revision is returned.

get_oldest_rev()¶: Return the oldest revision stored in the repository.

get_path_history(path, rev=None, limit=None)¶

Retrieve all the revisions containing this path.

If given, rev is used as a starting point (i.e. no revision ‘’newer’’ than rev should be returned). The result format should be the same as the one of Node.get_history()

get_path_url(path, rev)¶

Return the repository URL for the given path and revision.

The returned URL can be None, meaning that no URL has been specified for the repository, an absolute URL, or a scheme-relative URL starting with //, in which case the scheme of the request should be prepended.

get_quickjump_entries(rev)¶

Generate a list of interesting places in the repository.

rev might be used to restrict the list of available locations, but in general it’s best to produce all known locations.

The generated results must be of the form (category, name, path, rev).

get_youngest_rev()¶: Return the youngest revision in the repository.

has_node(path, rev=None)¶

Tell if there’s a node at the specified (path,rev) combination.

When rev is None, the latest revision is implied.

is_viewable(perm)¶: Return True if view permission is granted on the repository.

next_rev(rev, path='')¶

Return the revision immediately following the specified revision.

If path is given, filter out descendant revisions having no changes below path.

In presence of multiple children, this follows the first child.

normalize_path(path)¶: Return a canonical representation of path in the repos.

normalize_rev(rev)¶

Return a (unique) canonical representation of a revision.

It’s up to the backend to decide which string values of rev (usually provided by the user) should be accepted, and how they should be normalized. Some backends may for instance want to match against known tags or branch names.

In addition, if rev is None or ‘’, the youngest revision should be returned.

Raises:	NoSuchChangeset – If the given `rev` isn’t found.

parent_revs(rev)¶: Return a list of parents of the specified revision.

previous_rev(rev, path='')¶

Return the revision immediately preceding the specified revision.

If path is given, filter out ancestor revisions having no changes below path.

In presence of multiple parents, this follows the first parent.

rev_older_than(rev1, rev2)¶

Provides a total order over revisions.

Return True if rev1 is an ancestor of rev2.

short_rev(rev)¶

Return a compact string representation of a revision in the repos.

Raises:	NoSuchChangeset – If the given `rev` isn’t found.
Since 1.2:	Always returns a string or `None`.

sync(rev_callback=None, clean=False)¶

Perform a sync of the repository cache, if relevant.

If given, rev_callback must be a callable taking a rev parameter. The backend will call this function for each rev it decided to synchronize, once the synchronization changes are committed to the cache. When clean is True, the cache is cleaned first.

sync_changeset(rev)¶

Resync the repository cache for the given rev, if relevant.

Returns a “metadata-only” changeset containing the metadata prior to the resync, or None if the old values cannot be retrieved (typically when the repository is not cached).

class trac.versioncontrol.api.Node(repos, path, rev, kind)¶

Bases: object

Represents a directory or file in the repository at a given revision.

can_view(perm)¶: Return True if view permission is granted on the node.

get_annotations()¶

Provide detailed backward history for the content of this Node.

Retrieve an array of revisions, one rev for each line of content for that node. Only expected to work on (text) FILE nodes, of course.

get_content()¶

Return a stream for reading the content of the node.

This method will return None for directories. The returned object must support a read([len]) method.

get_content_length()¶

The length in bytes of the content.

Will be None for a directory.

get_content_type()¶

The MIME type corresponding to the content, if known.

Will be None for a directory.

get_entries()¶

Generator that yields the immediate child entries of a directory.

The entries are returned in no particular order. If the node is a file, this method returns None.

get_history(limit=None)¶

Provide backward history for this Node.

Generator that yields (path, rev, chg) tuples, one for each revision in which the node was changed. This generator will follow copies and moves of a node (if the underlying version control system supports that), which will be indicated by the first element of the tuple (i.e. the path) changing. Starts with an entry for the current revision.

Parameters:	limit – if given, yield at most `limit` results.

get_previous()¶

Return the change event corresponding to the previous revision.

This returns a (path, rev, chg) tuple.

get_processed_content(keyword_substitution=True, eol_hint=None)¶

Return a stream for reading the content of the node, with some standard processing applied.

Parameters:

keyword_substitution – if True, meta-data keywords present in the content like $Rev$ are substituted (which keyword are substituted and how they are substituted is backend specific)
eol_hint – which style of line ending is expected if None was explicitly specified for the file itself in the version control backend (for example in Subversion, if it was set to 'native'). It can be None, 'LF', 'CR' or 'CRLF'.

get_properties()¶

Returns the properties (meta-data) of the node, as a dictionary.

The set of properties depends on the version control system.

is_viewable(perm)¶: Return True if view permission is granted on the node.

class trac.versioncontrol.api.Changeset(repos, rev, message, author, date)¶

Bases: object

Represents a set of changes committed at once in a repository.

can_view(perm)¶: Return True if view permission is granted on the changeset.

get_bookmarks()¶: Yield bookmarks associated with this changeset.

New in version 1.1.5.

get_branches()¶: Yield branches to which this changeset belong. Each branch is given as a pair (name, head), where name is the branch name and head a flag set if the changeset is a head for this branch (i.e. if it has no children changeset).

get_changes()¶

Generator that produces a tuple for every change in the changeset.

The tuple will contain (path, kind, change, base_path, base_rev), where change can be one of Changeset.ADD, Changeset.COPY, Changeset.DELETE, Changeset.EDIT or Changeset.MOVE, and kind is one of Node.FILE or Node.DIRECTORY. The path is the targeted path for the change (which is the ‘’deleted’’ path for a DELETE change). The base_path and base_rev are the source path and rev for the action (None and -1 in the case of an ADD change).

get_properties()¶

Returns the properties (meta-data) of the node, as a dictionary.

The set of properties depends on the version control system.

Warning: this used to yield 4-elements tuple (besides name and text, there were wikiflag and htmlclass values). This is now replaced by the usage of IPropertyRenderer (see #1601).

get_tags()¶: Yield tags associated with this changeset.

New in version 1.0.

is_viewable(perm)¶: Return True if view permission is granted on the changeset.

class trac.versioncontrol.api.EmptyChangeset(repos, rev, message=None, author=None, date=None)¶

Bases: trac.versioncontrol.api.Changeset

Changeset that contains no changes. This is typically used when the changeset can’t be retrieved.

Helper Functions¶

trac.versioncontrol.api.is_default(reponame)¶: Check whether reponame is the default repository.

Table Of Contents

Previous topic

Next topic

This Page

`trac.versioncontrol.api` – Trac Version Control APIs¶

Interfaces¶

Components¶

Exceptions¶

Abstract classes¶

Helper Functions¶

trac.versioncontrol.api – Trac Version Control APIs¶

Interfaces¶

Components¶

Exceptions¶

Abstract classes¶

Helper Functions¶

`trac.versioncontrol.api` – Trac Version Control APIs¶