cubicweb: comparison server/hook.py

equal deleted inserted replaced

-:7351806cd485
+:2bbc1010494c
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 When called for one of these events, hook will have an `entity` attribute
 containing the entity instance.
-* 'before_add_entity', 'before_update_entity':
+* `before_add_entity`, `before_update_entity`:
 - on those events, you can check what attributes of the entity are modified in
 `entity.cw_edited` (by definition the database is not yet updated in a before
 event)
-- you are allowed to further modify the entity before database operations,
+- you are allowed to further modify the entity before database
-using the dictionary notation. By doing this, you'll avoid the need for a
+operations, using the dictionary notation on `cw_edited`. By doing
-whole new rql query processing, the only difference is that the underlying
+this, you'll avoid the need for a whole new rql query processing,
-backend query (eg usually sql) will contains the additional data. For
+the only difference is that the underlying backend query (eg
-example:
+usually sql) will contains the additional data. For example:
 .. sourcecode:: python
 self.entity.set_attributes(age=42)
 one that triggered the hook.
 Similarly, removing an attribute from `cw_edited` will cancel its
 modification.
-- on 'before_update_entity' event, you can access to old and new values in
+- on `before_update_entity` event, you can access to old and new values in
 this hook, by using `entity.cw_edited.oldnewvalue(attr)`
-* 'after_add_entity', 'after_update_entity'
+* `after_add_entity`, `after_update_entity`
 - on those events, you can still check what attributes of the entity are
 modified in `entity.cw_edited` but you can't get anymore the old value, nor
 modify it.
-* 'before_delete_entity', 'after_delete_entity'
+* `before_delete_entity`, `after_delete_entity`
 - on those events, the entity has no `cw_edited` set.
 Relation modification related events
 When called for one of these events, hook will have `eidfrom`, `rtype`, `eidto`
 attributes containing respectivly the eid of the subject entity, the relation
 type and the eid of the object entity.
-* 'before_add_relation', 'before_delete_relation'
+* `before_add_relation`, `before_delete_relation`
 - on those events, you can still get original relation by issuing a rql query
-* 'after_add_relation', 'after_delete_relation'
+* `after_add_relation`, `after_delete_relation`
 This is an occasion to remind us that relations support the add / delete
 operation, but no update.
 Non data events
 ~~~~~~~~~~~~~~~
-Hooks called on server start/maintenance/stop event (eg 'server_startup',
+Hooks called on server start/maintenance/stop event (eg `server_startup`,
-'server_maintenance', 'server_shutdown') have a `repo` attribute, but *their
+`server_maintenance`, `server_shutdown`) have a `repo` attribute, but *their
 `_cw` attribute is None*.  The `server_startup` is called on regular startup,
 while `server_maintenance` is called on cubicweb-ctl upgrade or shell
 commands. `server_shutdown` is called anyway.
 Hooks called on backup/restore event (eg 'server_backup', 'server_restore') have
 a `repo` and a `timestamp` attributes, but *their `_cw` attribute is None*.
-Hooks called on session event (eg 'session_open', 'session_close') have no
+Hooks called on session event (eg `session_open`, `session_close`) have no
 special attribute.
 API
 ---
 on the right events. It is possible to dispatch on multiple events at once
 if needed (though take care as hook attribute may vary as described above).
 .. Note::
-Do not forget to extend the base class selectors as in ::
+Do not forget to extend the base class selectors as in:
 .. sourcecode:: python
 class MyHook(Hook):
 __regid__ = 'whatever'
 operation instance.
 An operation is triggered on connections pool events related to
 commit / rollback transations. Possible events are:
-* 'precommit':
+* `precommit`:
 the transaction is being prepared for commit. You can freely do any heavy
 computation, raise an exception if the commit can't go. or even add some
 new operations during this phase. If you do anything which has to be
 reverted if the commit fails afterwards (eg altering the file system for
 instance), you'll have to support the 'revertprecommit' event to revert
 things by yourself
-* 'revertprecommit':
+* `revertprecommit`:
 if an operation failed while being pre-commited, this event is triggered
 for all operations which had their 'precommit' event already fired to let
 them revert things (including the operation which made the commit fail)
-* 'rollback':
+* `rollback`:
 the transaction has been either rollbacked either:
 * intentionaly
 * a 'precommit' event failed, in which case all operations are rollbacked
 once 'revertprecommit'' has been called
-* 'postcommit':
+* `postcommit`:
 the transaction is over. All the ORM entities accessed by the earlier
 transaction are invalid. If you need to work on the database, you need to
 start a new transaction, for instance using a new internal session, which
 you will need to commit (and close!).
 For an operation to support an event, one has to implement the `<event
 name>_event` method with no arguments.
-Notice order of operations may be important, and is controlled according to
+The order of operations may be important, and is controlled according to
 the insert_index's method output (whose implementation vary according to the
 base hook class used).
 """
 def __init__(self, session, **kwargs):
 You should try to use this instead of creating on operation for each
 `value`, since handling operations becomes costly on massive data import.
 Usage looks like:
 .. sourcecode:: python
 class MyEntityHook(Hook):
 __regid__ = 'my.entity.hook'
 __select__ = Hook.__select__ & is_instance('MyEntity')

branch	stable
changeset 6753	2bbc1010494c
parent 6730	253dd28cc35f
child 6765	b922e3a817e9