Mercurial > libervia-backend

annotate doc/libervia-cli/list.rst @ 4037:524856bd7b19

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
massive refactoring to switch from camelCase to snake_case: historically, Libervia (SàT before) was using camelCase as allowed by PEP8 when using a pre-PEP8 code, to use the same coding style as in Twisted. However, snake_case is more readable and it's better to follow PEP8 best practices, so it has been decided to move on full snake_case. Because Libervia has a huge codebase, this ended with a ugly mix of camelCase and snake_case. To fix that, this patch does a big refactoring by renaming every function and method (including bridge) that are not coming from Twisted or Wokkel, to use fully snake_case. This is a massive change, and may result in some bugs.
author Goffi <goffi@goffi.org>
date Sat, 08 Apr 2023 13:54:42 +0200
parents 267e4987b58b
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
1 =================================
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
2 list: create and manage lists
3041
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
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
5 list is a generic tools to create items with metadata and states (where state can be
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
6 ``queued``, ``done``, etc). This can be used for many things, from TODO list to bugs
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
7 management.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
8
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
9 get
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
10 ===
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
11
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
12 Retrieve one or more lists and display them. A project may use magic string in README to
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
13 indicate PubSub service and node to use, in which case use just need to be in the
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
14 directory of the project.
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 examples
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
17 --------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
18
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
19 Retrieve last 5 lists (ordered by creation) from a project using magic string in README::
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
20
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
21 $ li list get -m 5 -o creation
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
22
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
23 Retrieve the list with id ``123`` on service ``pubsub.example.org``::
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
24
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
25 $ li list get -s pubsub.example.org -i 123
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
26
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
27
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
28 set
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
29 ===
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
30
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
31 Create/replace or update a list item. You can specify fields using the ``-f NAME [VALUES
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
32 ...], --field NAME [VALUES ...]``, several values can be set. For ``text-multi`` (multiple
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
33 lines of text), each line is set in distinct value.
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
34
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
35 The ``-U {auto,true,false}, --update {auto,true,false}`` indicates if the item must be
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
36 updated (non specified values are kept) or fully replaced (non specified values would then
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
37 be default, even if they were previously set in the item). If ``auto`` is used (this is
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
38 the default), ``--update=true`` is used when ``item_id`` is specified, otherwise a new
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
39 item is created.
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
40
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
41 If ``-n NODE, --node NODE`` is not specified, it uses tickets default namespace.
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
42
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
43 examples
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
44 --------
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
45
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
46 Modify priority of a ticket with id ``123`` to ``major`` (the ticket is updated and not
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
47 replaced due to the default ``--update auto``)::
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
48
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
49 $ li list set -s pubsub.example.org -i 123 -f priority major
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
50
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
51 Set ``body`` for a new item when its schemas makes it a ``text-multi``::
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
52
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
53 $ li list set -s pubsub.example.org -f body "line 1" "line 2" "line 3"
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
54
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
55 delete
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
56 ======
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
57
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
58 Delete an item from a list. The options are the same as for :ref:`li_pubsub_delete`, the
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
59 only different is that ``-n NODE, --node NODE`` defaults to tickets namespace.
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
60
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
61 example
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
62 -------
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
63
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
64 Delete item with id ``456`` from tickets on PubSub service ``pubsub.example.org``::
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
65
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
66 $ li pubsub delete -s pubsub.example.org -i 456
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
67
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
68 import
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
4037
524856bd7b19 massive refactoring to switch from camelCase to snake_case:
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
71 import lists from an external source. This works in the same way as
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
72 :ref:`libervia-cli_blog_import`: you need to specify an importer and a data location. If you let
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
73 both positional argument empty, you'll get list of importers, if you specify importer but
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
74 not data location, you'll get a description on how the importer works.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
75
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
76 If you want to see a progress bar for the import, use the ``-P, --progress`` option, this
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
77 is recommended for most imports.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
78
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
79 Some importers may have specific option (check description for details), you can specify
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
80 them with ``o NAME VALUE, --option NAME VALUE``
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
81
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
82 When you import a list, the list will be created according to the schema of the PubSub
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
83 node. By default, the metadata of the original list will be put to the one of the same
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
84 name in the dest PubSub item. But of course the schema of your destination PubSub node may
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
85 differ from the original metadata. In this case, you can use ``-m IMPORTED_FIELD
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
86 DEST_FIELD, --map IMPORTED_FIELD DEST_FIELD`` to specify how the mapping mus be done
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
87 (``IMPORTED_FIELD is the name of the field in the original list, while ``DEST_FIELD`` if
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
88 the name of the field in your node schema).
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
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
91 examples
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
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
94 Get list of list importers::
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
95
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
96 $ li list import
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
97
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
98 Get description of list importer for Bugzilla::
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
99
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
100 $ li list import bugzilla
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
101
4037
524856bd7b19 massive refactoring to switch from camelCase to snake_case:
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
102 import lists from a Bugzilla XML export file at ``~/bugzilla_export.xml`` to the
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
103 ``pubsub.example.org`` PubSub service. We use default lists node and want a progression
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
104 bar::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
105
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
106 $ li list import -P -s pubsub.example.org ~/bugzilla_export.xml
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
107
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
108 Same import, but this time we want to map the field ``assigned_to_name`` from Bugzilla to
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
109 the field ``assigned_to`` in our schema::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
110
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
111 $ li list import -P -s pubsub.example.org -m assigned_to_name assigned_to ~/bugzilla_export.xml