README

   1 minidb - A simple SQLite3 store for Python objects
   2 ==================================================
   3
   4 minidb is a Python module that utilizes the SQLite3 database library in order
   5 to store and retrieve Python objects. It utilizes Python's __slots__ mechanism
   6 to determine the column names, and uses the class name for table names. Data is
   7 always stored as text in the database, but will be converted using the type
   8 specified in __slots__ (which therefore has to be a dict).
   9
  10
  11 A very basic example
  12 --------------------
  13
  14 let's define a "Person" object having an ID (that's not a requirement, but we
  15 use it for good measure) and a name:
  16
  17     >>> class Person(object):
  18     >>>    __slots__ = {'id': int, 'name': str}
  19
  20 The minidb.Store class represents our database. By default, it uses an
  21 in-memory database, but you can pass a filename to its constructor to persist
  22 the data to a file:
  23
  24     >>> import minidb
  25     >>> db = minidb.Store('persons.db')
  26
  27 We can now simply create a person object and store it in the database (note
  28 that you can write an __init__ method, but you don't have to, and it won't be
  29 used by minidb when retrieving data from the database):
  30
  31     >>> john = Person()
  32     >>> john.id = 42
  33     >>> john.name = "John"
  34     >>> db.save(john)
  35
  36 You should commit and close the DB after using it:
  37
  38     >>> db.commit()
  39     >>> db.close()
  40
  41 Let's have a look at the "persons.db" file with the "sqlite3" command-line
  42 utility and inspect what minidb has created:
  43
  44     sqlite> .schema
  45     CREATE TABLE Person (id TEXT, name TEXT);
  46
  47 Looks good (as already mentioned, the data type in the table will always be
  48 TEXT, and minidb takes care of converting the data during load/save). And this
  49 is the data that's currently stored in the database:
  50
  51     sqlite> SELECT * FROM Person;
  52     42|John
  53
  54 Loading data works similarly. Let's start fresh (assuming the "Person" class
  55 will be defined as above) and load the stored Person:
  56
  57     >>> db = minidb.Store('persons.db')
  58     >>> db.load(person)
  59     [<__main__.Person object at 0x7fa17a52d210>]
  60     >>> [(p.id, p.name) for p in db.load(Person)]
  61     [(42, 'John')]
  62
  63 You can have a look at the API documentation using the "pydoc" command line
  64 utility or "help" in the interactive shell:
  65
  66     >>> help(minidb.Store)
  67
  68 See the file "minidb.py" for some examples on what you can do with minidb.
  69
  70
  71 Remarks
  72 -------
  73
  74 The initial idea code for this project was code-named "ORM wie eine
  75 Kirchenmaus" and released on 2009-11-29.
  76
  77 --
  78 Thomas Perl <m@thp.io>; 2010-10-30
  79