The pure-Python engine consists of one module, pydblite.py. To use it, import the class Base from this module:
from pydblite.pydblite import Base
Create a database instance, passing it a path in the file system
db = Base('test.pdl')
For a new database, define the field names
db.create('name', 'age', 'size')
You don’t have to define the field types. Any value will be accepted as long as it can be serialized by the cPickle module:
db.exists() indicates if the base exists.
if the base exists, open it
if db.exists():
db.open()
You can pass a parameter “mode” to the create() method, to specify what you want to do if the base already exists in the file system
db.create('name', 'age', 'size', mode="open")
opens the database and ignores the field definitiondb.create('name', 'age', 'size', mode="override")
erases the existing base and creates a new one with the field definitionmode
is not specified and the base already exists, an IOError
is raiseddb.insert(name='homer', age=23, size=1.84)
If some fields are missing, they are initialized with the value None
db.insert('homer', 23, 1.84)
The arguments must be provided in the same order as in the create()
method
db.commit()
If you don’t commit the changes, the insertion, deletion and update operations will not be saved on disk. As long as changes are not commited, use open()
to restore the values as they are currently on disk (this is equivalent to rollback in transactional databases)
db.delete(list_of_records)
where list_of_records can be any iterable (list, tuple, set, etc) yielding records
db.update(record, age=24)
create()
method, an internal field called __id__
is added. It is an integer which is guaranteed to be unique and unchanged for each record in the base, so that it can be used as the record identifier__version__
is also managed by the database engine. It is an integer which is set to 0 when the record is created, then incremented by 1 each time the record is updated. This is used to detect concurrency control, for instance in a web application where 2 users select the same record and want to update it at the same timeThe instance of Base is a Python iterator
for r in db:
do_something_with(r)
A record can be accessed by its identifier
record = db[rec_id]
returns the record such that record['__id__'] == rec_id
db(key1=val1, key2=val2)
returns the list of records where the keys take the given valuesdb(key) >= val
returns an iterator on all records where the value of the field key is greater than or equal to val.Example
for rec in (db("age") > 30):
print rec["name"]
such “rich comparison” operations can be combined with & (AND) and | (OR)
for rec in (db("age") > 30) & (db("country") == "France"):
print rec["name"]
The selection of records can use Python list comprehension syntax
recs = [r for r in db if 30 > r['age'] >= 18 and r['size'] < 2]
Returns the records in the base where the age is between 18 and 30, and size is below 2 meters. The record is a dictionary, where the key is the field name and value is the field value
Python generator expression syntax can also be used
for r in (r for r in db if r['name'] in ('homer', 'marge')):
do_something_with(r)
iterates on the records where the name is one of ‘homer’ or ‘marge’
To speed up selections, an index can be created on a field using create_index('field')
db.create_index('age')
When an index is created, the database instance has an attribute (here _age
: note the heading underscore, to avoid name conflicts with internal names). This attribute is a dictionary-like object, where keys are the values taken by the field, and values are the records whose field values are egal to the key :
records = db._age[23]
returns the list of records with age == 23
If no record has this value, lookup by this value returns an empty list
The index supports iteration on the field values, and the keys()
method returns all existing values for the field
default
is an optional default value ; set to None
if not specified__id__
and __version__
)len(db)
: number of records in the base