Français

## Pure-Python engine The pure-Python engine consists of one module, `PyDbLite.py`. To use it, import the class `Base` from this module : from PyDbLite import Base ### Create or open a database 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. PyDbLite will accept any value that can be serialized by the `cPickle` module : strings, Unicode strings, integers, floats, dates and datetimes (instances of the `date` and `datetime` classes in the `datetime` module), user-defined classes, etc db.exists() indicates if the base exists if the base exists, open it : 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 mode = "open" : db.create('name','age','size',mode="open") opens the database and ignores the field definition mode = "override" : db.create('name','age','size',mode="override") erases the existing base and creates a new one with the field definition if mode is not specified and the base already exists, an `IOError` is raised ### Insert, update, delete a record insert a new record by keywords : db.insert(name='homer',age=23,size=1.84) If some fields are missing, they are initialized with the value `None` by positional arguments : db.insert('homer',23,1.84) The arguments must be provided in the same order as in the `create()` method save the changes on disk : 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) besides the fields passed to the `create()` method, an internal field called `__id__` is added. It is a 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 another internal field called `__version__` is also managed by the database engine. It is a 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 time to delete a record : db.delete(record) or, if you know the record identifier : del db[rec_id] to delete a list of records : db.delete(list_of_records) `list_of_records` can be any iterable (list, tuple, set, etc) yielding records to update a record : db.update(record,age=24) ### Selection The instance of `Base` is a Python iterator ; to iterate on all the records : for r in db: do_something_with(r) #### Direct access A record can be accessed by its identifier : record = db[rec_id] returns the record such that record['__id__'] == rec_id #### Simple selections db(key1=val1,key2=val2) returns the list of records where the keys take the given values db(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"] #### List comprehension 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' #### Index To speed up selections, an index can be created on a 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 ### Other attributes and methods db.add_field('new_field'[,default=v]) : adds a new field to an existing base. default is an optional default value ; set to `None` if not specified db.drop_field('name') : drops an existing field db.path : the path of the database in the file system db.name : the database name : the basename of the path, stripped of its extension len(db) : number of records in the base db.fields : the list of the fields (does not include the internal fields `__id__` and `__version__`)