doc/book/devrepo/vreg.rst
author Nicolas Chauvat <nicolas.chauvat@logilab.fr>
Wed, 19 Feb 2020 19:49:01 +0100
changeset 12888 24a20d2b8c84
parent 12879 7347715bf0ee
permissions -rw-r--r--
[server.querier] remove useless attribute Querier._planner
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
     1
The Registry, selectors and application objects
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
     2
===============================================
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
     3
5608
f9ab62103ad4 proof read documentation
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 5394
diff changeset
     4
This chapter deals with some of the  core concepts of the |cubicweb| framework
f9ab62103ad4 proof read documentation
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 5394
diff changeset
     5
which make it different from other frameworks (and maybe not easy to
5306
763319a51e72 [doc/book] some fixes for vregistry, selectors & appobjects
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5147
diff changeset
     6
grasp at a first glance). To be able to do advanced development with
763319a51e72 [doc/book] some fixes for vregistry, selectors & appobjects
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5147
diff changeset
     7
|cubicweb| you need a good understanding of what is explained below.
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
     8
5306
763319a51e72 [doc/book] some fixes for vregistry, selectors & appobjects
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5147
diff changeset
     9
This chapter goes deep into details. You don't have to remember them
763319a51e72 [doc/book] some fixes for vregistry, selectors & appobjects
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5147
diff changeset
    10
all but keep it in mind so you can go back there later.
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    11
5306
763319a51e72 [doc/book] some fixes for vregistry, selectors & appobjects
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5147
diff changeset
    12
An overview of AppObjects, the VRegistry and Selectors is given in the
763319a51e72 [doc/book] some fixes for vregistry, selectors & appobjects
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5147
diff changeset
    13
:ref:`VRegistryIntro` chapter.
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    14
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    15
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    16
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    17
The :class:`CWRegistryStore`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    18
----------------------------
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    19
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    20
The :class:`CWRegistryStore <cubicweb.cwvreg.CWRegistryStore>` can be
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    21
seen as a two-level dictionary. It contains all dynamically loaded
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    22
objects (subclasses of :class:`AppObject <cubicweb.appobject.AppObject>`)
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    23
to build a |cubicweb| application. Basically:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    24
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    25
* the first level key returns a *registry*. This key corresponds to the
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    26
  `__registry__` attribute of application object classes
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    27
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    28
* the second level key returns a list of application objects which
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    29
  share the same identifier. This key corresponds to the `__regid__`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    30
  attribute of application object classes.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    31
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    32
A *registry* holds a specific kind of application objects. There is
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    33
for instance a registry for entity classes, another for views, etc...
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    34
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    35
The :class:`CWRegistryStore <cubicweb.cwvreg.CWRegistryStore>` has two
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    36
main responsibilities:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    37
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    38
- being the access point to all registries
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    39
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    40
- handling the registration process at startup time, and during automatic
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    41
  reloading in debug mode.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    42
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    43
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    44
Details of the recording process
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    45
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    46
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    47
.. index::
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    48
   vregistry: registration_callback
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    49
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    50
On startup, |cubicweb| loads application objects defined in its library
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    51
and in cubes used by the instance. Application objects from the
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    52
library are loaded first, then those provided by cubes are loaded in
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    53
dependency order (e.g. if your cube depends on an other, objects from
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    54
the dependency will be loaded first). The layout of the modules or packages
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    55
in a cube  is explained in :ref:`cubelayout`.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    56
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    57
For each module:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    58
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    59
* by default all objects are registered automatically
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    60
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    61
* if some objects have to replace other objects, or have to be
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    62
  included only if some condition is met, you'll have to define a
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    63
  `registration_callback(vreg)` function in your module and explicitly
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    64
  register **all objects** in this module, using the api defined
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    65
  below.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    66
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    67
.. Note::
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    68
    Once the function `registration_callback(vreg)` is implemented in a module,
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    69
    all the objects from this module have to be explicitly registered as it
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    70
    disables the automatic objects registration.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    71
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    72
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    73
API for objects registration
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    74
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    75
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    76
Here are the registration methods that you can use in the
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    77
`registration_callback` to register your objects to the
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    78
:class:`CWRegistryStore` instance given as argument (usually named
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    79
`vreg`):
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    80
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    81
- :py:meth:`register_all() <cubicweb.cwvreg.CWRegistryStore.register_all>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    82
- :py:meth:`register_and_replace() <cubicweb.cwvreg.CWRegistryStore.register_and_replace>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    83
- :py:meth:`register() <cubicweb.cwvreg.CWRegistryStore.register>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    84
- :py:meth:`unregister() <logilab.common.registry.RegistryStore.unregister>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    85
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    86
Examples:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    87
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    88
.. sourcecode:: python
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    89
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    90
   # web/views/basecomponents.py
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    91
   def registration_callback(vreg):
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    92
      # register everything in the module except SeeAlsoComponent
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    93
      vreg.register_all(globals().itervalues(), __name__, (SeeAlsoVComponent,))
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    94
      # conditionally register SeeAlsoVComponent
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    95
      if 'see_also' in vreg.schema:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    96
          vreg.register(SeeAlsoVComponent)
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    97
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    98
In this example, we register all application object classes defined in the module
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
    99
except `SeeAlsoVComponent`. This class is then registered only if the 'see_also'
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   100
relation type is defined in the instance'schema.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   101
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   102
.. sourcecode:: python
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   103
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   104
   # goa/appobjects/sessions.py
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   105
   def registration_callback(vreg):
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   106
      vreg.register(SessionsCleaner)
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   107
      # replace AuthenticationManager by GAEAuthenticationManager
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   108
      vreg.register_and_replace(GAEAuthenticationManager, AuthenticationManager)
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   109
      # replace PersistentSessionManager by GAEPersistentSessionManager
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   110
      vreg.register_and_replace(GAEPersistentSessionManager, PersistentSessionManager)
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   111
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   112
In this example, we explicitly register classes one by one:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   113
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   114
* the `SessionCleaner` class
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   115
* the `GAEAuthenticationManager` to replace the `AuthenticationManager`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   116
* the `GAEPersistentSessionManager` to replace the `PersistentSessionManager`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   117
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   118
If at some point we register a new appobject class in this module, it won't be
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   119
registered at all without modification to the `registration_callback`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   120
implementation. The previous example will register it though, thanks to the call
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   121
to the `register_all` method.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   122
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   123
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   124
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   125
Runtime objects selection
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   126
~~~~~~~~~~~~~~~~~~~~~~~~~
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   127
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   128
Now that we have all application objects loaded, the question is : when
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   129
I want some specific object, for instance the primary view for a given
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   130
entity, how do I get the proper object ? This is what we call the
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   131
**selection mechanism**.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   132
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   133
As explained in the :ref:`Concepts` section:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   134
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   135
* each application object has a **selector**, defined by its
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   136
  `__select__` class attribute
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   137
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   138
* this selector is responsible to return a **score** for a given context
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   139
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   140
  - 0 score means the object doesn't apply to this context
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   141
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   142
  - else, the higher the score, the better the object suits the context
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   143
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   144
* the object with the highest score is selected.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   145
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   146
.. Note::
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   147
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   148
  When no single object has the highest score, an exception is raised in development
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   149
  mode to let you know that the engine was not able to identify the view to
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   150
  apply. This error is silenced in production mode and one of the objects with
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   151
  the highest score is picked.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   152
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   153
  In such cases you would need to review your design and make sure
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   154
  your selectors or appobjects are properly defined. Such an error is
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   155
  typically caused by either forgetting to change the __regid__ in a
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   156
  derived class, or by having copy-pasted some code.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   157
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   158
For instance, if you are selecting the primary (`__regid__ =
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   159
'primary'`) view (`__registry__ = 'views'`) for a result set
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   160
containing a `Card` entity, two objects will probably be selectable:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   161
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   162
* the default primary view (`__select__ = is_instance('Any')`), meaning
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   163
  that the object is selectable for any kind of entity type
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   164
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   165
* the specific `Card` primary view (`__select__ = is_instance('Card')`,
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   166
  meaning that the object is selectable for Card entities
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   167
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   168
Other primary views specific to other entity types won't be selectable in this
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   169
case. Among selectable objects, the `is_instance('Card')` selector will return a higher
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   170
score since it's more specific, so the correct view will be selected as expected.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   171
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   172
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   173
API for objects selections
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   174
~~~~~~~~~~~~~~~~~~~~~~~~~~
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   175
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   176
Here is the selection API you'll get on every registry. Some of them, as the
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   177
'etypes' registry, containing entity classes, extend it. In those methods,
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   178
`*args, **kwargs` is what we call the **context**. Those arguments are given to
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   179
selectors that will inspect their content and return a score accordingly.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   180
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   181
:py:meth:`select() <logilab.common.registry.Registry.select>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   182
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   183
:py:meth:`select_or_none() <logilab.common.registry.Registry.select_or_none>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   184
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   185
:py:meth:`possible_objects() <logilab.common.registry.Registry.possible_objects>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   186
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   187
:py:meth:`object_by_id() <logilab.common.registry.Registry.object_by_id>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   188
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   189
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   190
The `AppObject` class
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   191
---------------------
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   192
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   193
The :py:class:`cubicweb.appobject.AppObject` class is the base class
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   194
for all dynamically loaded objects (application objects) accessible
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   195
through the :py:class:`cubicweb.cwvreg.CWRegistryStore`.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   196
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   197
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   198
Predicates and selectors
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   199
------------------------
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   200
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   201
Predicates are scoring functions that are called by the registry to tell whenever
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   202
an appobject can be selected in a given context. Predicates may be chained
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   203
together using operators to build a selector. A selector is the glue that tie
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   204
views to the data model or whatever input context. Using them appropriately is an
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   205
essential part of the construction of well behaved cubes.
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   206
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   207
Of course you may have to write your own set of predicates as your needs grows
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   208
and you get familiar with the framework (see :ref:`CustomPredicates`).
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   209
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   210
A predicate is a class testing a particular aspect of a context. A selector is
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   211
built by combining existant predicates or even selectors.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   212
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   213
Using and combining existant predicates
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   214
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   215
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   216
You can combine predicates using the `&`, `|` and `~` operators.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   217
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   218
When two predicates are combined using the `&` operator, it means that
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   219
both should return a positive score. On success, the sum of scores is
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   220
returned.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   221
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   222
When two predicates are combined using the `|` operator, it means that
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   223
one of them should return a positive score. On success, the first
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   224
positive score is returned.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   225
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   226
You can also "negate" a predicate by precedeing it by the `~` unary operator.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   227
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   228
Of course you can use parenthesis to balance expressions.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   229
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   230
Example
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   231
~~~~~~~
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   232
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   233
The goal: when on a blog, one wants the RSS link to refer to blog entries, not to
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   234
the blog entity itself.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   235
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   236
To do that, one defines a method on entity classes that returns the
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   237
RSS stream url for a given entity. The default implementation on
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   238
:class:`~cubicweb.entities.AnyEntity` (the generic entity class used
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   239
as base for all others) and a specific implementation on `Blog` will
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   240
do what we want.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   241
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   242
But when we have a result set containing several `Blog` entities (or
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   243
different entities), we don't know on which entity to call the
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   244
aforementioned method. In this case, we keep the generic behaviour.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   245
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   246
Hence we have two cases here, one for a single-entity rsets, the other for
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   247
multi-entities rsets.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   248
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   249
In web/views/boxes.py lies the RSSIconBox class. Look at its selector:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   250
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   251
.. sourcecode:: python
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   252
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   253
  class RSSIconBox(box.Box):
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   254
    ''' just display the RSS icon on uniform result set '''
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   255
    __select__ = box.Box.__select__ & non_final_entity()
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   256
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   257
It takes into account:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   258
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   259
* the inherited selection criteria (one has to look them up in the class
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   260
  hierarchy to know the details)
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   261
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   262
* :class:`~cubicweb.predicates.non_final_entity`, which filters on result sets
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   263
  containing non final entities (a 'final entity' being synonym for entity
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   264
  attributes type, eg `String`, `Int`, etc)
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   265
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   266
This matches our second case. Hence we have to provide a specific component for
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   267
the first case:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   268
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   269
.. sourcecode:: python
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   270
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   271
  class EntityRSSIconBox(RSSIconBox):
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   272
    '''just display the RSS icon on uniform result set for a single entity'''
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   273
    __select__ = RSSIconBox.__select__ & one_line_rset()
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   274
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   275
Here, one adds the :class:`~cubicweb.predicates.one_line_rset` predicate, which
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   276
filters result sets of size 1. Thus, on a result set containing multiple
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   277
entities, :class:`one_line_rset` makes the EntityRSSIconBox class non
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   278
selectable. However for a result set with one entity, the `EntityRSSIconBox`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   279
class will have a higher score than `RSSIconBox`, which is what we wanted.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   280
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   281
Of course, once this is done, you have to:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   282
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   283
* fill in the call method of `EntityRSSIconBox`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   284
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   285
* provide the default implementation of the method returning the RSS stream url
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   286
  on :class:`~cubicweb.entities.AnyEntity`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   287
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   288
* redefine this method on `Blog`.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   289
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   290
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   291
When to use selectors?
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   292
~~~~~~~~~~~~~~~~~~~~~~
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   293
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   294
Selectors are to be used whenever arises the need of dispatching on the shape or
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   295
content of a result set or whatever else context (value in request form params,
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   296
authenticated user groups, etc...). That is, almost all the time.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   297
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   298
Here is a quick example:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   299
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   300
.. sourcecode:: python
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   301
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   302
    class UserLink(component.Component):
12879
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   303
        '''if the user is the anonymous user, build a link to login else a link
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   304
        to the connected user object with a logout link
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   305
        '''
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   306
        __regid__ = 'loggeduserlink'
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   307
12879
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   308
        def call(self):
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   309
            if self._cw.session.anonymous_session:
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   310
                # display login link
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   311
                ...
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   312
            else:
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   313
                # display a link to the connected user object with a loggout link
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   314
                ...
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   315
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   316
The proper way to implement this with |cubicweb| is two have two different
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   317
classes sharing the same identifier but with different selectors so you'll get
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   318
the correct one according to the context.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   319
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   320
.. sourcecode:: python
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   321
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   322
    class UserLink(component.Component):
12879
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   323
        '''display a link to the connected user object with a loggout link'''
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   324
        __regid__ = 'loggeduserlink'
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   325
        __select__ = component.Component.__select__ & authenticated_user()
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   326
12879
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   327
        def call(self):
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   328
            # display useractions and siteactions
12879
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   329
            ...
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   330
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   331
    class AnonUserLink(component.Component):
12879
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   332
        '''build a link to login'''
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   333
        __regid__ = 'loggeduserlink'
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   334
        __select__ = component.Component.__select__ & anonymous_user()
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   335
12879
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   336
        def call(self):
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 10499
diff changeset
   337
            # display login link
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   338
            ...
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   339
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   340
The big advantage, aside readability once you're familiar with the
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   341
system, is that your cube becomes much more easily customizable by
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   342
improving componentization.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   343
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   344
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   345
.. _CustomPredicates:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   346
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   347
Defining your own predicates
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   348
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   349
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   350
You can use the :py:func:`objectify_predicate <logilab.common.registry.objectify_predicate>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   351
decorator to easily write your own predicates as simple python
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   352
functions.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   353
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   354
In other cases, you can take a look at the following abstract base classes:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   355
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   356
- :py:class:`ExpectedValuePredicate <cubicweb.predicates.ExpectedValuePredicate>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   357
- :py:class:`EClassPredicate <cubicweb.predicates.EClassPredicate>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   358
- :py:class:`EntityPredicate <cubicweb.predicates.EntityPredicate>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   359
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   360
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   361
.. _DebuggingSelectors:
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   362
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   363
Debugging selection
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   364
~~~~~~~~~~~~~~~~~~~
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   365
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   366
Once in a while, one needs to understand why a view (or any
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   367
application object) is, or is not selected appropriately. Looking at
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   368
which predicates fired (or did not) is the way. The
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   369
:class:`traced_selection <logilab.common.registry.traced_selection>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   370
context manager to help with that, *if you're running your instance in
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   371
debug mode*.
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   372
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   373
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   374
Base predicates
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   375
---------------
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   376
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   377
Here is a description of generic predicates provided by CubicWeb that should suit
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   378
most of your needs.
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   379
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   380
Bare predicates
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   381
~~~~~~~~~~~~~~~
10496
e95b559a06a2 [doc] more fixes of warnings/errors in doc build
David Douard <david.douard@logilab.fr>
parents: 10491
diff changeset
   382
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   383
Those predicates are somewhat dumb, which doesn't mean they're not (very) useful.
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   384
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   385
- :py:class:`yes <cubicweb.appobject.yes>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   386
- :py:class:`match_kwargs <cubicweb.predicates.match_kwargs>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   387
- :py:class:`appobject_selectable <cubicweb.predicates.appobject_selectable>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   388
- :py:class:`adaptable <cubicweb.predicates.adaptable>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   389
- :py:class:`configuration_values <cubicweb.predicates.configuration_values>`
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   390
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   391
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   392
Result set predicates
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   393
~~~~~~~~~~~~~~~~~~~~~
10496
e95b559a06a2 [doc] more fixes of warnings/errors in doc build
David Douard <david.douard@logilab.fr>
parents: 10491
diff changeset
   394
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   395
Those predicates are looking for a result set in the context ('rset' argument or
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   396
the input context) and match or not according to its shape. Some of these
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   397
predicates have different behaviour if a particular cell of the result set is
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   398
specified using 'row' and 'col' arguments of the input context or not.
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   399
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   400
- :py:class:`none_rset <cubicweb.predicates.none_rset>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   401
- :py:class:`any_rset <cubicweb.predicates.any_rset>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   402
- :py:class:`nonempty_rset <cubicweb.predicates.nonempty_rset>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   403
- :py:class:`empty_rset <cubicweb.predicates.empty_rset>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   404
- :py:class:`one_line_rset <cubicweb.predicates.one_line_rset>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   405
- :py:class:`multi_lines_rset <cubicweb.predicates.multi_lines_rset>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   406
- :py:class:`multi_columns_rset <cubicweb.predicates.multi_columns_rset>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   407
- :py:class:`paginated_rset <cubicweb.predicates.paginated_rset>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   408
- :py:class:`sorted_rset <cubicweb.predicates.sorted_rset>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   409
- :py:class:`one_etype_rset <cubicweb.predicates.one_etype_rset>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   410
- :py:class:`multi_etypes_rset <cubicweb.predicates.multi_etypes_rset>`
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   411
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   412
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   413
Entity predicates
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   414
~~~~~~~~~~~~~~~~~
10496
e95b559a06a2 [doc] more fixes of warnings/errors in doc build
David Douard <david.douard@logilab.fr>
parents: 10491
diff changeset
   415
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   416
Those predicates are looking for either an `entity` argument in the input context,
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   417
or entity found in the result set ('rset' argument or the input context) and
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   418
match or not according to entity's (instance or class) properties.
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   419
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   420
- :py:class:`non_final_entity <cubicweb.predicates.non_final_entity>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   421
- :py:class:`is_instance <cubicweb.predicates.is_instance>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   422
- :py:class:`score_entity <cubicweb.predicates.score_entity>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   423
- :py:class:`rql_condition <cubicweb.predicates.rql_condition>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   424
- :py:class:`relation_possible <cubicweb.predicates.relation_possible>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   425
- :py:class:`partial_relation_possible <cubicweb.predicates.partial_relation_possible>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   426
- :py:class:`has_related_entities <cubicweb.predicates.has_related_entities>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   427
- :py:class:`partial_has_related_entities <cubicweb.predicates.partial_has_related_entities>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   428
- :py:class:`has_permission <cubicweb.predicates.has_permission>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   429
- :py:class:`has_add_permission <cubicweb.predicates.has_add_permission>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   430
- :py:class:`has_mimetype <cubicweb.predicates.has_mimetype>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   431
- :py:class:`is_in_state <cubicweb.predicates.is_in_state>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   432
- :py:func:`on_fire_transition <cubicweb.predicates.on_fire_transition>`
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   433
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   434
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   435
Logged user predicates
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   436
~~~~~~~~~~~~~~~~~~~~~~
10496
e95b559a06a2 [doc] more fixes of warnings/errors in doc build
David Douard <david.douard@logilab.fr>
parents: 10491
diff changeset
   437
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   438
Those predicates are looking for properties of the user issuing the request.
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   439
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   440
- :py:class:`match_user_groups <cubicweb.predicates.match_user_groups>`
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   441
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   442
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   443
Web request predicates
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   444
~~~~~~~~~~~~~~~~~~~~~~
10496
e95b559a06a2 [doc] more fixes of warnings/errors in doc build
David Douard <david.douard@logilab.fr>
parents: 10491
diff changeset
   445
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   446
Those predicates are looking for properties of *web* request, they can not be
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   447
used on the data repository side.
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   448
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   449
- :py:class:`no_cnx <cubicweb.predicates.no_cnx>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   450
- :py:class:`anonymous_user <cubicweb.predicates.anonymous_user>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   451
- :py:class:`authenticated_user <cubicweb.predicates.authenticated_user>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   452
- :py:class:`match_form_params <cubicweb.predicates.match_form_params>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   453
- :py:class:`match_search_state <cubicweb.predicates.match_search_state>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   454
- :py:class:`match_context_prop <cubicweb.predicates.match_context_prop>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   455
- :py:class:`match_context <cubicweb.predicates.match_context>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   456
- :py:class:`match_view <cubicweb.predicates.match_view>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   457
- :py:class:`primary_view <cubicweb.predicates.primary_view>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   458
- :py:class:`contextual <cubicweb.predicates.contextual>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   459
- :py:class:`specified_etype_implements <cubicweb.predicates.specified_etype_implements>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   460
- :py:class:`attribute_edited <cubicweb.predicates.attribute_edited>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   461
- :py:class:`match_transition <cubicweb.predicates.match_transition>`
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   462
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   463
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   464
Other predicates
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   465
~~~~~~~~~~~~~~~~
10499
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   466
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   467
- :py:class:`match_exception <cubicweb.predicates.match_exception>`
d0907690af55 [doc] move the documentations from docstring directly to the book.
David Douard <david.douard@logilab.fr>
parents: 10496
diff changeset
   468
- :py:class:`debug_mode <cubicweb.predicates.debug_mode>`
5147
70181998897f more / cleaner / in code documentation of vreg, selectors and appobject
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   469
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   470
You'll also find some other (very) specific predicates hidden in other modules
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7955
diff changeset
   471
than :mod:`cubicweb.predicates`.