Mercurial > libervia-backend

comparison doc/libervia-cli/pubsub_hook.rst @ 3488:c80a0f864b5d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: updated doc following global renaming
author Goffi <goffi@goffi.org>
date Sun, 21 Mar 2021 18:23:58 +0100
parents doc/jp/pubsub_hook.rst@72583524cfd3
children 267e4987b58b
comparison
equal deleted inserted replaced
3487:75427f0a5445 3488:c80a0f864b5d
1 .. _libervia-cli_pubsub_hook:
2
3 ====================================
4 pubsub/hook: PubSub hooks management
5 ====================================
6
7 ``hook`` is a subcommands grouping all PubSub commands related to hooks management. Hooks
8 are user actions launched on specific events.
9
10 3 types of hooks can be used:
11
12 ``python``
13 A Python module is expected as argument. The module must be available in Python path,
14 and it must have a ``hook`` function.
15
16 ``python_file``
17 A path to a Python script is expected as argument. The script must contain a ``hook``
18 function.
19
20 ``python_code``
21 Python code which will be directly executed. 3 variables will be set: ``host`` which
22 contain the main SàT instance, ``client`` which contain the session attached to the
23 profile, and ``item`` which contain the item attached to the event.
24
25 .. note::
26
27 Hooks are executed in SàT context, and must be asynchronous. If they block, the whole
28 SàT execution will be blocked. They have access to everything, so don't run a code that
29 you don't absolutely trust.
30
31 .. note::
32
33 Only ``python_file`` type is currently implemented
34
35 .. note::
36 Hook is an experimental feature, the way to use it may change in the future.
37
38 create
39 ======
40
41 Create a hook of given type. Type is specified with ``-t {python,python_file,python_code},
42 --type {python,python_file,python_code}`` and a positional arguments is expected, which
43 depends on the chosen type.
44
45 By default the hook is temporary (it will be lost if the profile is disconnected), but you
46 can make is persistent accross reconnexions if you use the ``-P, --persistent`` argument.
47
48 example
49 -------
50
51 Install a persistent hook on blog node, using the Python script named
52 ``do_something_neat.py`` in ``$HOME`` directory::
53
54 $ li pubsub node hook create -n urn:xmpp:microblog:0 -t python_file --persistent ~/do_something_neat.py
55
56 delete
57 ======
58
59 Delete one hook or all of them. To delete a hook, specify its type and argument (the that
60 you have used with ``create``). If you use empty ``--type`` and ``--arg`` all hooks will
61 be removed.
62
63 example
64 -------
65
66 Delete the ``do_something_neat.py`` hook::
67
68 $ li pubsub node hook delete -n urn:xmpp:microblog:0 -t python_file --arg ~/do_something_neat.py
69
70 list
71 ====
72
73 List registered hooks. The output will give the following informations:
74
75 service
76 PubSub service on which the hook is attached.
77
78 node
79 PubSub node on which the hook is attached.
80
81 type
82 hook type
83
84 arg
85 hook arguments (dependant of hook type)
86
87 persistent
88 boolean indicating is the hook persist accross sessions.
89
90 example
91 -------
92
93 Get PubSub hooks registered for this profile in JSON::
94
95 $ li pubsub hook list -O json
96