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.

See also trac.versioncontrol.api.IRepositoryConnector extension point

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.

get_repository(repos_dir, params)

Return a Repository instance for the given repository type and dir.

class trac.versioncontrol.api.IRepositoryProvider

Bases: trac.core.Interface

Provide known named instances of Repository.

See also trac.versioncontrol.api.IRepositoryProvider extension point

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.

See also trac.versioncontrol.api.IRepositoryChangeListener extension point

changeset_added(changeset)

Called after a changeset has been added to a repository.

changeset_modified(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.

connectors

List of components that implement IRepositoryConnector

providers

List of components that implement IRepositoryProvider

change_listeners

List of components that implement IRepositoryChangeListener

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.

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_repositories()

Retrieve repositories specified in TracIni.

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

get_supported_types()

Return the list of supported repository types.

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_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_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:
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_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_all_repositories()

Return a dictionary of repository information, indexed by name.

get_real_repositories()

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

reload_repositories()

Reload the repositories from the providers.

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.

shutdown(tid=None)

Free Repository instances bound to a given thread identifier

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
class trac.versioncontrol.api.DbRepositoryProvider

Bases: trac.core.Component

Component providing repositories registered in the DB.

get_repositories()

Retrieve repositories specified in the repository DB table.

add_repository(reponame, dir, type_=None)

Add a repository.

add_alias(reponame, target)

Create an alias repository.

remove_repository(reponame)

Remove a repository.

modify_repository(reponame, changes)

Modify attributes of 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 the message contains a p or div element it will be rendered directly. Use the message class on the p or div element to style as a red box. Otherwise, the message should be plain text or contain only inline elements and will be wrapped in a p element and rendered in a 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 the message contains a p or div element it will be rendered directly. Use the message class on the p or div element to style as a red box. Otherwise, the message should be plain text or contain only inline elements and will be wrapped in a p element and rendered in a 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.
close()

Close the connection to the repository.

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.

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’’).

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).

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_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_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).

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.

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_youngest_rev()

Return the youngest revision in the repository.

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.

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.

parent_revs(rev)

Return a list of parents of the specified revision.

rev_older_than(rev1, rev2)

Provides a total order over revisions.

Return True if rev1 is an ancestor of rev2.

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()

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.
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.
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_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.

is_viewable(perm)

Return True if view permission is granted on the repository.

can_view(perm)

Return True if view permission is granted on the repository.

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

Bases: object

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

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_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_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_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_properties()

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

The set of properties depends on the version control system.

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.

is_viewable(perm)

Return True if view permission is granted on the node.

can_view(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.

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_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_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_tags()

Yield tags associated with this changeset.

New in version 1.0.

get_bookmarks()

Yield bookmarks associated with this changeset.

New in version 1.1.5.

is_viewable(perm)

Return True if view permission is granted on the changeset.

can_view(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.

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).

Helper Functions

trac.versioncontrol.api.is_default(reponame)

Check whether reponame is the default repository.