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