4 The Big Example

An Oracle example:

Ok, for starters you've got a simple users table:

CREATE TABLE USERS (
    OID NUMBER,
    USERNAME VARCHAR(16),
    PASSWORD VARCHAR(16),
    CREATED DATE,
    LAST_MOD DATE
);

And a sequencer for the OID:

CREATE SEQUENCE USERS_OID_SEQ;

And you want to do stuff with it using PyDO.

from PyDO import *
DBIInitAlias('drew', 'pydo:oracle:drew/drew@drew')
class Users(PyDO):
    connectionAlias = 'drew'
    table = 'USERS'
    fields = (
        ('OID'     , 'NUMBER'),
        ('USERNAME', 'VARCHAR(16)'),
        ('PASSWORD', 'VARCHAR(16)'),
        ('CREATED' , 'DATE'),
        ('LAST_MOD', 'DATE')
        )
    sequenced = {
        'OID': 'USERS_OID_SEQ'
        }
    unique = [ 'OID', 'USERNAME' ]

Ok, line-by-line, this is what this all means:

> from PyDO import *

Import the contents of PyDO into your module namespace. PyDO is pretty clean and shouldn't pollute the namespace significantly as it was designed to be imported this way, but if that irks you, doing a regular import PyDO will also work (but you'll need to adequately qualify things, obviously).

> DBIInitAlias('drew', 'pydo:oracle:drew/drew@drew')

PyDO has a database driver library thingy. It's not really meant for use outside of PyDO, but you can use it if you like, it's mainly there so the main PyDO code doesn't have to care so much about the underlying database so much in terms of things like: whether it support bind variables or not and etc.

The arguments to DBIInitAlias are: a connection alias name (used as connectionAlias in your data classes), and a PyDO connect string. For oracle, the connect strings are of the form pydo:oracle:user/password@inst.

> class Users(PyDO):

All dataclasses inherit directly or indirectly from the PyDO base class.

> connectionAlias = 'drew'

Used to select the database connection to use for this object. You can have more than one connection going at a time, so you need to choose one (presumably the one that has the table you're going to use). In this case we're going to use the alias that we initialized previously.

> table = 'USERS'

PyDO needs to know what table the rows will be coming from if it's going to do anything, so we point it at the previously created USERS table.

> fields = (
>     ('OID'     , 'NUMBER'),
>     ('USERNAME', 'VARCHAR(16)'),
>     ('PASSWORD', 'VARCHAR(16)'),
>     ('CREATED' , 'DATE'),
>     ('LAST_MOD', 'DATE')
>     )

What you need to do here is associate the column names from the table to their database type. The case of the column names *must* be the same as the native case of the database for such things (specifically, the same case as what the database driver returns on a describe of a query). For most databases, this is uppercase, same for the database type.

> sequenced = {
>     'OID': 'USERS_OID_SEQ'
> }

This says, if on a call to new() (described later), OID is not specified, then fetch it from the sequence here named.

> unique = [ 'OID', 'USERNAME' ]

This is a list of candidate keys -- columns that uniquely identify a row.

Subsections