

    ** The MotherCaster Plugin **


 - Goals

The MotherCaster plugin has two goals:

  * Provide a validation for fields types
  * Provide a validation for required fields

The plugin is very usefule when Mother is used with a Web Form, 
because it' possible to control fields consistency (types) and 
fields presence (required fields).


 - How

Use the Plugin is simple. It's contained in mother.plugins, and 
his name is mocaster.

To use a MptherClass with the MotherCaster plugin two things are 
needed:

  * Define in your class a dictionnary
  * inherit from MotherCaster


 - Example

Code example:

from mother.mothers import DbMother, MO_NOA
from mother.plugins.mocaster import *

class ClsStars(DbMother, MotherCaster):

  cast_fields= {
      star_mass: int,
      star_age: int,
      star_name: str }

  # Optionally...
  required_fields= ['star_age']

  def __init__(self, d= {}, flag= MO_NOA, session= None):

      MotherCaster.__init__(self, autocast= True)
      DbMother.__init__(self, d, flag, session)


 - Details

Note that:

  * cast_fields does not have to contain all fields for 
    the table.

  * required_fields is optional and the previous consideration 
    apply there.

When a ClsStars is initialized, the following happens:

  * fields are checked: if they have a wrong type, a casting is 
    automatically done (auotcast= True)

  * if a provided field is not present in the table stars, it's 
    dropped (note that this does not depend on cast_fields 
    declaration).

  * Mother controls if all required_fields are provided.

 
 - Exceptions

In case of error, a MoWrongFields instance is raised.


 - Examples

Examples (remember to initialize Mother before):

>>> MyDict= dict(star_name= 19, star_age= '12', not_existent_field=1)
>>> MyStar= ClsStars(MyDict, MO_NOA)

Here, star_name becomes '19' and star_age 12. not_existent_field 
is silently dropped.

>>> MyDict= dict(star_name= 'sun', star_mass='www')
>>> try:
...  MyStar= ClsStars(MyDict, MO_NOA)
... except MoWrongFields, errors:
...  print "Invalid types:", errors.ifields
...  print "Missing fields:", errors.mfields
>>> 

Here, star_mass is invalid because it's impossible to cast it to an 
int, and star_age, which is a required field, is missing.


