--- a/appobject.py Tue Apr 06 10:10:47 2010 +0200
+++ b/appobject.py Tue Apr 06 10:11:40 2010 +0200
@@ -1,11 +1,18 @@
-"""Base class for dynamically loaded objects accessible through the vregistry.
-
-You'll also find some convenience classes to build selectors.
+# :organization: Logilab
+# :copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
+# :contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
+# :license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
+"""
+The `AppObject` class
+---------------------
-:organization: Logilab
-:copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
-:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
-:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
+The AppObject class is the base class for all dynamically loaded objects
+(application objects) accessible through the vregistry.
+
+We can find a certain number of attributes and methods defined in this class and
+common to all the application objects.
+
+.. autoclass:: AppObject
"""
__docformat__ = "restructuredtext en"
@@ -21,13 +28,17 @@
# selector base classes and operations ########################################
def objectify_selector(selector_func):
- """convenience decorator for simple selectors where a class definition
- would be overkill::
+ """Most of the time, a simple score function is enough to build a selector.
+ The :func:`objectify_selector` decorator turn it into a proper selector
+ class::
@objectify_selector
def one(cls, *args, **kwargs):
return 1
+ class MyView(View):
+ __select__ = View.__select__ & one()
+
"""
return type(selector_func.__name__, (Selector,),
{'__doc__': selector_func.__doc__,
@@ -49,7 +60,7 @@
class Selector(object):
"""base class for selector classes providing implementation
- for operators ``&`` and ``|``
+ for operators ``&``, ``|`` and ``~``
This class is only here to give access to binary operators, the
selector logic itself should be implemented in the __call__ method
@@ -205,42 +216,77 @@
selected according to a context (usually at least a request and a result
set).
- Concrete application objects classes are designed to be loaded by the
- vregistry and should be accessed through it, not by direct instantiation.
+ The following attributes should be set on concret appobject classes:
- The following attributes should be set on concret appobject classes:
- :__registry__:
+ :attr:`__registry__`
name of the registry for this object (string like 'views',
'templates'...)
- :__regid__:
+
+ :attr:`__regid__`
object's identifier in the registry (string like 'main',
'primary', 'folder_box')
- :__select__:
+
+ :attr:`__select__`
class'selector
- Moreover, the `__abstract__` attribute may be set to True to indicate
- that a appobject is abstract and should not be registered.
+ Moreover, the `__abstract__` attribute may be set to True to indicate that a
+ class is abstract and should not be registered.
At selection time, the following attributes are set on the instance:
- :_cw:
+ :attr:`_cw`
current request
- :cw_extra_kwargs:
+ :attr:`cw_extra_kwargs`
other received arguments
- only if rset is found in arguments (in which case rset/row/col will be
- removed from cwextra_kwargs):
+ And also the following, only if `rset` is found in arguments (in which case
+ rset/row/col will be removed from `cwextra_kwargs`):
- :cw_rset:
+ :attr:`cw_rset`
context result set or None
- :cw_row:
+
+ :attr:`cw_row`
if a result set is set and the context is about a particular cell in the
result set, and not the result set as a whole, specify the row number we
are interested in, else None
- :cw_col:
+
+ :attr:`cw_col`
if a result set is set and the context is about a particular cell in the
result set, and not the result set as a whole, specify the col number we
are interested in, else None
+
+
+ .. Note::
+
+ * do not inherit directly from this class but from a more specific class
+ such as `AnyEntity`, `EntityView`, `AnyRsetView`, `Action`...
+
+ * to be recordable, a subclass has to define its registry (attribute
+ `__registry__`) and its identifier (attribute `__regid__`). Usually
+ you don't have to take care of the registry since it's set by the base
+ class, only the identifier `id`
+
+ * application objects are designed to be loaded by the vregistry and
+ should be accessed through it, not by direct instantiation, besides
+ to use it as base classe.
+
+
+ * When we inherit from `AppObject` (even not directly), you *always* have
+ to use **super()** to get the methods and attributes of the superclasses,
+ and not use the class identifier.
+
+ For example, instead of writting::
+
+ class Truc(PrimaryView):
+ def f(self, arg1):
+ PrimaryView.f(self, arg1)
+
+ You must write::
+
+ class Truc(PrimaryView):
+ def f(self, arg1):
+ super(Truc, self).f(arg1)
+
"""
__registry__ = None
__regid__ = None