Package bazaar
[show private | hide private]
[frames | no frames]

Package bazaar

Bazaar ORM is an easy to use and powerful abstraction layer between relational database and object oriented application.

Features: Requirements:

This is free software distributed under GNU Lesser General Public License. Download it from project's page on Savannah.

Bazaar ORM is easy to use, but is designed for people who know both object-oriented and relational technologies, their advantages, disadvantages and differences between them (``The Object-Relational Impedance Mismatch'' reading is recommended).

Using the layer

Creating application classes

Let's consider following diagram:
   Order < 1 ---- * > OrderItem
   OrderItem | * ---- 1 > Article

There are three classes and two associations. Both relationships are one to many associations, but first one is bi-directional and second is uni-directional.

Class definition (more about class and relationships defining can be found in bazaar.conf module documentation) should be like:
   # import bazaar module used to create classes
   import bazaar.conf

   # create class for articles
   # class name is specified, relation equals to class name
   Article = bazaar.conf.Persistence('Article')

   # add class attributes and relation columns
   # class attribute name is the same as relation column name

   # create order and order items classes
   # class names are different than database relation names
   Order = bazaar.conf.Persistence('Order', relation = 'order')
   OrderItem = bazaar.conf.Persistence('OrderItem', relation = 'order_item')

   Order.addColumn('no')           # order number
   OrderItem.addColumn('pos')      # order item position
   OrderItem.addColumn('quantity') # article quantity

   # define bi-directional association between Order and OrderItem classes
   # from OrderItem perspective
   # attribute name: order
   # relation column name: order_fkey
   # referenced object's class: Order
   # referenced object's class attribute name: items
   OrderItem.addColumn('order', 'order_fkey', Order, vattr = 'items')

   # from Order perspective
   # attribute name: items
   # referenced object's class: OrderItem
   # referenced relation column name: order_fkey
   # referenced object's class attribute name: order
   Order.addColumn('items', vcls = OrderItem, vcol = 'order_fkey', vattr = 'order')

   # define uni-directional association between OrderItem and Article classes
   # attribute name: article
   # relation column name: article_fkey
   # referenced object's class: Article
   OrderItem.addColumn('article', 'article_fkey', Article)
Now, SQL schema can be created:
   # primary key values generator
   create sequence order_seq;
   create table "order" (
       # every application object is identified with __key__ attribute
       __key__      integer,
       no           integer not null unique,
       finished     boolean not null,
       primary key (__key__)

   create sequence article_seq;
   create table article (
       __key__      integer,
       name         varchar(20) not null,
       price        numeric(10,2) not null,
       unique (name),
       primary key (__key__)

   create sequence order_item_seq;
   create table order_item (
       __key__      integer,
       order_fkey   integer,
       pos          integer not null,
       article_fkey integer not null,
       quantity     numeric(10,3) not null,
       primary key (__key__),
       unique (order_fkey, pos),

       # association between Order and OrderItem
       foreign key (order_fkey) references "order"(__key__),

       # association between OrderItem and Article
       foreign key (article_fkey) references article(__key__)

Application code

Application must import Bazaar ORM core module:
   import bazaar.core
   import psycopg

DB API module is imported, too. However, it is not obligatory because it can be specified in config file, see bazaar.config module documentation for details.

Create Bazaar ORM layer instance. There are several parameters (bazaar.core.Bazaar), but now in this example only list of application classes and DB API module are specified:
   bzr = bazaar.core.Bazaar((Article, Order, OrderItem), dbmod = psycopg)
Connect to database:
   bzr.connectDB('dbname = ord')

Connection string is standard database source name (dsn) described in DB API 2.0 specification. Connection can be established with bazaar.core.Bazaar class constructor, too.

Create application object:
   apple = Article() = 'apple'
   apple.price = 2.33
Object constructor can initialize object attributes:
   oi1 = OrderItem(pos = 1, quantity = 10)
   oi1.article = apple

   peach = Article() = 'peach'
   peach.price = 2.34

   oi2 = OrderItem(article = peach)
   oi2.pos = 2
   oi2.quantity = 40
Create new order:
   ord = Order(no = 1)
Append order items to order. It can be made in two ways (it is bi-directional relationship):
   oi2.order = ord
Finally, add created objects data into database:

Objects can be updated and deleted, too (bazaar.core.Bazaar).

Now, let's play with some objects. Remove second order item from order no 1:
   del ord.items[oi2]
And update association:
Add second order item again:
Change apple price:
   apple.price = 2.00
And update database data:
Print all orders:
   for ord in bzr.getObjects(Order):
       print ord
Find order number 1:
   bzr.find(Order, {'no': 1})
Find order items for article "apple":
   bzr.find(OrderItem,  {'article': apple})
Finally, commit transaction:

  • assoc: Association classes.
  • cache: Cache and reference buffer classes.
  • conf: Provides classes for mapping application classes to database relations.
  • config: Module contains basic classes for Bazaar ORM layer configuration.
  • core: This module contains basic Bazaar ORM implementation.
  • exc: Bazaar ORM exceptions.
  • motor: Data convertor and database access classes.
  • test: This module simplifies unit testing of applications and libraries, which use Bazaar ORM library.

Log Utility class to deffer creation of loggers (of logging package).

Generated by Epydoc 2.1 on Tue May 10 18:27:29 2005