sven 0.9

sven is a document-oriented programming library that helps you put content in a version-controlled document repository

It can be used with SVN or BZR backends.

The SVN backend requires pysvn which you will probably want to install system-wide[1].

The BZR backend requires bzrlib. Currently only bzr 2.0+ is supported.

Basic usage:

from sven.backend import SvnAccess
client = SvnAccess(my_local_checkout_dir)

client.write('path/to/a/file/to/write', "Lovely content to be versioning!")
client.write('path/to/another/file', "Aw shucks, I'll version this too..",
             msg="My commit message", mimetype='text/plain')

last_rev_int = client.last_changed_rev('path/to/another/file')

last_rev_int = last_rev_int - 1
from sven.exc import ResourceUnchanged
try:
    earlier_version = client.read('path/to/another/file', rev=last_rev_int)
except ResourceUnchanged, exc:
    last_rev_int = exc.last_change
    earlier_version = client.read('path/to/another/file', rev=last_rev_int)

changelog = client.log('path/to/another/file', rev=last_rev_int)

To use the BZR backend,

from sven.bzr import BzrAccess

The interface is the same.

Each .write writes the content to the path on the local filesystem’s checkout and then commits it to the repository. The workflow of one-write-per-commit is by design and is not likely to change soon; if you need a different workflow, you probably ought to just be using svn clients directly, anyway.

Currently sven does not help you set up a repository client or server. It assumes you’ve already got a repository and checkout (which may be the same thing, in the BZR case) set up.

The formats returned by some of its methods (.read, .log and .ls) are totally ad-hoc right now and strange; they’ll probably be formalized sooner or later.

For more detailed usage documentation please see ./sven/doctest.txt (which can be run as a test suite by python sven/backend.py) and ./sven/bzr.txt (which can be run as a test suite by python sven/bzr.py)

[1] If you start to experience Segmentation faults while using sven, especially

during .write operations, your versions of svn and pysvn are likely incompatible (e.g. svn 1.5 with pysvn compiled against your earlier svn 1.4) If this happens, you should uninstall pysvn, then compile it from source. You might want to test for this upfront by running the test suite:

python sven/backend.py

Follow sven on github: <http://github.com/socialplanning/sven>

New in this version

• Added sven.exc.MissingRepository exception, to be thrown when accessing a nonexistent repo.

• Added kwarg check_repo to BzrAccess.__init__ with default False. If set to True, the constructor will check for the existence of a repository and throw a MissingRepository if it does not exist.

• Add author kwarg to BzrAccess.write with default None. It can be set to a string value which will be used as the “author” of the commit. (The system-level bzr whoami output will still be used for the separate “contributor” of the commit.) This is equivalent to the command-line bzr commit –author.

• Add timestamp kwarg to BzrAccess.write with default None. It can be set to a numerical timestamp, which will override the current system time in the commit. This is equivalent to the command-line bzr commit –timestamp.

• Manually strip all “r” characters from the commit message; bzr seems to break if any are present.

History

0.8.1 (2010-11-10)

• Make version numbers sane for bzr backend (one commit per write, regardless of how many intermediate directories were created)

0.8 (2010-08-26)

• Don’t require python svn libs installed when importing sven

• Tweaks for Python 2.4 compatibility

• Add support for writing revprops

0.7.2 (2010-01-26)

• Fix bug in SVN backend’s ‘mimetype’ getter.

0.7.1 (2010-01-26)

• Update SVN backend to talk about ‘mimetype’ instead of ‘kind’.

0.7 (2010-01-26)

• Added bazaar backend and tests.

• Removed experimental mercurial backend. I only need “something faster than subversion” and Bazaar’s worldview fits my brain better, so I doubt I’ll be maintaining the mercurial backend. If you’re using it, please complain loudly, because I didn’t know that you were using it.

• client.kind(uri) now takes an optional integer rev parameter like everything else.

• The strange dictionary returned by .read() now uses keys named ‘body’ and ‘mimetype’ instead of ‘body’ and ‘kind’.

• Refactored path normalization in SVN backend classes and added optional path_fixer callable argument to constructor.

  If provided, path_fixer should expect to be called with a string URI as the only argument. It should return a string URI. It can be used to define filesystem layout policies, like “always store files prefixed under a date hierarchy” or “add a file extension.”

  I’m probably overabstracting too early, though, so I won’t be surprised if I scrap this idea.

• When writing contents to a file, Sven used to append a newline to the contents whether or not the contents already ended with a newline. Now, sven will only append a newline if the content doesn’t already end in a newline.

• Implemented custom resource properties for bazaar backend, because it doesn’t have any concept like svn propget/propset.

  Resource properties are implemented as independently versioned files. File and directory properties live in separate locations, because that seemed easier and more logical somehow.

  For a file ‘/foo/bar/baz.txt’ its ‘mimetype’ property lives at ‘/.sven-meta/.mimetype/foo/bar/baz.txt’ and its ‘fleem’ property lives at ‘/.sven-meta/.fleem/foo/bar/baz.txt’.

  For a directory ‘/foo/bar/’ its ‘mimetype’ property lives at ‘/foo/bar/.sven-meta/.mimetype’ and its ‘fleem’ property lives at ‘/foo/bar/.sven-meta/.fleem’.

  Note that for normal files read and written directly by the user, sven’s default behavior appends a newline to the end of the file if there is none. For these metadata files, sven does not append a newline to the end of the file.

0.6 (2009-11-24)

• SvnBackend.__init__ no longer takes a ‘svnuri’ argument to the remote repository as its first positional argument; it’s not used anywhere. This is a backwards-incompatible change.

• The strange ad-hoc JSONish object returned by SvnAccess.ls had an extra / prefixed to the object’s ‘href’ erroneously; now fixed.

• Experimental implementation of the Sven API for Mercurial backends now lives in sven.hg.HgAccess; it is documented in hg-doctest.txt and has a few small differences from the SvnAccess backend. It is highly incomplete (think of it as an alpha stage) and requires mercurial to be installed. Sven does not install mercurial, just like it doesn’t install pysvn.

0.5

The 0.5 release does not exist. Sven went straight to 0.6 after 0.4.1 with some backwards-incompatible changes.

0.4.1 (2009-08-10)

• Fixed several embarrassing typos in the 0.4 release

0.4 (2009-08-10)

• Added simple_backend.FSAccess class, which partially implements the SVNAccess API, but on a plain old filesystem. Needs tests and documentation, among other things (e.g. justification)

• Refactored SvnAccess to split out recently-added options for update_before/after_write into logically separate component

• SvnAccess.set_kind and .write now return the pysvn.Revision of the (last) commit instead of None

• Added SvnAccessEventEmitter class which executes a list of callback functions at the end of every successful .write and .set_kind action

  Callbacks should have the signature

  (uri, contents, msg, kind, (pre_rev, post_rev))

0.3.1 (2009-07-28)

• Fixed bug: SvnAccess.ls was returning its contents with absolute URIs, rather than URIs relative to the root of the repository.

0.3 (2009-07-25)

• Removed SvnAccess.update_after_write knob and instead set default value of True to the update_after_write argument to SvnAccess.write; callers can implement alternatives trivially by subclassing.

• Added update_before_write argument to .write with default value of True. Turn this off as well as update_after_write if you want to manage synchronicity in exchange for potentially significant performance improvements.

• Added default_commit_message argument to SvnAccess constructor. The default is “foom”.

• Throw exc.ResourceChanged exceptions when a file is found to be out of date during a write operation (which will only happen if update_before_write is unset by the caller) and revert local changes if this happens, to restore the checkout to an unconflicting state.

0.2 (2009-07-25)

• Now with doctests!

• SvnAccess.write now supports an optional update_after_write argument. If set to a True value, calls to .write will end with an svn up to resynchronize the checkout with the repository. Default is False.

• SvnAccess.__init__ now supports an optional update_after_write argument. If set to a True value, all calls to .write will end with an svn up even if .write is not sent a True update_after_write value. Default is True, so if you are concerned with performance and willing to maintain synchronicity on your own, you should explicitly set this to False.

• SvnAccess.__init__ no longer executes a silent os.chdir.

0.1.2 (2009-07-24)

First release.