Athanor is a set of utilities for SQLAlchemy.

Athanor provides simple conveinence functions for common patterns found in many applications. Tools should be selected as the situation calls for. SQLAlchemy is marvelous package; Athanor is not an attempt to eliminate SQLAlchemy.

See Also - http://en.wikipedia.org/wiki/Athanor

See examples.py

BaseModel is base class for SQLAlchemy mapped objects that provides a number of utilities to inspect, create, find, fetch and update objects/columns. It also provides “magic finders” that will supply dynamic getters and finders such as get_by_foo and find_by_bar.

Many of these utilities are familiar to Django’s ORM.

Automatically computes __tablename__ unless overriden as the plural of the words_with_underscores version of the class name. Override if the magic falls on it’s face.

FooBar -> foo_bars

The .objects attribute is query of all objects in the collection with no filters applied. See SQLAlchemy’s query_property. The finders below use .objects so subclasses can override it if they need to apply any default options and criteria.

Gets an object by the collection’s primary key. Returns None if no object is found

Returns an object if one exists or None if no object is found.

Foo.get(1)

Gets an object by a column and value.

Returns an object if one exists or None if no object is found.

Foo.get_by(Foo.id, 1)

Find the objects of .objects matching criteria by order_by

Returns an query of .objects with the criteria and order_by applied.

Foo.find(and_(Foo.id > 10, Foo.id < 100))

Find the first object of .objects matching criteria by order_by

Returns and object or None is no such match exists.

Foo.find_one(and_(Foo.id > 10, Foo.id < 100))

Creates and object from data kwargs, adds it to the session and commits. Override in subclass if you want to enforce behavior on creation (e.g. If you want to always pass in a created_by user)

A the created object after it has been committed to the database.

Foo.create(user=user, name=’marc’)

Attempts to fetch an object by given primary key. If no object is found then an object will be created from the given data dictionary. If update is True, existing objects will be updated from the data dictionary.

Returns a tuple of the object and a boolean indicating whether or not it was created.

obj, created = Foo.get_or_create(1, {‘name’: ‘marc’, ‘user’: user})

Attempts to fetch an object by given column and value. If no object is found then an object will be created from the given data dictionary. If update is True, existing objects will be updated from the data dictionary.

Returns a tuple of the object and a boolean indicating whether or not it was created.

obj, created = Foo.get_by_or_create(Foo.name, ‘marc’, {‘name’: ‘marc’, ‘user’: user})

Attempts to fetch an object by given criteria. If no object is found then an object will be created from the given data dictionary. If update is True, existing objects will be updated from the data dictionary.

Returns a tuple of the object and a boolean indicating whether or not it was created.

obj, created = Foo.get_by_or_create(and_(Foo.name==’marc’, Foo.active=True), {‘name’: ‘marc’, ‘user’: user})

Convenience method to build a simple representation of a mapped instance from the class name and includes the objects primary key(s).

A string

print foo

A list of an objects column names

A list of an objects relationship names

A list of an object’s primary key names

A list of an object’s columns and relationships

Build a dict representation of an object. Pass a list of field names to include to only includes fields explicitly listed. Pass a list of fields names to exclude to omit fields. No relationships are traversed, if you want to include relationships, subclass and manually include those fields.

A dictionary of an object’s fields.

foo.to_dict(exclude=[‘id’])

A method to handle JSON serialization. A common convention is to call __json__ if such a method exists on an object when converting to JSON. By default calls to_dict().

A dict suitable for serialization.

Update an object from a dictionary.

The object updated

foo.update({‘name’: ‘marc’})

Commits the session. This method does not restrict the commit to only the object in question. This is a simple convenience to make code look a bit more literate at the cost of possible unintentional side effects

None

foo.save()

Deletes an object

None

foo.delete()

UTCDateTime will take a time-zone aware datetime and store it as UTC in the database automatically.

See http://techspot.zzzeek.org/2011/01/14/the-enum-recipe/

Included here for easy install

StampedMixin adds created_on and modified_on columns to a table. These columns will updated as needed.

TrackedMixin adds created_by and modified_by columns to a table that relate to a User object. Use the .touch(user) method to update modified_by.

• tests
• ReST docs
• A simple makefile

Marc DellaVolpe ([email protected])