hi friends,
attached is a patched version of the versioned extension and it's
companion test_, enhanced to:
1. allow the user to specify the names of the columns for 'version'
and 'timestamp' (but with the current defaults), in a named parameter
column_field_names to acts_as_versioned().
2. won't attempt to add the columns if they already exist. thus, the
user may manually define these fields, with freedom of flags as
relationships etc.
TODO: assert the column types of eventually existing fields will be
compatible with the extension: integer for version and DateTime for
the timestamp. i just didn't know how to check that, so i leave that
to a more skilled friend.
the test passes ok, with and without any of the columns defined manually.
best regards,
alex
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"SQLElixir" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/sqlelixir?hl=en
-~----------~----~----~----~------~----~------~--~---
'''
A versioning plugin for Elixir.
Entities that are marked as versioned with the `acts_as_versioned` statement
will automatically have a history table created and a timestamp and version
column added to their tables. In addition, versioned entities are provided
with four new methods: revert, revert_to, compare_with and get_as_of, and one
new attribute: versions. Entities with compound primary keys are supported.
The `versions` attribute will contain a list of previous versions of the
instance, in increasing version number order.
The `get_as_of` method will retrieve a previous version of the instance "as of"
a specified datetime. If the current version is the most recent, it will be
returned.
The `revert` method will rollback the current instance to its previous version,
if possible. Once reverted, the current instance will be expired from the
session, and you will need to fetch it again to retrieve the now reverted
instance.
The `revert_to` method will rollback the current instance to the specified
version number, if possibe. Once reverted, the current instance will be expired
from the session, and you will need to fetch it again to retrieve the now
reverted instance.
The `compare_with` method will compare the instance with a previous version. A
dictionary will be returned with each field difference as an element in the
dictionary where the key is the field name and the value is a tuple of the
format (current_value, version_value). Version instances also have a
`compare_with` method so that two versions can be compared.
Also included in the module is a `after_revert` decorator that can be used to
decorate methods on the versioned entity that will be called following that
instance being reverted.
The acts_as_versioned statement also accepts an optional `ignore` argument
that consists of a list of strings, specifying names of fields. Changes in
those fields will not result in a version increment. In addition, you can
pass in an optional `check_concurrent` argument, which will use SQLAlchemy's
built-in optimistic concurrency mechanisms.
Note that relationships that are stored in mapping tables will not be included
as part of the versioning process, and will need to be handled manually. Only
values within the entity's main table will be versioned into the history table.
'''
from datetime import datetime
import inspect
from sqlalchemy import Table, Column, and_, desc
from sqlalchemy.orm import mapper, MapperExtension, EXT_CONTINUE, \
object_session
from elixir import Integer, DateTime
from elixir.statements import Statement
from elixir.properties import EntityBuilder
__all__ = ['acts_as_versioned', 'after_revert']
__doc_all__ = []
#
# utility functions
#
def get_entity_where(instance):
clauses = []
for column in instance.table.primary_key.columns:
instance_value = getattr(instance, column.name)
clauses.append(column==instance_value)
return and_(*clauses)
def get_history_where(instance):
clauses = []
history_columns = instance.__history_table__.primary_key.columns
for column in instance.table.primary_key.columns:
instance_value = getattr(instance, column.name)
history_column = getattr(history_columns, column.name)
clauses.append(history_column==instance_value)
return and_(*clauses)
#
# a mapper extension to track versions on insert, update, and delete
#
class VersionedMapperExtension(MapperExtension):
def before_insert(self, mapper, connection, instance):
setattr(instance, instance.__class__.__column_field_names__[0], 1)
setattr(instance, instance.__class__.__column_field_names__[1], datetime.now())
return EXT_CONTINUE
def before_update(self, mapper, connection, instance):
old_values = instance.table.select(get_entity_where(instance)) \
.execute().fetchone()
# SA might've flagged this for an update even though it didn't change.
# This occurs when a relation is updated, thus marking this instance
# for a save/update operation. We check here against the last version
# to ensure we really should save this version and update the version
# data.
ignored = instance.__class__.__ignored_fields__
for key in instance.table.c.keys():
if key in ignored:
continue
if getattr(instance, key) != old_values[key]:
# the instance was really updated, so we create a new version
dict_values = dict(old_values.items())
connection.execute(
instance.__class__.__history_table__.insert(), dict_values)
setattr(instance, instance.__class__.__column_field_names__[0],
getattr(instance, instance.__class__.__column_field_names__[0]) + 1)
setattr(instance, instance.__class__.__column_field_names__[1], datetime.now())
break
return EXT_CONTINUE
def before_delete(self, mapper, connection, instance):
connection.execute(instance.__history_table__.delete(
get_history_where(instance)
))
return EXT_CONTINUE
versioned_mapper_extension = VersionedMapperExtension()
#
# the acts_as_versioned statement
#
class VersionedEntityBuilder(EntityBuilder):
def __init__(self, entity, ignore=[], check_concurrent=False, column_field_names=None):
self.entity = entity
self.add_mapper_extension(versioned_mapper_extension)
#TODO: we should rather check that the version_id_col isn't set
# externally
self.check_concurrent = check_concurrent
# Changes in these fields will be ignored
if column_field_names in [None, []]:
column_field_names = ['version', 'timestamp']
entity.__column_field_names__ = column_field_names
ignore.extend(column_field_names)
entity.__ignored_fields__ = ignore
def create_non_pk_cols(self):
# add a version column to the entity, along with a timestamp
field_names = self.entity.__column_field_names__
if field_names[0] not in [col.name for col in self.entity._descriptor.columns]:
self.add_table_column(Column(field_names[0], Integer))
if field_names[1] not in [col.name for col in self.entity._descriptor.columns]:
self.add_table_column(Column(field_names[1], DateTime))
# add a concurrent_version column to the entity, if required
if self.check_concurrent:
self.entity._descriptor.version_id_col = 'concurrent_version'
# we copy columns from the main entity table, so we need it to exist first
def after_table(self):
entity = self.entity
# look for events
after_revert_events = []
for name, func in inspect.getmembers(entity, inspect.ismethod):
if getattr(func, '_elixir_after_revert', False):
after_revert_events.append(func)
# create a history table for the entity
#TODO: fail more noticeably in case there is a version col
columns = [
column.copy() for column in entity.table.c
if column.name not in entity.__column_field_names__
]
columns.append(Column(entity.__column_field_names__[0], Integer, primary_key=True))
table = Table(entity.table.name + '_history', entity.table.metadata,
*columns
)
entity.__history_table__ = table
# create an object that represents a version of this entity
class Version(object):
pass
# map the version class to the history table for this entity
Version.__name__ = entity.__name__ + 'Version'
Version.__versioned_entity__ = entity
mapper(Version, entity.__history_table__)
# attach utility methods and properties to the entity
def get_versions(self):
v = object_session(self).query(Version) \
.filter(get_history_where(self)) \
.order_by(getattr(Version, entity.__column_field_names__[0])) \
.all()
# history contains all the previous records.
# Add the current one to the list to get all the versions
v.append(self)
return v
def get_as_of(self, dt):
# if the passed in timestamp is older than our current version's
# time stamp, then the most recent version is our current version
if getattr(self, entity.__column_field_names__[1]) < dt:
return self
# otherwise, we need to look to the history table to get our
# older version
sess = object_session(self)
query = sess.query(Version) \
.filter(and_(get_history_where(self),
getattr(Version, entity.__column_field_names__[1]) <= dt)) \
.order_by(desc(getattr(Version, entity.__column_field_names__[1]))).limit(1)
return query.first()
def revert_to(self, to_version):
if isinstance(to_version, Version):
to_version = getattr(to_version, entity.__column_field_names__[0])
hist = entity.__history_table__
old_version = hist.select(and_(
get_history_where(self),
getattr(hist.c, entity.__column_field_names__[0]) == to_version
)).execute().fetchone()
entity.table.update(get_entity_where(self)).execute(
dict(old_version.items())
)
hist.delete(and_(get_history_where(self),
getattr(hist.c, entity.__column_field_names__[0]) >= to_version)).execute()
self.expire()
for event in after_revert_events:
event(self)
def revert(self):
assert getattr(self, entity.__column_field_names__[0]) > 1
self.revert_to(getattr(self, entity.__column_field_names__[0]) - 1)
def compare_with(self, version):
differences = {}
for column in self.table.c:
if column.name in (entity.__column_field_names__[0], 'concurrent_version'):
continue
this = getattr(self, column.name)
that = getattr(version, column.name)
if this != that:
differences[column.name] = (this, that)
return differences
entity.versions = property(get_versions)
entity.get_as_of = get_as_of
entity.revert_to = revert_to
entity.revert = revert
entity.compare_with = compare_with
Version.compare_with = compare_with
acts_as_versioned = Statement(VersionedEntityBuilder)
def after_revert(func):
"""
Decorator for watching for revert events.
"""
func._elixir_after_revert = True
return func
from elixir import *
from versioned import acts_as_versioned
from datetime import datetime, timedelta
import time
column_field_names=['version_no', 'timestamp_value']
nextOneValue = 0
def nextOne():
global nextOneValue
nextOneValue += 2
return nextOneValue
def setup():
global Director, Movie, Actor
class Director(Entity):
name = Field(String(60))
movies = OneToMany('Movie', inverse='director')
using_options(tablename='directors')
class Movie(Entity):
id = Field(Integer, primary_key=True)
title = Field(String(60), primary_key=True)
description = Field(String(512))
releasedate = Field(DateTime)
ignoreme = Field(Integer, default=0)
autoupd = Field(Integer, default=nextOne, onupdate=nextOne)
# version_no = Field(Integer)
timestamp_value = Field(DateTime)
director = ManyToOne('Director', inverse='movies')
actors = ManyToMany('Actor', inverse='movies',
tablename='movie_casting')
using_options(tablename='movies')
acts_as_versioned(ignore=['ignoreme', 'autoupd'], column_field_names=column_field_names)
class Actor(Entity):
name = Field(String(60))
movies = ManyToMany('Movie', inverse='actors',
tablename='movie_casting')
using_options(tablename='actors')
setup_all()
metadata.bind = 'sqlite:///'
def teardown():
cleanup_all()
class TestVersioning(object):
def setup(self):
create_all()
def teardown(self):
drop_all()
session.close()
def test_versioning(self):
gilliam = Director(name='Terry Gilliam')
monkeys = Movie(id=1, title='12 Monkeys',
description='draft description', director=gilliam)
bruce = Actor(name='Bruce Willis', movies=[monkeys])
session.commit(); session.clear()
time.sleep(1)
after_create = datetime.now()
time.sleep(1)
movie = Movie.get_by(title='12 Monkeys')
assert getattr(movie, column_field_names[0]) == 1
assert movie.title == '12 Monkeys'
assert movie.director.name == 'Terry Gilliam'
assert movie.autoupd == 2, movie.autoupd
movie.description = 'description two'
session.commit(); session.clear()
time.sleep(1)
after_update_one = datetime.now()
time.sleep(1)
movie = Movie.get_by(title='12 Monkeys')
movie.description = 'description three'
session.commit(); session.clear()
# Edit the ignored field, this shouldn't change the version
monkeys = Movie.get_by(title='12 Monkeys')
monkeys.ignoreme = 1
session.commit(); session.clear()
time.sleep(1)
after_update_two = datetime.now()
time.sleep(1)
movie = Movie.get_by(title='12 Monkeys')
assert movie.autoupd == 8, movie.autoupd
oldest_version = movie.get_as_of(after_create)
middle_version = movie.get_as_of(after_update_one)
latest_version = movie.get_as_of(after_update_two)
initial_timestamp = getattr(oldest_version, column_field_names[1])
assert getattr(oldest_version, column_field_names[0]) == 1
assert oldest_version.description == 'draft description'
assert oldest_version.ignoreme == 0
assert oldest_version.autoupd is not None
assert oldest_version.autoupd > 0
assert getattr(middle_version, column_field_names[0]) == 2
assert middle_version.description == 'description two'
assert middle_version.autoupd > oldest_version.autoupd
assert getattr(latest_version, column_field_names[0]) == 3, \
'version=%i' % getattr(latest_version, column_field_names[0])
assert latest_version.description == 'description three'
assert latest_version.ignoreme == 1
assert latest_version.autoupd > middle_version.autoupd
differences = latest_version.compare_with(oldest_version)
assert differences['description'] == \
('description three', 'draft description')
assert len(movie.versions) == 3
assert movie.versions[0] == oldest_version
assert movie.versions[1] == middle_version
assert [getattr(v, column_field_names[0]) for v in movie.versions] == [1, 2, 3]
movie.description = 'description four'
movie.revert_to(2)
session.commit(); session.clear()
movie = Movie.get_by(title='12 Monkeys')
assert getattr(movie, column_field_names[0]) == 2, "version=%i, should be 2" % getattr(movie, column_field_names[0])
assert movie.description == 'description two', movie.description
movie.description = "description 3"
session.commit(); session.clear()
movie = Movie.get_by(title='12 Monkeys')
movie.description = "description 4"
session.commit(); session.clear()
movie = Movie.get_by(title='12 Monkeys')
assert getattr(movie, column_field_names[0]) == 4
movie.revert_to(movie.versions[-2])
movie.description = "description 5"
session.commit(); session.clear()
movie = Movie.get_by(title='12 Monkeys')
assert getattr(movie, column_field_names[0]) == 4
assert movie.versions[-2].description == "description 3"
