Section A.4. More about ActiveMapper

A.4. More about ActiveMapper

The SQLAlchemy documentation covers SQLAlchemy's features in detail, but it does not cover the "extensions", and ActiveMapper is an extension. Luckily, there is not much you need to know about ActiveMapper. In SQLAlchemy, when you define a table, you typically do something like this:

    products = Table("products", metadata,         Column("product_id", Integer, primary_key=True),         Column("product_code", String(20), unique=True),         Column("description", String))

You can easily tell SQLAlchemy to map a class to that table:

    class Product(object):         pass     pmap = mapper(Product, products)

At that point, pmap offers methods for retrieving Product objects from the database. Here is the equivalent table and class created with ActiveMapper:

    class Product(ActiveMapper):         class mapping:             product_id = column(Integer, primary_key=True)             product_code = column(String(20), unique=True)             description = column(String)

All of the methods (get_by, select, and so on) that are typically found on the pmap object in the first example are available directly on the Product class in the second example.

The mapper is available via Product.mapper and the table object is available via Product.table, if you need to work directly with those objects.

Not much actual difference exists between the two examples, and that is part of the idea. ActiveMapper does not try to reinvent any of SQLAlchemy's core object-relational mapping features. It just provides a more concise syntax for times when the Active Record pattern works well.

One useful behavior to note about ActiveMapper: ActiveMapper will automatically save() new objects that you create into the session located at turbogears.database.session. This behavior differs from what you get using plain SQLAlchemy, but it is equivalent to what you get with SQLObject.