[Modeling-cvs] ProjectModeling/Modeling/doc README.dynamic.txt,NONE,1.1

[<sbi...@us...>]

Update of /cvsroot/modeling/ProjectModeling/Modeling/doc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19962/Modeling/doc

Added Files:
	README.dynamic.txt 
Log Message:
Integrated patch #814055: Dynamic creation of packages/modules/classes

--- NEW FILE: README.dynamic.txt ---
---------------------------
Dynamic creation of classes
---------------------------

:Authors:
    Sébastien Bigaret <sbi...@us...>

Principles
----------

The module Modeling.dynamic has been added. It can be used in three
different ways:

  * method build(model): dynamically build the package derived from the
    model. The generated package and its modules have the very same
    functionality as the ones generated by the script
    mdl_generate_python_code.py (in "base" mode, option ``-B``).

  * metaclass ``CustomObjectMeta``: automatically adds all the necessary
    methods to a class for integration with the modeling framework. It
    looks for the following attributes in the class:

      - ``entityName``: mandatory, this is the name of the class'
        entity. The corresponding model should have been loaded prior to
        the class declaration, or you'll get a dynamic.EntityNotFound
        exception.

     - ``verbose_metaclass``: if set, the metaclass prints on sys.stderr
       some info while building the class.

     - ``mdl_define_properties``: if set, the metaclass will also add
       properties for each attribute on relationship in the entity, so
       that you do not need anymore to use e.g. ``book.getTitle()`` or
       ``book.setTitle``, but simply ``print book.title`` or
       ``book.title="my title"``

       Note: this name is not definitive and will probably be changed
       before this is integrated into the core (same for metaclass,
       methods' names, etc.). Suggestions are welcome!

  * method ``build_with_metaclass(model, define_properties)``: builds
    the package and its module from a model. The generated modules and
    classes uses the ``CustomObjectMeta`` metaclass. Parameter
    ``define_properties`` triggers the creation of properties by the
    metaclass.

    This method raises ``NotImplementedError`` under python2.1, as
    expected.

Note: The model will be loaded, as usually, from XML or PyModels, for
      example with Model.searchModel(). See e.g.
      tests/test_EditingContext_Global.py for an example.


Example of use
--------------

You find there three different examples on how these new features can be
used::

  ### Common to exs 1, 2 & 3: load the model
  from Modeling import ModelSet, Model, dynamic
  model=Model.searchModel('AuthorBooks', '.', verbose=1)
  ModelSet.defaultModelSet().addModel(model)
  
  ### 1. example with dynamic.build()
  dynamic.build(model)
  from Modeling.EditingContext import EditingContext
  from AuthorBooks.Book import Book
  # fetch
  ec=EditingContext()
  print [b.getTitle() for b in ec.fetch('Book')]
  # create a new book
  b=Book(title='mon titre')
  ec.insert(b)
  ec.saveChanges()
  
  ### 2. example with dynamic.build_metaclass()
  dynamic.build_with_metaclass(model, define_properties=1)
  from Modeling.EditingContext import EditingContext
  ec=EditingContext()
  print [b.title for b in ec.fetch('Book')]
  from AuthorBooks.Book import Book
  b=Book(title='mon titre7.2')
  ec.insert(b)
  ec.saveChanges()
  b.price=7.21
  
  ### 3. example with the metaclass
  class Book:
    __metaclass__=dynamic.CustomObjectMeta
    entityName='Book'
    mdl_define_properties=1
  
  class Writer:
    __metaclass__=dynamic.CustomObjectMeta
    entityName='Writer'
    mdl_define_properties=1
  
  # fetch and insert etc., as usual:
  from Modeling.EditingContext import EditingContext
  ec=EditingContext()
  b=Book(title='book_w1') ; w1=Writer(lastName='w1')
  ec.insert(b) ; ec.insert(w1)
  b.author=w1
  w1.addToBooks(b)
  ec.saveChanges()


Tests
-----

All three tests test_EC_Global.py, test_EC_Global_Inheritance.py and
test_EC_ParentChild.py now accepts new options:

  * ``-c`` uses ``dynamic.build(model, define_properties=0)``

  * ``-C`` uses ``dynamic.build(model, define_properties=1)``

  * ``-m`` uses ``dynamic.build_with_metaclass(model, define_properties=0)``

  * ``-M`` uses ``dynamic.build_with_metaclass(model, define_properties=1)``

  * without any of these options, they use the test packages in
    tests/testPackages as in the standard distribution.

Note: they all require that you copy the pymodels pymodel_AuthorBooks.py
      (in testPackages/AuthorBooks/) and pymodel_StoreEmployees.py (in
      (testPackages/StoreEmployees/) in the tests/ directory.


Changes
-------

Some classes have been changed to derive from ``object``, when available
(python v2.2+), just because I've noted that this results in slightly
better performance; however, this has nothing to do with the dynamic
creation of classes.

Among those classes that are now new-style classes: CustomObject. When
it is integrated into the framework, this will probably be left as a
choice for the user: since this transforms any user-class inheriting
from CustomObject into new-style classes, this can have unexpected
side-effects in other portions of the user's code (for example,
``type(object)==InstanceType`` for classic-style classes, while it
equals to ``obj.__class__`` for new-style classes).


Known issues
------------

If you get errors such as:

    ".../Modeling/dynamic.py", line 39, in instance_method
    	 meth=new.instancemethod(func, None, aClass)
    TypeError: instancemethod() argument 3 must be class, not type

with python 2.2 you've probably been bitten by a bug in python 2.2
final, that has been fixed from version 2.2.1c1. See in particular:
  http://sf.net/tracker/index.php?func=detail&aid=503091&group_id=5470&atid=105470
  http://www.python.org/2.2.2/NEWS.txt

  In this case, you should upgrade your python version.

Note: python2.2 shipped w/ MacOS X has this bug.

Thanks to Mario Ruggier for reporting the problem.