tracopt.versioncontrol.svn.svn_fs – Subversion backend for Trac

This module can be considered to be private. However, it can serve as an example implementation of a version control backend.

Speaking of Subversion, we use its svn.fs layer mainly, which means we need direct (read) access to the repository content.

Though there’s no documentation for the Python API per se, the doxygen documentation for the C libraries are usually enough. Another possible source of inspiration are the examples and the helper classes in the bindings themselves.

Note about Unicode

The Subversion bindings are not unicode-aware and they expect to receive UTF-8 encoded string parameters,

On the other hand, all paths manipulated by Trac are unicode objects.

Therefore:

• before being handed out to SVN, the Trac paths have to be encoded to UTF-8, using _to_svn()
• before being handed out to Trac, a SVN path has to be decoded from UTF-8, using _from_svn()

Whenever a value has to be stored as utf8, we explicitly mark the variable name with “_utf8”, in order to avoid any possible confusion.

Warning:

SubversionNode.get_content() returns an object from which one can read a stream of bytes. NO guarantees can be given about what that stream of bytes represents. It might be some text, encoded in some way or another. SVN properties might give some hints about the content, but they actually only reflect the beliefs of whomever set those properties...

class tracopt.versioncontrol.svn.svn_fs.Pool(parent_pool=None)

Bases: object

A Pythonic memory pool object

Create a new memory pool

assert_valid()

Assert that this memory_pool is still valid.

clear()

Clear embedded memory pool. Invalidate all subpools.

destroy()

Destroy embedded memory pool. If you do not destroy the memory pool manually, Python will destroy it automatically.

valid()

Check whether this memory pool and its parents are still valid

class tracopt.versioncontrol.svn.svn_fs.SubversionRepository(path, params, log)

Bases: trac.versioncontrol.api.Repository

Repository implementation based on the svn.fs API.

clear(youngest_rev=None)

Reset notion of youngest and oldest

close()

Dispose of low-level resources associated to this repository.

get_base()

Retrieve the base path corresponding to the Subversion repository itself.

This is the same as the path property minus the intra-repository scope, if one was specified.

get_changes(old_path, old_rev, new_path, new_rev, ignore_ancestry=0)

Determine differences between two arbitrary pairs of paths and revisions.

(wraps repos.svn_repos_dir_delta)

get_changeset(rev)

Produce a SubversionChangeset from given revision specification

get_changeset_uid(rev)

Build a value identifying the rev in this repository.

get_node(path, rev=None)

Produce a SubversionNode from given path and optionally revision specifications. No revision given means use the latest.

get_oldest_rev()

Gives an approximation of the oldest revision.

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

Retrieve creation and deletion events that happened on given path.

get_path_url(path, rev)

Retrieve the “native” URL from which this repository is reachable from Subversion clients.

get_quickjump_entries(rev)

Retrieve known branches, as (name, id) pairs.

Purposedly ignores rev and always takes the last revision.

get_youngest_rev()

Retrieve the latest revision in the repository.

(wraps fs.youngest_rev)

has_node(path, rev=None, pool=None)

Check if path exists at rev (or latest if unspecified)

next_rev(rev, path='', find_initial_rev=False)

Return revision immediately following rev, eventually below given path or globally.

normalize_path(path)

Take any path specification and produce a path suitable for the rest of the API

normalize_rev(rev)

Take any revision specification and produce a revision suitable for the rest of the API

previous_rev(rev, path='')

Return revision immediately preceeding rev, eventually below given path or globally.

rev_older_than(rev1, rev2)

Check relative order between two revision specifications.

class tracopt.versioncontrol.svn.svn_fs.SvnCachedRepository(env, repos, log)

Bases: trac.versioncontrol.cache.CachedRepository

Subversion-specific cached repository, zero-pads revision numbers in the cache tables.

Components

class tracopt.versioncontrol.svn.svn_fs.SubversionConnector

Bases: trac.core.Component

branches

Comma separated list of paths categorized as branches. If a path ends with ‘*’, then all the directory entries found below that path will be included. Example: /trunk, /branches/*, /projectAlpha/trunk, /sandbox/*

eol_style

End-of-Line character sequences when svn:eol-style property is native.

If native, substitute with the native EOL marker on the server. Otherwise, if LF, CRLF or CR, substitute with the specified EOL marker.

(‘’since 1.0.2’‘)

get_repository(type, dir, params)

Return a SubversionRepository.

The repository is wrapped in a CachedRepository, unless type is ‘direct-svnfs’.

tags

Comma separated list of paths categorized as tags.

If a path ends with ‘*’, then all the directory entries found below that path will be included. Example: /tags/*, /projectAlpha/tags/A-1.0, /projectAlpha/tags/A-v1.1

Concrete classes

class tracopt.versioncontrol.svn.svn_fs.SubversionRepository(path, params, log)

Bases: trac.versioncontrol.api.Repository

Repository implementation based on the svn.fs API.

clear(youngest_rev=None)

Reset notion of youngest and oldest

close()

Dispose of low-level resources associated to this repository.

get_base()

Retrieve the base path corresponding to the Subversion repository itself.

This is the same as the path property minus the intra-repository scope, if one was specified.

get_changes(old_path, old_rev, new_path, new_rev, ignore_ancestry=0)

Determine differences between two arbitrary pairs of paths and revisions.

(wraps repos.svn_repos_dir_delta)

get_changeset(rev)

Produce a SubversionChangeset from given revision specification

get_changeset_uid(rev)

Build a value identifying the rev in this repository.

get_node(path, rev=None)

Produce a SubversionNode from given path and optionally revision specifications. No revision given means use the latest.

get_oldest_rev()

Gives an approximation of the oldest revision.

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

Retrieve creation and deletion events that happened on given path.

get_path_url(path, rev)

Retrieve the “native” URL from which this repository is reachable from Subversion clients.

get_quickjump_entries(rev)

Retrieve known branches, as (name, id) pairs.

Purposedly ignores rev and always takes the last revision.

get_youngest_rev()

Retrieve the latest revision in the repository.

(wraps fs.youngest_rev)

has_node(path, rev=None, pool=None)

Check if path exists at rev (or latest if unspecified)

next_rev(rev, path='', find_initial_rev=False)

Return revision immediately following rev, eventually below given path or globally.

normalize_path(path)

Take any path specification and produce a path suitable for the rest of the API

normalize_rev(rev)

Take any revision specification and produce a revision suitable for the rest of the API

previous_rev(rev, path='')

Return revision immediately preceeding rev, eventually below given path or globally.

rev_older_than(rev1, rev2)

Check relative order between two revision specifications.

class tracopt.versioncontrol.svn.svn_fs.SubversionNode(path, rev, repos, pool=None, parent_root=None)

Bases: trac.versioncontrol.api.Node

get_annotations()

Return a list the last changed revision for each line. (wraps client.blame2)

get_branch_origin()

Return the revision in which the node’s path was created.

(wraps fs.revision_root_revision(fs.closest_copy))

get_content()

Retrieve raw content as a “read()”able object.

get_content_length()

Retrieve byte size of a file.

Return None for a folder. (wraps fs.file_length)

get_content_type()

Retrieve mime-type property of a file.

Return None for a folder. (wraps fs.revision_prop)

get_copy_ancestry()

Retrieve the list of (path,rev) copy ancestors of this node. Most recent ancestor first. Each ancestor (path, rev) corresponds to the path and revision of the source at the time the copy or move operation was performed.

get_entries()

Yield SubversionNode corresponding to entries in this directory.

(wraps fs.dir_entries)

get_history(limit=None)

Yield change events that happened on this path

get_last_modified()

Retrieve timestamp of last modification, in micro-seconds.

(wraps fs.revision_prop)

get_processed_content(keyword_substitution=True, eol_hint=None)

Retrieve processed content as a “read()”able object.

get_properties()

Return dict of node properties at current revision.

(wraps fs.node_proplist)

class tracopt.versioncontrol.svn.svn_fs.SubversionChangeset(repos, rev, scope, pool=None)

Bases: trac.versioncontrol.api.Changeset

get_changes()

Retrieve file changes for a given revision.

(wraps repos.svn_repos_replay)

get_properties()

Retrieve dict of Subversion properties for this revision (revprops)

Miscellaneous

class tracopt.versioncontrol.svn.svn_fs.Pool(parent_pool=None)

Bases: object

A Pythonic memory pool object

Create a new memory pool

assert_valid()

Assert that this memory_pool is still valid.

clear()

Clear embedded memory pool. Invalidate all subpools.

destroy()

Destroy embedded memory pool. If you do not destroy the memory pool manually, Python will destroy it automatically.

valid()

Check whether this memory pool and its parents are still valid

class tracopt.versioncontrol.svn.svn_fs.SvnCachedRepository(env, repos, log)

Bases: trac.versioncontrol.cache.CachedRepository

Subversion-specific cached repository, zero-pads revision numbers in the cache tables.