docs

lsbardel · lsbardel · commit bc2ae4ee4ebb · 2012-04-16T07:58:20.000+01:00
diff --git a/docs/source/examples/tutorial.rst b/docs/source/examples/tutorial.rst
@@ -1,5 +1,6 @@
 .. _tutorial:
 
+.. module:: stdnet.orm
 
 ============================
 Using Models
@@ -15,7 +16,7 @@ Writing Models
 ==========================
 
 Defining stdnet *models* is achieved by subclassing the
-:class:`stdnet.orm.StdModel` class. The following
+:class:`StdModel` class. The following
 snipped implements two models, ``Author`` and ``Book``::
 
     from stdnet import orm
@@ -44,11 +45,11 @@ An application
 
 Let's start with tutorial application: a small hedge fund.
 You never know it may become useful in the future!
-
 The application uses the following three models,
 
-* A ``Fund`` which stores information about several ``Position``
-* A ``Position`` is an investment on a particular funancial ``Instrument``.
+* ``Fund`` for storing information about several ``Position``.
+* ``Instrument`` holds information about tradable financial intruments.
+* ``Position`` is an investment on a particular ``Instrument`` in a ``Fund``.
 
 A minimal ``stdnet`` implementation can look like this::
 
@@ -87,45 +88,50 @@ A minimal ``stdnet`` implementation can look like this::
             
 If you are familiar with django_ you will see several similarities and you should be able to understand,
 with a certain degree of confidence, what it is going on.
-The only difference is the ``prices`` :class:`stdnet.orm.ListField`
+The only difference is the ``prices`` :class:`ListField`
 in the ``Instrument`` model which is
 not available in a traditional relational database.
 
 The metaclass
 ~~~~~~~~~~~~~~~~~~~~~~~
-The ``Position`` models specifies a ``Meta`` class with an ``ordering`` attribute.
+The ``Position`` models specifies a ``Meta`` class with an ``ordering``
+attribute.
 When provided, as in this case, the Meta class fields are used by the ``orm``
-to customize the build of the :class:`stdnet.orm.Metaclass` for the model.
-In this case we instruct the mapper to manage the ``Position`` model
-as ordered with respect to the :class:`stdnet.orm.DateField` ``dt``
+to customise the build of the :class:`Metaclass` for the model. The metaclas
+is stored in the :attr:`StdModel._meta` attribute.
+
+In this case we instruct the orm to manage the ``Position`` model
+as ordered with respect to the :class:`DateField` ``dt``
 in descending order. Check the  :ref:`sorting <sorting>`
 documentation for more details or ordering and sorting.
 
 
 Registering Models
 ================================
 
-Before playing with the API you need to :ref:`register the models <register-model>`::
+Before playing with the API let's to :ref:`register the models <register-model>`
+to a backend server. Registration is not compulsory, but it is required when using
+model's :class:`Manager`::
 
     import orm
 
     orm.register(Fund, 'redis://my.host.name:6379/?db=1')
     orm.register(Instrument, 'redis://my.host.name:6379/?db=1')
-    orm.register(Position, 'redis://my.host.name:6379/?db=2')
+    orm.register(Position, 'redis://my.host.name:6379/?db=1')
     
 
 .. _one-to-many:
 
 One-to-many relationships
 ================================
 
-The *Position* model contains two :class:`stdnet.orm.ForeignKey` fields.
+The *Position* model contains two :class:`ForeignKey` fields.
 In the context of relational databases a
 `foreign key <http://en.wikipedia.org/wiki/Foreign_key>`_ is
 a referential constraint between two tables.
 
 For stdnet is exactly the same thing. The field store the ``id`` of a
-related :class:`stdnet.orm.StdModel` instance.
+related :class:`StdModel` instance.
 Behind the scenes, this functionality is implemented by Python descriptors_.
 This shouldn't really matter to you, but we point it out here for the curious.
 
@@ -142,7 +148,7 @@ update and delete objects.
 Creating objects
 ~~~~~~~~~~~~~~~~~~~~~
 
-An instance of a :class:`stdnet.orm.StdModel`, an object for clarity,
+An instance of a :class:`StdModel`, an object for clarity,
 is mapped to a hash table in the :class:`stdnet.BackendDataServer` backend.
 To create an object, instantiate it using keyword arguments to the
 model class, then call ``save()`` to save it to the data-server.
diff --git a/docs/source/model/models.rst b/docs/source/model/models.rst
@@ -173,13 +173,13 @@ TS
 Registration
 ======================
 
-Once a model is defined, in order to use it in an application it needs to be
-registered with a back-end database. Unregistered models cannot be used to save
-data and they will raise exceptions.
+Models can be registered with a :class:`stdnet.BackendDataServer` so that
+the model :class:`Manager` can be used to create instance and query the database.
+If a model is not registered, the only way to operate on it is via the
+:class:`Session` API. 
 
-Stdnet comes with two functions for
-registration, a low level and a higher level one which can be used to register
-several models at once.
+Stdnet provides two registration functions, a low level and a higher level one
+which can be used to register several models at once.
 
 Register
 ~~~~~~~~~~~~~~~~
diff --git a/stdnet/orm/mapper.py b/stdnet/orm/mapper.py
@@ -60,26 +60,20 @@ def flush_models(includes = None, excludes = None):
 
 def register(model, backend = None, ignore_duplicates = True,
              local_thread = False, **params):
-    '''The low level function for registering a :class:`stdnet.orm.StdModel`
-classes with a :class:`stdnet.backends.BackendDataServer` data server.
+    '''The low level function for registering a :class:`StdModel`
+classes with a :class:`stdnet.BackendDataServer` data server.
     
-:parameter model: a :class:`stdnet.orm.StdModel` class. Must be provided.
+:parameter model: a :class:`StdModel`. Must be provided.
 
 :parameter backend: a backend connection string.
     For example::
 
         redis://localhost:8080?db=6&prefix=bla.
     
     Default ``settings.DEFAULT_BACKEND``.
-                    
+    
 :parameter params: optional parameters which can be used to override the
     connection string parameters.
-                      
-:parameter timeout: timeout in seconds for keys persistence.
-                    If not provided it is calculated from the
-                    connection string.
-                    
-                    Default ``None``.
     
 **Usage**
     
@@ -90,7 +84,7 @@ def register(model, backend = None, ignore_duplicates = True,
     orm.register(Author, 'redis://my.host.name:6379/?db=1')
     orm.register(Book, 'redis://my.host.name:6379/?db=2')
     orm.register(MyOtherModel, 
-                'redis://my.host.name:6379/?db=2&keyprefix=differentprefix')
+                'redis://my.host.name:6379/?db=2&keyprefix=differentprefix.')
     
 ``my.host.name`` can be ``localhost`` or an ip address or a domain name,
 while ``db`` indicates the database number (very useful for separating data
@@ -130,17 +124,17 @@ def unregister(model = None):
         
 
 def registered_models():
-    '''Iterator over registered models'''
+    '''An iterator over registered models'''
     return (m for m in _GLOBAL_REGISTRY)
     
     
 def model_iterator(application):
-    '''\
-Returns a generatotr of :class:`stdnet.orm.StdModel` classes found
-in the ``models`` module of an ``application`` dotted path.
+    '''A generator of :class:`StdModel` classes found in *application*.
 
-:parameter application: An iterable over python dotted-paths
-                        where models are defined.
+:parameter application: A python dotted path or an iterable over python
+    dotted-paths where models are defined.
+    
+Only models defined in these paths are considered.
 
 For example::
 
@@ -164,13 +158,12 @@ def model_iterator(application):
         try:
             mod_models = import_module('.models',application)
         except ImportError:
-            raise StopIteration
-        
-        label = getattr(mod_models,'app_label',label)
+            mod_models = mod
+        label = getattr(mod_models, 'app_label', label)
         for name in dir(mod_models):
-            model = getattr(mod_models,name)
-            meta = getattr(model,'_meta',None)
-            if isinstance(model,StdNetType) and meta:
+            model = getattr(mod_models, name)
+            meta = getattr(model, '_meta', None)
+            if isinstance(model, StdNetType) and meta:
                 if not meta.abstract and meta.app_label == label:
                     yield model
 
@@ -182,21 +175,18 @@ def register_application_models(applications,
     '''\
 A higher level registration functions for group of models located
 on application modules.
-
-It uses the :func:`stdnet.orm.model_iterator` function to iterate
-through all :class:`stdnet.orm.StdModel` models available in ``applications``
-and register them using the :func:`stdnet.orm.register` low
-level function.
+It uses the :func:`model_iterator` function to iterate
+through all :class:`StdModel` models available in ``applications``
+and register them using the :func:`register` low level function.
 
 :parameter applications: A String or a list of strings which represent
-    python dotted paths to modules containing
-    a ``models`` module where models are implemented.
+    python dotted paths where models are implemented.
 :parameter models: Optional list of models to include. If not provided
     all models found in *applications* will be included.
 :parameter app_defaults: optional dictionary which specify a model and/or
     application backend connection string.
 :parameter default: The default connection string. 
-:rtype: a generator over registered models
+:rtype: A generator over registered :class:`StdModel`.
 
 For example::
 
