# HG changeset patch # User Aurelien Campeas # Date 1271413972 -7200 # Node ID 763319a51e7280376f5dadf11ff6e682055cc09e # Parent d98fccb0da7f2cbdfc26b242a59c3d21801765a7 [doc/book] some fixes for vregistry, selectors & appobjects diff -r d98fccb0da7f -r 763319a51e72 appobject.py --- a/appobject.py Fri Apr 16 11:13:46 2010 +0200 +++ b/appobject.py Fri Apr 16 12:32:52 2010 +0200 @@ -3,6 +3,8 @@ # :contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr # :license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses """ +.. _appobject: + The `AppObject` class --------------------- diff -r d98fccb0da7f -r 763319a51e72 cwvreg.py --- a/cwvreg.py Fri Apr 16 11:13:46 2010 +0200 +++ b/cwvreg.py Fri Apr 16 12:32:52 2010 +0200 @@ -7,18 +7,19 @@ The `VRegistry` --------------- -The `VRegistry` can be seen as a two level dictionary. It contains all objects -loaded dynamically to build a |cubicweb| application. Basically: +The `VRegistry` can be seen as a two levels dictionary. It contains +all dynamically loaded objects (subclasses of :ref:`appobject`) to +build a |cubicweb| application. Basically: -* first level key return a *registry*. This key corresponds to the `__registry__` - attribute of application object classes +* the first level key returns a *registry*. This key corresponds to the + `__registry__` attribute of application object classes -* second level key return a list of application objects which share the same - identifier. This key corresponds to the `__regid__` attribute of application - object classes. +* the second level key returns a list of application objects which + share the same identifier. This key corresponds to the `__regid__` + attribute of application object classes. -A *registry* hold a specific kind of application objects. You've for instance -a registry for entity classes, another for views, etc... +A *registry* holds a specific kind of application objects. There is +for instance a registry for entity classes, another for views, etc... The `VRegistry` has two main responsibilities: @@ -27,7 +28,6 @@ - handling the registration process at startup time, and during automatic reloading in debug mode. - .. _AppObjectRecording: Details of the recording process @@ -36,21 +36,22 @@ .. index:: vregistry: registration_callback -On startup, |cubicweb| have to load application objects defined in its library -and in cubes used by the instance. Application objects from the library are -loaded first, then those provided by cubes are loaded in an ordered way (e.g. if -your cube depends on an other, objects from the dependancy will be loaded -first). Cube's modules or packages where appobject are looked at is explained in -:ref:`cubelayout`. +On startup |cubicweb| loads application objects defined in its library +and in cubes used by the instance. Application objects from the +library are loaded first, then those provided by cubes are loaded in +dependency order (e.g. if your cube depends on an other, objects from +the dependency will be loaded first). Cube's modules or packages where +appobject are looked for is explained in :ref:`cubelayout`. For each module: * by default all objects are registered automatically -* if some objects have to replace other objects, or be included only if some - condition is true, you'll have to define a `registration_callback(vreg)` - function in your module and explicitly register **all objects** in this module, - using the api defined below. +* if some objects have to replace other objects, or have to be + included only if some condition is met, you'll have to define a + `registration_callback(vreg)` function in your module and explicitly + register **all objects** in this module, using the api defined + below. .. Note:: Once the function `registration_callback(vreg)` is implemented in a module, @@ -71,7 +72,6 @@ .. automethod:: cubicweb.cwvreg.CubicWebVRegistry.register_if_interface_found .. automethod:: cubicweb.cwvreg.CubicWebVRegistry.unregister - Examples: .. sourcecode:: python @@ -115,13 +115,15 @@ Runtime objects selection ~~~~~~~~~~~~~~~~~~~~~~~~~ -Now that we've all application objects loaded, the question is : when I want some -specific object, for instance the primary view for a given entity, how do I get -the proper object ? This is what we call the **selection mechanism**. +Now that we have all application objects loaded, the question is : when +I want some specific object, for instance the primary view for a given +entity, how do I get the proper object ? This is what we call the +**selection mechanism**. As explained in the :ref:`Concepts` section: -* each application object has a **selector**, defined by its `__select__` class attribute +* each application object has a **selector**, defined by its + `__select__` class attribute * this selector is responsible to return a **score** for a given context @@ -141,9 +143,9 @@ In such cases you would need to review your design and make sure your selectors or appobjects are properly defined. -For instance, if you are selecting the primary (eg `__regid__ = 'primary'`) view (eg -`__registry__ = 'views'`) for a result set containing a `Card` entity, 2 objects -will probably be selectable: +For instance, if you are selecting the primary (eg `__regid__ = +'primary'`) view (eg `__registry__ = 'views'`) for a result set +containing a `Card` entity, two objects will probably be selectable: * the default primary view (`__select__ = implements('Any')`), meaning that the object is selectable for any kind of entity type diff -r d98fccb0da7f -r 763319a51e72 doc/book/en/admin/create-instance.rst --- a/doc/book/en/admin/create-instance.rst Fri Apr 16 11:13:46 2010 +0200 +++ b/doc/book/en/admin/create-instance.rst Fri Apr 16 12:32:52 2010 +0200 @@ -20,7 +20,7 @@ sufficient. You can anyway modify the configuration later on by editing configuration files. When a user/psswd is requested to access the database please use the login you create at the time you configured the database -(:ref:`ConfigurationPostgresql`). +(:ref:`PostgresqlConfiguration`). It is important to distinguish here the user used to access the database and the user used to login to the cubicweb instance. When an instance starts, it uses diff -r d98fccb0da7f -r 763319a51e72 doc/book/en/admin/instance-config.rst --- a/doc/book/en/admin/instance-config.rst Fri Apr 16 11:13:46 2010 +0200 +++ b/doc/book/en/admin/instance-config.rst Fri Apr 16 12:32:52 2010 +0200 @@ -157,7 +157,7 @@ :`ui.encoding`: Character encoding to use for the web -:`navigation.short-line-size`: # XXX should be in ui +:`navigation.short-line-size`: number of characters for "short" display :`navigation.page-size`: maximum number of entities to show per results page diff -r d98fccb0da7f -r 763319a51e72 doc/book/en/development/vreg.rst --- a/doc/book/en/development/vreg.rst Fri Apr 16 11:13:46 2010 +0200 +++ b/doc/book/en/development/vreg.rst Fri Apr 16 12:32:52 2010 +0200 @@ -1,16 +1,16 @@ The VRegistry, selectors and application objects ================================================ -This chapter talk about core concepts of the |cubicweb| framework, that make it -different from other framework (and probably not easy to grasp at a first -glance). You won't be able to do advanced development with |cubicweb| without -a good understanding of what's explain below. +This chapter talks about core concepts of the |cubicweb| framework, +that make it different from other frameworks (and maybe not easy to +grasp at a first glance). To be able to do advanced development with +|cubicweb| you need a good understanding of what is explained below. -This chapter goes deep into details. You don't have to remember them all but keep -it in mind so you can go back there later... +This chapter goes deep into details. You don't have to remember them +all but keep it in mind so you can go back there later. -.. toctree:: - :maxdepth: 1 +An overview of AppObjects, the VRegistry and Selectors is given in the +:ref:`VRegistryIntro` chapter. .. autodocstring:: cubicweb.cwvreg .. autodocstring:: cubicweb.selectors @@ -105,6 +105,3 @@ You'll also find some other (very) specific selectors hidden in other modules than :mod:`cubicweb.selectors`. - - -.. |cubicweb| replace:: *CubicWeb* diff -r d98fccb0da7f -r 763319a51e72 doc/book/en/intro/concepts.rst --- a/doc/book/en/intro/concepts.rst Fri Apr 16 11:13:46 2010 +0200 +++ b/doc/book/en/intro/concepts.rst Fri Apr 16 12:32:52 2010 +0200 @@ -181,8 +181,8 @@ object's `__registry__` : object's `__regid__` : [list of app objects] -E.g. The `vregistry` contains several registries which hold a list of -appobjects associated to an identifier. +E.g. the `vregistry` contains several (sub-)registries which hold a +list of appobjects associated to an identifier. The base class of appobjects is :class:`cubicweb.appobject.AppObject`. @@ -214,7 +214,6 @@ - `entities` - `views` - `sobjects` -- `hooks` Once initialized, there are three common ways to retrieve some application object @@ -238,7 +237,8 @@ The RQL query language ---------------------- -**No need for a complicated ORM when you have a powerful query language** +**No need for a complicated ORM when you have a powerful data + manipulation language** All the persistent data in a |cubicweb| instance is retrieved and modified by using the Relation Query Language. @@ -247,7 +247,7 @@ emphasize browsing relations. -db-api +DB-API ~~~~~~ The repository exposes a `db-api`_ like api but using the RQL instead of SQL. diff -r d98fccb0da7f -r 763319a51e72 doc/book/en/intro/history.rst --- a/doc/book/en/intro/history.rst Fri Apr 16 11:13:46 2010 +0200 +++ b/doc/book/en/intro/history.rst Fri Apr 16 12:32:52 2010 +0200 @@ -7,8 +7,11 @@ developing in 2001 as an offspring of its Narval_ research project. *CubicWeb* is written in Python and includes a data server and a web engine. -Its data server publishes data federated from different sources like SQL -databases, LDAP directories or even from other CubicWeb data servers. +Its data server publishes data federated from different sources like +SQL databases, LDAP directories, `VCS`_ repositories or even from other +CubicWeb data servers. + +.. _`VCS`: http://en.wikipedia.org/wiki/Revision_control Its web engine was designed to let the final user control what content to select and how to display it. It allows one to browse the federated data sources and diff -r d98fccb0da7f -r 763319a51e72 doc/book/en/tutorials/base/create-cube.rst --- a/doc/book/en/tutorials/base/create-cube.rst Fri Apr 16 11:13:46 2010 +0200 +++ b/doc/book/en/tutorials/base/create-cube.rst Fri Apr 16 12:32:52 2010 +0200 @@ -302,7 +302,7 @@ Excepted side boxes, we can see all of them already in action in the blog entry view. This is all described in more details in -:ref:`primary`. +:ref:`primary_view`. We can for example add in front of the publication date a prefix specifying that the date we see is the publication date. diff -r d98fccb0da7f -r 763319a51e72 selectors.py --- a/selectors.py Fri Apr 16 11:13:46 2010 +0200 +++ b/selectors.py Fri Apr 16 12:32:52 2010 +0200 @@ -12,37 +12,33 @@ You can combine selectors using the `&`, `|` and `~` operators. -When two selectors are combined using the `&` operator (formerly `chainall`), it -means that both should return a positive score. On success, the sum of scores is returned. +When two selectors are combined using the `&` operator, it means that +both should return a positive score. On success, the sum of scores is +returned. -When two selectors are combined using the `|` operator (former `chainfirst`), it -means that one of them should return a positive score. On success, the first +When two selectors are combined using the `|` operator, it means that +one of them should return a positive score. On success, the first positive score is returned. You can also "negate" a selector by precedeing it by the `~` unary operator. -Of course you can use parens to balance expressions. - -.. Note: - When one chains selectors, the final score is the sum of the score of each - individual selector (unless one of them returns 0, in which case the object is - non selectable) - +Of course you can use parenthesis to balance expressions. Example ~~~~~~~ -The goal: when on a Blog, one wants the RSS link to refer to blog entries, not to +The goal: when on a blog, one wants the RSS link to refer to blog entries, not to the blog entity itself. -To do that, one defines a method on entity classes that returns the RSS stream -url for a given entity. The default implementation on -:class:`~cubicweb.entities.AnyEntity` (the generic entity class used as base for -all others) and a specific implementation on Blog will do what we want. +To do that, one defines a method on entity classes that returns the +RSS stream url for a given entity. The default implementation on +:class:`~cubicweb.entities.AnyEntity` (the generic entity class used +as base for all others) and a specific implementation on `Blog` will +do what we want. -But when we have a result set containing several Blog entities (or different -entities), we don't know on which entity to call the aforementioned method. In -this case, we keep the generic behaviour. +But when we have a result set containing several `Blog` entities (or +different entities), we don't know on which entity to call the +aforementioned method. In this case, we keep the generic behaviour. Hence we have two cases here, one for a single-entity rsets, the other for multi-entities rsets. @@ -52,7 +48,7 @@ .. sourcecode:: python class RSSIconBox(ExtResourcesBoxTemplate): - '''just display the RSS icon on uniform result set''' + ''' just display the RSS icon on uniform result set ''' __select__ = ExtResourcesBoxTemplate.__select__ & non_final_entity() It takes into account: @@ -116,8 +112,9 @@ The proper way to implement this with |cubicweb| is two have two different classes sharing the same identifier but with different selectors so you'll get -the correct one according to the context: +the correct one according to the context. +.. sourcecode:: python class UserLink(component.Component): '''display a link to the connected user object with a loggout link''' @@ -137,8 +134,9 @@ # display login link ... -The big advantage, aside readibily once you're familiar with the system, is that -your cube becomes much more easily customizable by improving componentization. +The big advantage, aside readability once you're familiar with the +system, is that your cube becomes much more easily customizable by +improving componentization. .. _CustomSelectors: @@ -148,7 +146,7 @@ .. autodocstring:: cubicweb.appobject::objectify_selector -In other case, you can take a look at the following abstract base classes: +In other cases, you can take a look at the following abstract base classes: .. autoclass:: cubicweb.selectors.ExpectedValueSelector .. autoclass:: cubicweb.selectors.EClassSelector @@ -160,7 +158,7 @@ .. autofunction:: cubicweb.selectors.lltrace -.. Note:: +.. note:: Selectors __call__ should *always* return a positive integer, and shall never return `None`. @@ -254,11 +252,14 @@ .. sourcecode:: python - >>> with traced_selection( ('oid1', 'oid2') ): + >>> with traced_selection( ('regid1', 'regid2') ): ... # some code in which you want to debug selectors - ... # for objects with id 'oid1' and 'oid2' + ... # for objects with __regid__ 'regid1' and 'regid2' + A potentially usefull point to set up such a tracing function is + the `cubicweb.vregistry.Registry.select` method body. """ + def __init__(self, traced='all'): self.traced = traced