Reference

item.Item(store=store.Store, **kw)

A class describing an object in an Axiom Store. Your subclass of axiom.item.Item must define the following attributes:

  • typeName: A string uniquely identifying this class schema in the store.
  • schemaVersion: An integer denoting the schema version. See Upgraders.

You will also want to define other attributes and these must be special Axiom class attributes. A selection of standard types are already defined in the axiom.attributes module.

A simple example:

from axiom import item, attributes

class ShopProduct(item.Item):
    typeName = 'ShopProduct'
    schemaVersion = 1

    name = attributes.text(allowNone=False)
    price = attributes.integer(allowNone=False)
    stock = attributes.integer(default=0)

    def __repr__(self):
        return '<ShopProduct name='%s' price='%d' stock='%d'>' % (self.name, self.price, self.stock)

Limitations

  • Axiom Items only support one level of inheritance. You could not for example write a subclass of the ShopProduct class above. This is by design, and you are encouraged to explore object composition and adaption instead.

store.Store([dbdir=None[, debug=False[, parent=None[, idInParent=None]]]])

A database in which Axiom Items can be stored. An Axiom Store can be instantiated with a dbdir parameter, in which case it will be persisted to the filesystem at the given path. Alternatively, if instantiated without a dbdir parameter, the store will exist inmemory only for the lifetime of the python process.

from axiom import store

s = store.Store('/tmp/example.axiom')
s = store.Store() # An inmemory store

If debug=True, the store will print out all SQL commands as they are issued to the underlying Sqlite database.

Add Items to the Store

p = ShopProduct(store=s, name=u'Tea Bags', price=2)

That’s all there is to it. The returned item can be treated just like any other python object. Changes made to it are automatically persisted to the store.

>>> p.name
u'Tea Bags'
>>> p.stock
0
>>> p.stock += 20
>>> p.stock
20

If you want to avoid duplicate items you can instead use the findOrCreate method (see below)

Retrieve Items from the Store

  • getItemByID(storeID[, default=_noItem]):

    Returns the item with the given ‘storeID’. If no matching item raises KeyError or ‘default’ if given. Every item in the store has a unique ‘storeID’ attribute.

  • findFirst'''(userItemClass[, **attrs]):

    Returns the first item of class ‘userItemClass’ or None. The query can be further narrowed by specifying ‘attrs’, eg

    >>> s.findFirst(ShopProduct, name=u'Tea Bags')
<ShopProduct name='Tea Bags' price='2' stock='20'>

  • findOrCreate(userItemClass[, **attrs]):

    Returns the first item of class ‘userItemClass’ or creates it if it doesn’t already exist. eg.

    >>> s.findOrCreate(ShopProduct, name=u'Pot Noodle')
TypeError: attribute `= integer() <ShopProduct.price>`_ must not be None

    but we must give all attributes required to create the new item

    >>> s.findOrCreate(ShopProduct, name=u'Pot Noodle', price=3)
<ShopProduct name='Pot Noodle' price='3' stock='0'>

  • query(tableClass[, comparison=None[, limit=None[, offset=None[, sort=None[, justCount=False[, sumAttribute=None]]]]]]):

    Return generator of items matching class ‘tableClass’ and ‘comparison’. Limited to length ‘limit’ beyond ‘offset’. Sorted by attribute ‘sort’. Examples:

    >>> 'All products'
>>> [x.name for x in s.query(ShopProduct)]
[u'Tea Bags', u'Pot Noodle']
>>> 'Products in stock'
>>> [x.name for x in s.query(ShopProduct, ShopProduct.stock > 0)]
[u'Tea Bags']
>>> 'Products in stock AND which cost less than 5'
>>> from axiom.attributes import AND, OR
>>> [x.name for x in s.query(ShopProduct, AND(ShopProduct.stock > 0, ShopProduct.price < 5))]
[u'Tea Bags']

    You get the idea. Try turning on store debugging and you will get an idea of what is going on behind the scenes.

    >>> s.debug = True
>>> [x.name for x in s.query(ShopProduct, sort=ShopProduct.stock.ascending)]
** SELECT item_ShopProduct_v1 .oid, item_ShopProduct_v1 .* FROM item_ShopProduct_v1 ORDER BY item_ShopProduct_v1.`ASC --
********** COMMIT **********
  lastrow: None
  result: [(4, u'Pot Noodle', 3, 0), (3, u'Tea Bags', 2, 20) <stock]>`_
[u'Pot Noodle', u'Tea Bags']

    Axiom is also capable of constructing more complex queries involving table joins behind the scenes. For more complete examples see axiom-examples.

Substore

A Store that also exists as an Item in a parent Store.

Powerups

A powerup is a type of Axiom plugin. Zero or more powerups (Axiom items) can be registered to another axiom item (as long as it is in the same store) and can be retrieved according to their interface, either by normal adaption of the subject (in which case the highest priority powerup is returned), or as a group (in order of priority) by using the axiom.item.Item.powerupsFor method.

Upgraders

?