
    
    ** Mother Micro HowTo **



0- Install deps

 Postgresql and psycopg2 are needed. To install the dependencies,
 please, refer to the official sites:

  http://www.postgresql.org
  http://www.initd.org


1- Create a DB

 Start postgresql, and create a user and a database:

   $ createuser --help
   $ createdb --help

 After that, try to connect:

   $ psql -U my_user my_db


2- Download Mother

 Take Mother at www.dbmother.org (for example, the version x.y.z).
 Unpack it:

   $ tar xzf Mother-x.y.z.tgz

 The directory Mother-x.y.z is created. Inside you can find
 the mothe module and examples. Go on:

   $ cd Mother-x.y.z
 
 The directory examples contains some file used in this HowTo.


3- Install

 It's easy:

   $ python setup.py install
 
 this will create the module mother and will install a system script:
 mothermapper.


4- Create a Work Environment

 Mother needs a configuration file: we have to specify here the
 parameters of the database connection, and something more.
 By having more configuration files, we are able to use Mother
 with multiple database, for example.

 First of all, let's create a workdir:

   $ mkdir /my/workdir

 The faster way to create a conf file is to start with a default
 configuration file and tuning it.
 Just use mothermapper (launch `mothermapper -h' to know more):

   $ mothermapper -C /my/workdir/moconf.py

 Now, /my/workdir/moconf.py has to be edited: it is heavy commented, 
 so it's simple to tune it.
 It's very important to set database parameters and configure the
 variable MOTHER_MAP: the database map will reside there.

 Now that the conf file is ready, test the connection:

   $ mothermapper -c /my/workdir/moconf.py -t

 The database used here is contained in examples/sql_sample.sql.
 It's explined in details on the UserGuide at www.dbmother.org.

 Let's create the database tables and the map file:

   $ mothermapper -c /my/workdir/moconf.py -e examples/sql_sample.sql 
   $ mothermapper -c /my/workdir/moconf.py -s
   
 It's all: a Mother environment to handle the database is ready.


5- Define Two classes to handle two tables

 The classes are already defined in examples/sample.py.
 Take a look at this file, and at the files example.py and 
 thread_example.py.

 However, let's define them in a third file: edit the file 
 mydemo.py:

   $ vim mydemo.py

   ### BEGIN FILE ###

   from mother.mothers import *

   class ClsPlanets(DbMother):
      table_name= 'planets'
      def __init__(self, store= {}, flag= MO_NOA):
          DbMother.__init__(self, store, flag)

   class ClsStars(DbMother, MotherManager):
      table_name= 'stars'
      def __init__(self, store= {}, flag= MO_NOA):
          DbMother.__init__(self, store, flag)
          initChildManager([ClsPlanets])

   ### END FILE ###


6- Insert a new star:

 When we use Mother to handle a specific database, we need to
 bind the mother classes to the correct map file. To do that,
 the function init_mother() is used.

 Now, launch the python interpreter and begin to use Mother:

   >>> from mydemo import *
   >>> init_mother('/my/workdir/moconf.py')
   >>> SunDiz= dict(star_name='Sun')
   >>> Sun= ClsStars(SunDiz, MO_SAVE)
   >>> print Sun


7- Modify Sun

   >>> NewFields= dict(star_mass= 12)
   >>> Sun.setFields(NewFields)
   >>> Sun.update()


8- Insert a planet on the sun system

   >>> EarthDiz= dict(planet_name= 'earth', planet_mass= 12)
   >>> Earth= Sun.insertPlanets(EarthDiz)
   >>> print Earth


9- Insert another Planet

   >>> MarsDiz= dict(planet_name= 'mars', planet_mass= 10)
   >>> Mars= Sun.insertPlanets(MarsDiz)


10- Get all planets on the sun system

   >>> SunPlanets= Sun.getMultiplePlanets()
   >>> PlanetsDicts= SunPlanets.getFields()
   >>> PlanetsMothers= SunPlanets.getFields(flag_obj= True)


11- Get all planets with mass< 11

   >>> SunPlanets= Sun.getMultiplePlanets(filter='planet_mass< 11')


12- Get all planets with mass= 10

   >>> SunPlanets= Sun.getMultiplePlanets(filter=dict(planet_mass= 10))


13- Delete all Planets on the Sun System

   >>> Sun.deleteMultiplePlanets()


14-
 Dive into: read the official user guide and enjoy ;)







 
