doc/book/devrepo/repo/hooks.rst
author Denis Laxalde <denis.laxalde@logilab.fr>
Tue, 02 Oct 2018 16:04:52 +0200
branch3.26
changeset 12352 1a0159426def
parent 10491 c67bcee93248
child 12621 092d201a7c17
permissions -rw-r--r--
[doc] Do not rely on lgc's sphinx_ext This module is broken (getting an ImportError) and I don't want to fix it. The only usage we make of it is for the "autodocstring" directive, and I don't know what it does. Based on the context, replacing autodocstring with either automodule or autoclass and removing sphinx_ext from required Sphinx extensions.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     2
.. _hooks:
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     3
5191
6d182c7d4392 [doc/book] begin chapter on Hooks/Operations
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2172
diff changeset
     4
Hooks and Operations
6d182c7d4392 [doc/book] begin chapter on Hooks/Operations
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2172
diff changeset
     5
====================
6d182c7d4392 [doc/book] begin chapter on Hooks/Operations
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2172
diff changeset
     6
12352
1a0159426def [doc] Do not rely on lgc's sphinx_ext
Denis Laxalde <denis.laxalde@logilab.fr>
parents: 10491
diff changeset
     7
.. automodule:: cubicweb.server.hook
5191
6d182c7d4392 [doc/book] begin chapter on Hooks/Operations
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2172
diff changeset
     8
6d182c7d4392 [doc/book] begin chapter on Hooks/Operations
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2172
diff changeset
     9
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    10
Example using dataflow hooks
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    11
----------------------------
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
    12
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    13
We will use a very simple example to show hooks usage. Let us start with the
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    14
following schema.
5202
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    15
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    16
.. sourcecode:: python
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    17
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    18
   class Person(EntityType):
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    19
       age = Int(required=True)
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    20
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    21
We would like to add a range constraint over a person's age. Let's write an hook
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    22
(supposing yams can not handle this nativly, which is wrong). It shall be placed
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    23
into `mycube/hooks.py`. If this file were to grow too much, we can easily have a
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    24
`mycube/hooks/... package` containing hooks in various modules.
5202
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    25
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    26
.. sourcecode:: python
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    27
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    28
   from cubicweb import ValidationError
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 8062
diff changeset
    29
   from cubicweb.predicates import is_instance
5202
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    30
   from cubicweb.server.hook import Hook
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    31
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    32
   class PersonAgeRange(Hook):
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    33
        __regid__ = 'person_age_range'
6366
1806148d6ce8 backport stable
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6162 6344
diff changeset
    34
        __select__ = Hook.__select__ & is_instance('Person')
5202
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    35
        events = ('before_add_entity', 'before_update_entity')
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    36
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    37
        def __call__(self):
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    38
	    if 'age' in self.entity.cw_edited:
6162
76bd320c5ace backport stable
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6147 6152
diff changeset
    39
                if 0 <= self.entity.age <= 120:
76bd320c5ace backport stable
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6147 6152
diff changeset
    40
                   return
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    41
		msg = self._cw._('age must be between 0 and 120')
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    42
		raise ValidationError(self.entity.eid, {'age': msg})
5202
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    43
6162
76bd320c5ace backport stable
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6147 6152
diff changeset
    44
In our example the base `__select__` is augmented with an `is_instance` selector
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    45
matching the desired entity type.
5202
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    46
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    47
The `events` tuple is used specify that our hook should be called before the
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    48
entity is added or updated.
5202
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    49
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    50
Then in the hook's `__call__` method, we:
5202
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    51
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    52
* check if the 'age' attribute is edited
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    53
* if so, check the value is in the range
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    54
* if not, raise a validation error properly
5202
4a77da652759 [doc/book] more about hooks (simple examples with entities and relations)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5191
diff changeset
    55
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    56
Now Let's augment our schema with new `Company` entity type with some relation to
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    57
`Person` (in 'mycube/schema.py').
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
    58
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
    59
.. sourcecode:: python
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
    60
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
    61
   class Company(EntityType):
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
    62
        name = String(required=True)
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
    63
        boss = SubjectRelation('Person', cardinality='1*')
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
    64
        subsidiary_of = SubjectRelation('Company', cardinality='*?')
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
    65
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    66
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    67
We would like to constrain the company's bosses to have a minimum (legal)
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    68
age. Let's write an hook for this, which will be fired when the `boss` relation
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    69
is established (still supposing we could not specify that kind of thing in the
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    70
schema).
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    71
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    72
.. sourcecode:: python
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    73
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    74
   class CompanyBossLegalAge(Hook):
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    75
        __regid__ = 'company_boss_legal_age'
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    76
        __select__ = Hook.__select__ & match_rtype('boss')
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    77
        events = ('before_add_relation',)
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
    78
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    79
        def __call__(self):
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    80
            boss = self._cw.entity_from_eid(self.eidto)
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    81
            if boss.age < 18:
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    82
                msg = self._cw._('the minimum age for a boss is 18')
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    83
                raise ValidationError(self.eidfrom, {'boss': msg})
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    84
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    85
.. Note::
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    86
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    87
    We use the :class:`~cubicweb.server.hook.match_rtype` selector to select the
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    88
    proper relation type.
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    89
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    90
    The essential difference with respect to an entity hook is that there is no
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    91
    self.entity, but `self.eidfrom` and `self.eidto` hook attributes which
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    92
    represent the subject and object **eid** of the relation.
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    93
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    94
Suppose we want to check that there is no cycle by the `subsidiary_of`
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    95
relation. This is best achieved in an operation since all relations are likely to
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
    96
be set at commit time.
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
    97
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
    98
.. sourcecode:: python
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
    99
6756
46297c498842 [doc/book] add missing mixin
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6753
diff changeset
   100
    from cubicweb.server.hook import Hook, DataOperationMixIn, Operation, match_rtype
6344
0cb0d8d83e4c [book] add a link in hooks section to test, talk about create_entity in tests section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6152
diff changeset
   101
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   102
    def check_cycle(self, session, eid, rtype, role='subject'):
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   103
        parents = set([eid])
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   104
        parent = session.entity_from_eid(eid)
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   105
        while parent.related(rtype, role):
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   106
            parent = parent.related(rtype, role)[0]
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   107
            if parent.eid in parents:
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   108
                msg = session._('detected %s cycle' % rtype)
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   109
                raise ValidationError(eid, {rtype: msg})
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   110
            parents.add(parent.eid)
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   111
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   112
8062
ffd510fb71da [doc] fix data hooks parent class in Hooks doc.
Anthony Truchet <anthony.truchet@logilab.fr>
parents: 6756
diff changeset
   113
    class CheckSubsidiaryCycleOp(Operation):
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   114
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   115
        def precommit_event(self):
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   116
            check_cycle(self.session, self.eidto, 'subsidiary_of')
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   117
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   118
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   119
    class CheckSubsidiaryCycleHook(Hook):
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   120
        __regid__ = 'check_no_subsidiary_cycle'
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   121
        __select__ = Hook.__select__ & match_rtype('subsidiary_of')
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   122
        events = ('after_add_relation',)
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   123
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   124
        def __call__(self):
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   125
            CheckSubsidiaryCycleOp(self._cw, eidto=self.eidto)
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   126
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   127
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   128
Like in hooks, :exc:`~cubicweb.ValidationError` can be raised in operations. Other
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   129
exceptions are usually programming errors.
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   130
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   131
In the above example, our hook will instantiate an operation each time the hook
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   132
is called, i.e. each time the `subsidiary_of` relation is set. There is an
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   133
alternative method to schedule an operation from a hook, using the
6753
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   134
:func:`get_instance` class method.
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   135
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   136
.. sourcecode:: python
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   137
5231
40f53867e332 [doc/book] misc fixes/enhancements & notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5221
diff changeset
   138
   from cubicweb.server.hook import set_operation
40f53867e332 [doc/book] misc fixes/enhancements & notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5221
diff changeset
   139
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   140
   class CheckSubsidiaryCycleHook(Hook):
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   141
       __regid__ = 'check_no_subsidiary_cycle'
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   142
       events = ('after_add_relation',)
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   143
       __select__ = Hook.__select__ & match_rtype('subsidiary_of')
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   144
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   145
       def __call__(self):
6753
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   146
           CheckSubsidiaryCycleOp.get_instance(self._cw).add_data(self.eidto)
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   147
8062
ffd510fb71da [doc] fix data hooks parent class in Hooks doc.
Anthony Truchet <anthony.truchet@logilab.fr>
parents: 6756
diff changeset
   148
   class CheckSubsidiaryCycleOp(DataOperationMixIn, Operation):
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   149
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   150
       def precommit_event(self):
6753
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   151
           for eid in self.get_data():
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   152
               check_cycle(self.session, eid, self.rtype)
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   153
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   154
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   155
Here, we call :func:`set_operation` so that we will simply accumulate eids of
6366
1806148d6ce8 backport stable
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6162 6344
diff changeset
   156
entities to check at the end in a single `CheckSubsidiaryCycleOp`
1806148d6ce8 backport stable
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6162 6344
diff changeset
   157
operation. Value are stored in a set associated to the
1806148d6ce8 backport stable
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6162 6344
diff changeset
   158
'subsidiary_cycle_detection' transaction data key. The set initialization and
1806148d6ce8 backport stable
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6162 6344
diff changeset
   159
operation creation are handled nicely by :func:`set_operation`.
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   160
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   161
A more realistic example can be found in the advanced tutorial chapter
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   162
:ref:`adv_tuto_security_propagation`.
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   163
5259
61505346e28f [doc/book] add a ref from hooks to adv tutorial
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5231
diff changeset
   164
8211
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   165
Inter-instance communication
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   166
----------------------------
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   167
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   168
If your application consists of several instances, you may need some means to
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   169
communicate between them.  Cubicweb provides a publish/subscribe mechanism
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   170
using ØMQ_.  In order to use it, use
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   171
:meth:`~cubicweb.server.cwzmq.ZMQComm.add_subscription` on the
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   172
`repo.app_instances_bus` object.  The `callback` will get the message (as a
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   173
list).  A message can be sent by calling
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   174
:meth:`~cubicweb.server.cwzmq.ZMQComm.publish` on `repo.app_instances_bus`.
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   175
The first element of the message is the topic which is used for filtering and
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   176
dispatching messages.
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   177
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   178
.. _ØMQ: http://www.zeromq.org/
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   179
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   180
.. sourcecode:: python
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   181
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   182
  class FooHook(hook.Hook):
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   183
      events = ('server_startup',)
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   184
      __regid__ = 'foo_startup'
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   185
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   186
      def __call__(self):
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   187
          def callback(msg):
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   188
              self.info('received message: %s', ' '.join(msg))
8981
26fddf8d65d0 Fix documentation for zmq pub/sub hooks and configuration
Julien Cristau <julien.cristau@logilab.fr>
parents: 8670
diff changeset
   189
          self.repo.app_instances_bus.add_subscription('hello', callback)
8211
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   190
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   191
.. sourcecode:: python
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   192
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   193
  def do_foo(self):
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   194
      actually_do_foo()
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   195
      self._cw.repo.app_instances_bus.publish(['hello', 'world'])
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   196
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   197
The `zmq-address-pub` configuration variable contains the address used
8981
26fddf8d65d0 Fix documentation for zmq pub/sub hooks and configuration
Julien Cristau <julien.cristau@logilab.fr>
parents: 8670
diff changeset
   198
by the instance for sending messages, e.g. `tcp://*:1234`.  The
8211
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   199
`zmq-address-sub` variable contains a comma-separated list of addresses
8981
26fddf8d65d0 Fix documentation for zmq pub/sub hooks and configuration
Julien Cristau <julien.cristau@logilab.fr>
parents: 8670
diff changeset
   200
to listen on, e.g. `tcp://localhost:1234, tcp://192.168.1.1:2345`.
8211
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   201
543e1579ba0d [repo] Add a publish/subscribe mechanism for inter-instance communication using zmq
Julien Cristau <julien.cristau@logilab.fr>, Quentin Roquefort <quentin@kpsule.me>
parents: 8190
diff changeset
   202
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   203
Hooks writing tips
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   204
------------------
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   205
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   206
Reminder
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   207
~~~~~~~~
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   208
8483
4ba11607d84a [entity api] unify set_attributes / set_relations into a cw_set method. Closes #2423719
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 8211
diff changeset
   209
You should never use the `entity.foo = 42` notation to update an entity. It will
4ba11607d84a [entity api] unify set_attributes / set_relations into a cw_set method. Closes #2423719
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 8211
diff changeset
   210
not do what you expect (updating the database). Instead, use the
4ba11607d84a [entity api] unify set_attributes / set_relations into a cw_set method. Closes #2423719
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 8211
diff changeset
   211
:meth:`~cubicweb.entity.Entity.cw_set` method or direct access to entity's
4ba11607d84a [entity api] unify set_attributes / set_relations into a cw_set method. Closes #2423719
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 8211
diff changeset
   212
:attr:`cw_edited` attribute if you're writing a hook for 'before_add_entity' or
4ba11607d84a [entity api] unify set_attributes / set_relations into a cw_set method. Closes #2423719
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 8211
diff changeset
   213
'before_update_entity' event.
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   214
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   215
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   216
How to choose between a before and an after event ?
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   217
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   218
6753
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   219
`before_*` hooks give you access to the old attribute (or relation)
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   220
values. You can also intercept and update edited values in the case of
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   221
entity modification before they reach the database.
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   222
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   223
Else the question is: should I need to do things before or after the actual
6753
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   224
modification ? If the answer is "it doesn't matter", use an 'after' event.
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   225
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   226
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   227
Validation Errors
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   228
~~~~~~~~~~~~~~~~~
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   229
6753
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   230
When a hook which is responsible to maintain the consistency of the
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   231
data model detects an error, it must use a specific exception named
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   232
:exc:`~cubicweb.ValidationError`. Raising anything but a (subclass of)
6753
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   233
:exc:`~cubicweb.ValidationError` is a programming error. Raising it
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   234
entails aborting the current transaction.
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   235
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   236
This exception is used to convey enough information up to the user
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   237
interface. Hence its constructor is different from the default Exception
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   238
constructor. It accepts, positionally:
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   239
9184
b982e88e4836 [repo] normalize ValidationError on edited entity (closes #2509729)
David Douard <david.douard@logilab.fr>
parents: 8981
diff changeset
   240
* an entity eid (**not the entity itself**),
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   241
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   242
* a dict whose keys represent attribute (or relation) names and values
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   243
  an end-user facing message (hence properly translated) relating the
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   244
  problem.
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   245
6753
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   246
.. sourcecode:: python
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   247
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   248
  raise ValidationError(earth.eid, {'sea_level': self._cw._('too high'),
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   249
                                    'temperature': self._cw._('too hot')})
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   250
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   251
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   252
Checking for object created/deleted in the current transaction
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   253
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   254
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   255
In hooks, you can use the
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   256
:meth:`~cubicweb.server.session.Session.added_in_transaction` or
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   257
:meth:`~cubicweb.server.session.Session.deleted_in_transaction` of the session
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   258
object to check if an eid has been created or deleted during the hook's
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   259
transaction.
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   260
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   261
This is useful to enable or disable some stuff if some entity is being added or
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   262
deleted.
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   263
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   264
.. sourcecode:: python
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   265
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   266
   if self._cw.deleted_in_transaction(self.eidto):
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   267
      return
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   268
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   269
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   270
Peculiarities of inlined relations
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   271
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5202
diff changeset
   272
6147
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   273
Relations which are defined in the schema as `inlined` (see :ref:`RelationType`
95c604ec89bf update documentation to follow 6142:8bc6eac1fac1 changes. Try to make it better and move most doc with code on the way
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5394
diff changeset
   274
for details) are inserted in the database at the same time as entity attributes.
6753
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   275
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   276
This may have some side effect, for instance when creating an entity
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   277
and setting an inlined relation in the same rql query, then at
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   278
`before_add_relation` time, the relation will already exist in the
2bbc1010494c [doc/book] fix/update a bit the hooks chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6366
diff changeset
   279
database (it is otherwise not the case).