libknot 3.3.14.dev0__tar.gz → 3.3.16.dev0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. {libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/PKG-INFO +86 -59
  2. {libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/README.md +85 -58
  3. {libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/libknot.egg-info/PKG-INFO +86 -59
  4. {libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/pyproject.toml +1 -1
  5. {libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/setup.py +1 -1
  6. {libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/libknot/__init__.py +0 -0
  7. {libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/libknot/control.py +0 -0
  8. {libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/libknot/dname.py +0 -0
  9. {libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/libknot/probe.py +0 -0
  10. {libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/libknot.egg-info/SOURCES.txt +0 -0
  11. {libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/libknot.egg-info/dependency_links.txt +0 -0
  12. {libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/libknot.egg-info/top_level.txt +0 -0
  13. {libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/setup.cfg +0 -0
{libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: libknot
3
- Version: 3.3.14.dev0
3
+ Version: 3.3.16.dev0
4
4
  Summary: Python bindings for libknot
5
5
  Home-page: https://gitlab.nic.cz/knot/knot-dns/-/tree/master/python/libknot
6
6
  Author: CZ.NIC, z.s.p.o.
@@ -28,9 +28,9 @@ A Python interface for managing the Knot DNS daemon.
28
28
 
29
29
  * [Introduction](#introduction)
30
30
  * [Control module](#control-module)
31
- + [Usage](#control-usage)
32
31
  + [Protocol reference](#kctl-proto)
33
32
  + [Commands reference](#kctl-cmds)
33
+ + [Usage](#control-usage)
34
34
  + [Examples](#control-examples)
35
35
  * [Probe module](#probe-module)
36
36
  + [Probe usage](#probe-usage)
@@ -58,25 +58,15 @@ i.e. communication via a Unix socket.
58
58
 
59
59
  The module API is stored in `libknot.control`.
60
60
 
61
- ### Control usage<a id="control-usage"></a>
62
-
63
- The module usage consists of several steps:
64
-
65
- * Initialization and connection to the daemon control socket.
66
- * One or more control operations. An operation is called by sending a command
67
- with optional data to the daemon. The operation result has to be received
68
- afterwards.
69
- * Closing the connection and deinitialization.
70
-
71
61
  ### Protocol overview<a id="kctl-proto"></a>
72
62
 
73
63
  Connections are supposed to be short-lived, because maintaining a passive
74
- connection is costly for the server. Therefore the expected usage of the ctl
64
+ connection is costly for the server. Therefore the expected usage of the CTL
75
65
  interface is to always open a new connection on demand, then close it once it's
76
66
  not immediately needed.
77
67
 
78
- Messages are composed of units. These are of four types whose identifiers are
79
- defined in `libknot.control.KnotCtlType`:
68
+ Messages are composed of units. These are of four types the identifiers of
69
+ which are defined in `libknot.control.KnotCtlType`:
80
70
 
81
71
  | Type | Description | IO action |
82
72
  | ------- | ---------------------------------------------------------- | --------- |
@@ -85,6 +75,9 @@ defined in `libknot.control.KnotCtlType`:
85
75
  | `EXTRA` | Additional data. | cache |
86
76
  | `BLOCK` | End of data block. | flush |
87
77
 
78
+ `DATA` and `EXTRA` units aren't immediately sent, rather they're buffered and
79
+ then sent along with the next `END` or `BLOCK` unit.
80
+
88
81
  A unit can optionaly hold data, though this is only meaningful for the `DATA`
89
82
  and `EXTRA` types. The data consists of several sections of which usually only
90
83
  a few at a time will be present. For example when a unit issuing a `stats`
@@ -92,20 +85,20 @@ command is sent, there is no reason for it to contain an `ERROR` section.
92
85
 
93
86
  The data section identifiers are defined in `libknot.control.KnotCtlDataIdx`:
94
87
 
95
- | Section name | Description |
96
- | ------------ | ------------------------------------------------------ |
97
- | `COMMAND` | Command name. |
98
- | `FLAGS` | Command flags. |
99
- | `ERROR` | Error message. |
100
- | `SECTION` | Configuration section name. |
101
- | `ITEM` | Configuration item name. |
102
- | `ID` | Configuration item identifier. |
103
- | `ZONE` | Zone name. |
104
- | `OWNER` | Zone record owner |
105
- | `TTL` | Zone record TTL. |
106
- | `TYPE` | Zone record type name. |
107
- | `DATA` | Configuration item/zone record data. |
108
- | `FILTERS` | Command options or filters for output data processing. |
88
+ | Section name | `send_block()` arg name | Description |
89
+ | ------------ | ----------------------- | ------------------------------------------------------ |
90
+ | `COMMAND` | cmd | Command name. |
91
+ | `FLAGS` | flags | Command flags. |
92
+ | `ERROR` | *n/a* | Error message. Only sent by the server. |
93
+ | `SECTION` | section | Configuration section name. |
94
+ | `ITEM` | item | Configuration item name. |
95
+ | `ID` | identifier | Configuration item identifier. |
96
+ | `ZONE` | zone | Zone name. |
97
+ | `OWNER` | owner | Zone record owner |
98
+ | `TTL` | ttl | Zone record TTL. |
99
+ | `TYPE` | rtype | Zone record type name. |
100
+ | `DATA` | data | Configuration item/zone record data. |
101
+ | `FILTERS` | filters | Command options or filters for output data processing. |
109
102
 
110
103
  ### Commands reference<a id="kctl-cmds"></a>
111
104
 
@@ -115,17 +108,22 @@ of the commands' semantics, please consult the
115
108
 
116
109
  A concise notation is used for command synopsis:
117
110
 
118
- <pre>
119
- cmd-name(SECTION_NAME,
120
- [OPTIONAL_SECTION="literal value"],
121
- [OPT_SECTION1, OPT_SECTION2], # Sections must be present together or not at all
122
- [OPT_MASTER, [OPT_SLAVE]], # OPT_SLAVE may only appear if OPT_MASTER is present
123
- SECTION_NAME2="option1"|"option2", # Either one or the other literal may be used
124
- SECTION_NAME3={"asdf"}, # any subset of characters
125
- )
126
- </pre>
111
+ ```
112
+ # command "cmd-name" accepts section of type SECTION_NAME and optionally
113
+ # another section of type OPT_SECTION
114
+ cmd-name(SECTION_NAME, [OPT_SECTION])
115
+
116
+ [OPT_SECTION="literal value"], # Optional section with fixed expected value.
117
+ [SECTION1, SECTION2] # Sections must be present together or not at all.
118
+ [PRIMARY, [SECONDARY]] # SECONDARY may only appear if PRIMARY is present.
119
+ SECTION_NAME="option1"|"option2" # Either one or the other literal may be used.
120
+ SECTION_NAME={"asdf"} # Any subset of characters may be used.
121
+ ```
122
+
123
+ The `B` flag always represents an option to execute in blocking mode.
127
124
 
128
- The **`"B"`** flag always represents an option to execute in blocking mode.
125
+ When listing the filters a command accepts, the letter which is passed into
126
+ `FILTERS` will be boldened. Like this: zone**f**ile
129
127
 
130
128
  #### Server
131
129
 
@@ -138,23 +136,23 @@ The **`"B"`** flag always represents an option to execute in blocking mode.
138
136
 
139
137
  #### Zone events
140
138
 
141
- `ZONE`: if none applies to all zones
139
+ The following commands apply to all zones if `ZONE` is left empty.
142
140
 
143
141
  * `zone-status([ZONE], [FILTERS={"rstefc"}])`
144
- + `FILTERS`: role `(r)`, serial `(s)`, transaction `(t)`, events `(e)`, freeze `(f)`, catalog `(c)`
142
+ + filters: **r**ole, **s**erial, **t**ransaction, **e**vents, **f**reeze, **c**atalog <!-- , **u**nixtime -->
145
143
  * `zone-reload([ZONE], [FLAGS={"BF"}])`
146
- + `FLAGS`: `F` reload modules
144
+ + the `F` flag commands to also reload modules
147
145
  * `zone-refresh([ZONE], [FLAGS="B"])`
148
146
  * `zone-retransfer([ZONE], [FLAGS="B"])`
149
147
  * `zone-notify([ZONE], [FLAGS="B"])`
150
148
  * `zone-flush([ZONE], [FILTERS="d", DATA], [FLAGS="B"])`
151
- + the outputdir `(d)` filter commands that zone(s) be flushed to path stored in the `DATA` section
149
+ + the output**d**ir filter commands that zone(s) be flushed to path stored in the `DATA` section
152
150
  * `zone-backup([ZONE], [FILTERS={"dzjtkocqZJTKOCQ"}, [DATA]], [FLAGS="B"])`
153
- + `FILTERS`
154
- - for description of the outputdir `(d)` filter see `zone-flush`
155
- - zonefile `(z)`, journal `(j)`, timers `(t)`, kaspdb `(k)`, keysonly `(o)`, catalog `(c)`, quic `(q)`
156
- - negative counterparts (eg. `nozonefile`) are symmetrical and capitalized
157
- * `zone-restore` <i>analogous to `zone-backup`</i>
151
+ + filters
152
+ - the backup**d**ir filter commands that backups be made to path stored in the `DATA` section
153
+ - **z**onefile, **j**ournal, **t**imers, **k**aspdb, keys**o**nly, **c**atalog, **q**uic
154
+ - negative counterparts (eg. no**Z**onefile) are symmetrical and capitalized
155
+ * `zone-restore` *analogous to `zone-backup`*
158
156
  * `zone-sign([ZONE], [FLAGS="B"])`
159
157
  * `zone-validate([ZONE], [FLAGS="B"])`
160
158
  * `zone-keys-load([ZONE], [FLAGS="B"])`
@@ -167,42 +165,71 @@ The **`"B"`** flag always represents an option to execute in blocking mode.
167
165
 
168
166
  #### Zone editing
169
167
 
170
- Use `"@"` as `OWNER` if you want to denote `ZONE` itself as the owner.
168
+ Use `@` as `OWNER` if you want to denote `ZONE` itself as the owner.
171
169
 
172
170
  * `zone-read([ZONE], [OWNER], [TYPE])`
173
171
  + if `ZONE` is left empty all zones are read
174
- * `zone-begin(ZONE)`
172
+ * `zone-begin(ZONE, [FILTERS="b"])`
173
+ + filters: **b**enevolent
175
174
  * `zone-commit(ZONE)`
176
175
  * `zone-abort(ZONE)`
177
176
  * `zone-diff(ZONE)`
178
- * `zone-get(ZONE, [OWNER], [TYPE])` <!-- TODO: test if OWNER and TYPE may be specified independently -->
177
+ * `zone-get(ZONE, [OWNER], [TYPE])`
179
178
  * `zone-set(ZONE, OWNER, [TTL], TYPE, DATA)`
180
179
  * `zone-unset(ZONE, OWNER, [TYPE, [DATA]])`
181
180
  * `zone-purge(ZONE, [FILTERS={ocejktf}], [FLAGS="B"])`
182
- + `FILTERS`: orphan `(o)`, catalog `(c)`, expire `(e)`, journal `(j)`, kaspdb `(k)`, timers `(t)`, zonefile `(f)`
181
+ + filters: **o**rphan, **c**atalog, **e**xpire, **j**ournal, **k**aspdb, **t**imers, zone**f**ile
183
182
  * `zone-stats(ZONE, [SECTION], [ITEM], [FLAGS="F"])`
184
183
  + `SECTION` stores the module, `ITEM` stores the counter
185
184
  + the `F` flag specifies to include 0 counters in server's response
186
185
 
187
186
  #### Configuration
188
187
 
189
- optional list schema option ('s') in FILTERS <!-- TODO: k cemu to je? -->
188
+ For the following commands:
190
189
 
191
- For the following commands:<br/>
192
- &middot; `SECTION` holds the configuration section name (eg. `template`)<br/>
193
- &middot; `ID` holds the configuration id (eg. `default`)<br/>
194
- &middot; `ITEM` holds the configuration item name (eg. `storage`)<br/>
190
+ * `SECTION` holds the configuration section name (eg. `template`)
191
+ * `ID` holds the configuration id (eg. `default`)
192
+ * `ITEM` holds the configuration item name (eg. `storage`)
195
193
 
196
- * `conf-list([SECTION, [ID], [ITEM]], [FILTERS="s"])`
194
+ <!-- hacky comment to separate markdown lists -->
195
+
196
+ * `conf-list([SECTION, [ID], [ITEM]], [FILTERS="z"|{"st"}])`
197
+ + filters:
198
+ - **z**one: list all zone names, including those from the catalog
199
+ - li**s**t: list configuration section items instead of its identifiers
200
+ - **t**ransaction: If a transaction is open (`conf-begin`) queries the
201
+ transaction's configuration schema instead of the server's
197
202
  * `conf-read([SECTION, [ID], [ITEM]])`
198
203
  * `conf-begin()`
199
204
  * `conf-commit()`
200
205
  * `conf-abort()`
201
206
  * `conf-diff([SECTION, [ID], [ITEM]])`
202
207
  * `conf-get([SECTION, [ID], [ITEM]])`
203
- * `conf-set(SECTION, ID, ITEM, [DATA], [FILTERS="s"])`
208
+ * `conf-set(SECTION, ID, ITEM, [DATA])`
204
209
  * `conf-unset([SECTION, [ID], [ITEM]], [DATA])`
205
210
 
211
+ ### Control usage<a id="control-usage"></a>
212
+
213
+ The module usage consists of several steps:
214
+
215
+ * Initialization and connection to the daemon control socket.
216
+ * One or more control operations. An operation is called by sending a command
217
+ with optional data to the daemon. The operation result has to be received
218
+ afterwards.
219
+ * Closing the connection and deinitialization.
220
+
221
+ #### Sending
222
+
223
+ There are two methods on the `KnotCtl` class which send data to the socket.
224
+
225
+ `KnotCtl.send(KnotCtlType, KnotCtlData)` is the more rudimentary one. It only
226
+ sends the section identifier along with its data, if any are provided. When
227
+ using this function users must beware of the different characteristics
228
+ regarding buffering of different unit types.
229
+
230
+ `KnotCtl.send_block(...)` is more convenient in that it always flushes by
231
+ sending a `BLOCK` unit. Otherwise the two methods are functionally equivalent.
232
+
206
233
  ### Control examples<a id="control-examples"></a>
207
234
 
208
235
  ```python3
{libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/README.md RENAMED
@@ -6,9 +6,9 @@ A Python interface for managing the Knot DNS daemon.
6
6
 
7
7
  * [Introduction](#introduction)
8
8
  * [Control module](#control-module)
9
- + [Usage](#control-usage)
10
9
  + [Protocol reference](#kctl-proto)
11
10
  + [Commands reference](#kctl-cmds)
11
+ + [Usage](#control-usage)
12
12
  + [Examples](#control-examples)
13
13
  * [Probe module](#probe-module)
14
14
  + [Probe usage](#probe-usage)
@@ -36,25 +36,15 @@ i.e. communication via a Unix socket.
36
36
 
37
37
  The module API is stored in `libknot.control`.
38
38
 
39
- ### Control usage<a id="control-usage"></a>
40
-
41
- The module usage consists of several steps:
42
-
43
- * Initialization and connection to the daemon control socket.
44
- * One or more control operations. An operation is called by sending a command
45
- with optional data to the daemon. The operation result has to be received
46
- afterwards.
47
- * Closing the connection and deinitialization.
48
-
49
39
  ### Protocol overview<a id="kctl-proto"></a>
50
40
 
51
41
  Connections are supposed to be short-lived, because maintaining a passive
52
- connection is costly for the server. Therefore the expected usage of the ctl
42
+ connection is costly for the server. Therefore the expected usage of the CTL
53
43
  interface is to always open a new connection on demand, then close it once it's
54
44
  not immediately needed.
55
45
 
56
- Messages are composed of units. These are of four types whose identifiers are
57
- defined in `libknot.control.KnotCtlType`:
46
+ Messages are composed of units. These are of four types the identifiers of
47
+ which are defined in `libknot.control.KnotCtlType`:
58
48
 
59
49
  | Type | Description | IO action |
60
50
  | ------- | ---------------------------------------------------------- | --------- |
@@ -63,6 +53,9 @@ defined in `libknot.control.KnotCtlType`:
63
53
  | `EXTRA` | Additional data. | cache |
64
54
  | `BLOCK` | End of data block. | flush |
65
55
 
56
+ `DATA` and `EXTRA` units aren't immediately sent, rather they're buffered and
57
+ then sent along with the next `END` or `BLOCK` unit.
58
+
66
59
  A unit can optionaly hold data, though this is only meaningful for the `DATA`
67
60
  and `EXTRA` types. The data consists of several sections of which usually only
68
61
  a few at a time will be present. For example when a unit issuing a `stats`
@@ -70,20 +63,20 @@ command is sent, there is no reason for it to contain an `ERROR` section.
70
63
 
71
64
  The data section identifiers are defined in `libknot.control.KnotCtlDataIdx`:
72
65
 
73
- | Section name | Description |
74
- | ------------ | ------------------------------------------------------ |
75
- | `COMMAND` | Command name. |
76
- | `FLAGS` | Command flags. |
77
- | `ERROR` | Error message. |
78
- | `SECTION` | Configuration section name. |
79
- | `ITEM` | Configuration item name. |
80
- | `ID` | Configuration item identifier. |
81
- | `ZONE` | Zone name. |
82
- | `OWNER` | Zone record owner |
83
- | `TTL` | Zone record TTL. |
84
- | `TYPE` | Zone record type name. |
85
- | `DATA` | Configuration item/zone record data. |
86
- | `FILTERS` | Command options or filters for output data processing. |
66
+ | Section name | `send_block()` arg name | Description |
67
+ | ------------ | ----------------------- | ------------------------------------------------------ |
68
+ | `COMMAND` | cmd | Command name. |
69
+ | `FLAGS` | flags | Command flags. |
70
+ | `ERROR` | *n/a* | Error message. Only sent by the server. |
71
+ | `SECTION` | section | Configuration section name. |
72
+ | `ITEM` | item | Configuration item name. |
73
+ | `ID` | identifier | Configuration item identifier. |
74
+ | `ZONE` | zone | Zone name. |
75
+ | `OWNER` | owner | Zone record owner |
76
+ | `TTL` | ttl | Zone record TTL. |
77
+ | `TYPE` | rtype | Zone record type name. |
78
+ | `DATA` | data | Configuration item/zone record data. |
79
+ | `FILTERS` | filters | Command options or filters for output data processing. |
87
80
 
88
81
  ### Commands reference<a id="kctl-cmds"></a>
89
82
 
@@ -93,17 +86,22 @@ of the commands' semantics, please consult the
93
86
 
94
87
  A concise notation is used for command synopsis:
95
88
 
96
- <pre>
97
- cmd-name(SECTION_NAME,
98
- [OPTIONAL_SECTION="literal value"],
99
- [OPT_SECTION1, OPT_SECTION2], # Sections must be present together or not at all
100
- [OPT_MASTER, [OPT_SLAVE]], # OPT_SLAVE may only appear if OPT_MASTER is present
101
- SECTION_NAME2="option1"|"option2", # Either one or the other literal may be used
102
- SECTION_NAME3={"asdf"}, # any subset of characters
103
- )
104
- </pre>
89
+ ```
90
+ # command "cmd-name" accepts section of type SECTION_NAME and optionally
91
+ # another section of type OPT_SECTION
92
+ cmd-name(SECTION_NAME, [OPT_SECTION])
93
+
94
+ [OPT_SECTION="literal value"], # Optional section with fixed expected value.
95
+ [SECTION1, SECTION2] # Sections must be present together or not at all.
96
+ [PRIMARY, [SECONDARY]] # SECONDARY may only appear if PRIMARY is present.
97
+ SECTION_NAME="option1"|"option2" # Either one or the other literal may be used.
98
+ SECTION_NAME={"asdf"} # Any subset of characters may be used.
99
+ ```
100
+
101
+ The `B` flag always represents an option to execute in blocking mode.
105
102
 
106
- The **`"B"`** flag always represents an option to execute in blocking mode.
103
+ When listing the filters a command accepts, the letter which is passed into
104
+ `FILTERS` will be boldened. Like this: zone**f**ile
107
105
 
108
106
  #### Server
109
107
 
@@ -116,23 +114,23 @@ The **`"B"`** flag always represents an option to execute in blocking mode.
116
114
 
117
115
  #### Zone events
118
116
 
119
- `ZONE`: if none applies to all zones
117
+ The following commands apply to all zones if `ZONE` is left empty.
120
118
 
121
119
  * `zone-status([ZONE], [FILTERS={"rstefc"}])`
122
- + `FILTERS`: role `(r)`, serial `(s)`, transaction `(t)`, events `(e)`, freeze `(f)`, catalog `(c)`
120
+ + filters: **r**ole, **s**erial, **t**ransaction, **e**vents, **f**reeze, **c**atalog <!-- , **u**nixtime -->
123
121
  * `zone-reload([ZONE], [FLAGS={"BF"}])`
124
- + `FLAGS`: `F` reload modules
122
+ + the `F` flag commands to also reload modules
125
123
  * `zone-refresh([ZONE], [FLAGS="B"])`
126
124
  * `zone-retransfer([ZONE], [FLAGS="B"])`
127
125
  * `zone-notify([ZONE], [FLAGS="B"])`
128
126
  * `zone-flush([ZONE], [FILTERS="d", DATA], [FLAGS="B"])`
129
- + the outputdir `(d)` filter commands that zone(s) be flushed to path stored in the `DATA` section
127
+ + the output**d**ir filter commands that zone(s) be flushed to path stored in the `DATA` section
130
128
  * `zone-backup([ZONE], [FILTERS={"dzjtkocqZJTKOCQ"}, [DATA]], [FLAGS="B"])`
131
- + `FILTERS`
132
- - for description of the outputdir `(d)` filter see `zone-flush`
133
- - zonefile `(z)`, journal `(j)`, timers `(t)`, kaspdb `(k)`, keysonly `(o)`, catalog `(c)`, quic `(q)`
134
- - negative counterparts (eg. `nozonefile`) are symmetrical and capitalized
135
- * `zone-restore` <i>analogous to `zone-backup`</i>
129
+ + filters
130
+ - the backup**d**ir filter commands that backups be made to path stored in the `DATA` section
131
+ - **z**onefile, **j**ournal, **t**imers, **k**aspdb, keys**o**nly, **c**atalog, **q**uic
132
+ - negative counterparts (eg. no**Z**onefile) are symmetrical and capitalized
133
+ * `zone-restore` *analogous to `zone-backup`*
136
134
  * `zone-sign([ZONE], [FLAGS="B"])`
137
135
  * `zone-validate([ZONE], [FLAGS="B"])`
138
136
  * `zone-keys-load([ZONE], [FLAGS="B"])`
@@ -145,42 +143,71 @@ The **`"B"`** flag always represents an option to execute in blocking mode.
145
143
 
146
144
  #### Zone editing
147
145
 
148
- Use `"@"` as `OWNER` if you want to denote `ZONE` itself as the owner.
146
+ Use `@` as `OWNER` if you want to denote `ZONE` itself as the owner.
149
147
 
150
148
  * `zone-read([ZONE], [OWNER], [TYPE])`
151
149
  + if `ZONE` is left empty all zones are read
152
- * `zone-begin(ZONE)`
150
+ * `zone-begin(ZONE, [FILTERS="b"])`
151
+ + filters: **b**enevolent
153
152
  * `zone-commit(ZONE)`
154
153
  * `zone-abort(ZONE)`
155
154
  * `zone-diff(ZONE)`
156
- * `zone-get(ZONE, [OWNER], [TYPE])` <!-- TODO: test if OWNER and TYPE may be specified independently -->
155
+ * `zone-get(ZONE, [OWNER], [TYPE])`
157
156
  * `zone-set(ZONE, OWNER, [TTL], TYPE, DATA)`
158
157
  * `zone-unset(ZONE, OWNER, [TYPE, [DATA]])`
159
158
  * `zone-purge(ZONE, [FILTERS={ocejktf}], [FLAGS="B"])`
160
- + `FILTERS`: orphan `(o)`, catalog `(c)`, expire `(e)`, journal `(j)`, kaspdb `(k)`, timers `(t)`, zonefile `(f)`
159
+ + filters: **o**rphan, **c**atalog, **e**xpire, **j**ournal, **k**aspdb, **t**imers, zone**f**ile
161
160
  * `zone-stats(ZONE, [SECTION], [ITEM], [FLAGS="F"])`
162
161
  + `SECTION` stores the module, `ITEM` stores the counter
163
162
  + the `F` flag specifies to include 0 counters in server's response
164
163
 
165
164
  #### Configuration
166
165
 
167
- optional list schema option ('s') in FILTERS <!-- TODO: k cemu to je? -->
166
+ For the following commands:
168
167
 
169
- For the following commands:<br/>
170
- &middot; `SECTION` holds the configuration section name (eg. `template`)<br/>
171
- &middot; `ID` holds the configuration id (eg. `default`)<br/>
172
- &middot; `ITEM` holds the configuration item name (eg. `storage`)<br/>
168
+ * `SECTION` holds the configuration section name (eg. `template`)
169
+ * `ID` holds the configuration id (eg. `default`)
170
+ * `ITEM` holds the configuration item name (eg. `storage`)
173
171
 
174
- * `conf-list([SECTION, [ID], [ITEM]], [FILTERS="s"])`
172
+ <!-- hacky comment to separate markdown lists -->
173
+
174
+ * `conf-list([SECTION, [ID], [ITEM]], [FILTERS="z"|{"st"}])`
175
+ + filters:
176
+ - **z**one: list all zone names, including those from the catalog
177
+ - li**s**t: list configuration section items instead of its identifiers
178
+ - **t**ransaction: If a transaction is open (`conf-begin`) queries the
179
+ transaction's configuration schema instead of the server's
175
180
  * `conf-read([SECTION, [ID], [ITEM]])`
176
181
  * `conf-begin()`
177
182
  * `conf-commit()`
178
183
  * `conf-abort()`
179
184
  * `conf-diff([SECTION, [ID], [ITEM]])`
180
185
  * `conf-get([SECTION, [ID], [ITEM]])`
181
- * `conf-set(SECTION, ID, ITEM, [DATA], [FILTERS="s"])`
186
+ * `conf-set(SECTION, ID, ITEM, [DATA])`
182
187
  * `conf-unset([SECTION, [ID], [ITEM]], [DATA])`
183
188
 
189
+ ### Control usage<a id="control-usage"></a>
190
+
191
+ The module usage consists of several steps:
192
+
193
+ * Initialization and connection to the daemon control socket.
194
+ * One or more control operations. An operation is called by sending a command
195
+ with optional data to the daemon. The operation result has to be received
196
+ afterwards.
197
+ * Closing the connection and deinitialization.
198
+
199
+ #### Sending
200
+
201
+ There are two methods on the `KnotCtl` class which send data to the socket.
202
+
203
+ `KnotCtl.send(KnotCtlType, KnotCtlData)` is the more rudimentary one. It only
204
+ sends the section identifier along with its data, if any are provided. When
205
+ using this function users must beware of the different characteristics
206
+ regarding buffering of different unit types.
207
+
208
+ `KnotCtl.send_block(...)` is more convenient in that it always flushes by
209
+ sending a `BLOCK` unit. Otherwise the two methods are functionally equivalent.
210
+
184
211
  ### Control examples<a id="control-examples"></a>
185
212
 
186
213
  ```python3
{libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/libknot.egg-info/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: libknot
3
- Version: 3.3.14.dev0
3
+ Version: 3.3.16.dev0
4
4
  Summary: Python bindings for libknot
5
5
  Home-page: https://gitlab.nic.cz/knot/knot-dns/-/tree/master/python/libknot
6
6
  Author: CZ.NIC, z.s.p.o.
@@ -28,9 +28,9 @@ A Python interface for managing the Knot DNS daemon.
28
28
 
29
29
  * [Introduction](#introduction)
30
30
  * [Control module](#control-module)
31
- + [Usage](#control-usage)
32
31
  + [Protocol reference](#kctl-proto)
33
32
  + [Commands reference](#kctl-cmds)
33
+ + [Usage](#control-usage)
34
34
  + [Examples](#control-examples)
35
35
  * [Probe module](#probe-module)
36
36
  + [Probe usage](#probe-usage)
@@ -58,25 +58,15 @@ i.e. communication via a Unix socket.
58
58
 
59
59
  The module API is stored in `libknot.control`.
60
60
 
61
- ### Control usage<a id="control-usage"></a>
62
-
63
- The module usage consists of several steps:
64
-
65
- * Initialization and connection to the daemon control socket.
66
- * One or more control operations. An operation is called by sending a command
67
- with optional data to the daemon. The operation result has to be received
68
- afterwards.
69
- * Closing the connection and deinitialization.
70
-
71
61
  ### Protocol overview<a id="kctl-proto"></a>
72
62
 
73
63
  Connections are supposed to be short-lived, because maintaining a passive
74
- connection is costly for the server. Therefore the expected usage of the ctl
64
+ connection is costly for the server. Therefore the expected usage of the CTL
75
65
  interface is to always open a new connection on demand, then close it once it's
76
66
  not immediately needed.
77
67
 
78
- Messages are composed of units. These are of four types whose identifiers are
79
- defined in `libknot.control.KnotCtlType`:
68
+ Messages are composed of units. These are of four types the identifiers of
69
+ which are defined in `libknot.control.KnotCtlType`:
80
70
 
81
71
  | Type | Description | IO action |
82
72
  | ------- | ---------------------------------------------------------- | --------- |
@@ -85,6 +75,9 @@ defined in `libknot.control.KnotCtlType`:
85
75
  | `EXTRA` | Additional data. | cache |
86
76
  | `BLOCK` | End of data block. | flush |
87
77
 
78
+ `DATA` and `EXTRA` units aren't immediately sent, rather they're buffered and
79
+ then sent along with the next `END` or `BLOCK` unit.
80
+
88
81
  A unit can optionaly hold data, though this is only meaningful for the `DATA`
89
82
  and `EXTRA` types. The data consists of several sections of which usually only
90
83
  a few at a time will be present. For example when a unit issuing a `stats`
@@ -92,20 +85,20 @@ command is sent, there is no reason for it to contain an `ERROR` section.
92
85
 
93
86
  The data section identifiers are defined in `libknot.control.KnotCtlDataIdx`:
94
87
 
95
- | Section name | Description |
96
- | ------------ | ------------------------------------------------------ |
97
- | `COMMAND` | Command name. |
98
- | `FLAGS` | Command flags. |
99
- | `ERROR` | Error message. |
100
- | `SECTION` | Configuration section name. |
101
- | `ITEM` | Configuration item name. |
102
- | `ID` | Configuration item identifier. |
103
- | `ZONE` | Zone name. |
104
- | `OWNER` | Zone record owner |
105
- | `TTL` | Zone record TTL. |
106
- | `TYPE` | Zone record type name. |
107
- | `DATA` | Configuration item/zone record data. |
108
- | `FILTERS` | Command options or filters for output data processing. |
88
+ | Section name | `send_block()` arg name | Description |
89
+ | ------------ | ----------------------- | ------------------------------------------------------ |
90
+ | `COMMAND` | cmd | Command name. |
91
+ | `FLAGS` | flags | Command flags. |
92
+ | `ERROR` | *n/a* | Error message. Only sent by the server. |
93
+ | `SECTION` | section | Configuration section name. |
94
+ | `ITEM` | item | Configuration item name. |
95
+ | `ID` | identifier | Configuration item identifier. |
96
+ | `ZONE` | zone | Zone name. |
97
+ | `OWNER` | owner | Zone record owner |
98
+ | `TTL` | ttl | Zone record TTL. |
99
+ | `TYPE` | rtype | Zone record type name. |
100
+ | `DATA` | data | Configuration item/zone record data. |
101
+ | `FILTERS` | filters | Command options or filters for output data processing. |
109
102
 
110
103
  ### Commands reference<a id="kctl-cmds"></a>
111
104
 
@@ -115,17 +108,22 @@ of the commands' semantics, please consult the
115
108
 
116
109
  A concise notation is used for command synopsis:
117
110
 
118
- <pre>
119
- cmd-name(SECTION_NAME,
120
- [OPTIONAL_SECTION="literal value"],
121
- [OPT_SECTION1, OPT_SECTION2], # Sections must be present together or not at all
122
- [OPT_MASTER, [OPT_SLAVE]], # OPT_SLAVE may only appear if OPT_MASTER is present
123
- SECTION_NAME2="option1"|"option2", # Either one or the other literal may be used
124
- SECTION_NAME3={"asdf"}, # any subset of characters
125
- )
126
- </pre>
111
+ ```
112
+ # command "cmd-name" accepts section of type SECTION_NAME and optionally
113
+ # another section of type OPT_SECTION
114
+ cmd-name(SECTION_NAME, [OPT_SECTION])
115
+
116
+ [OPT_SECTION="literal value"], # Optional section with fixed expected value.
117
+ [SECTION1, SECTION2] # Sections must be present together or not at all.
118
+ [PRIMARY, [SECONDARY]] # SECONDARY may only appear if PRIMARY is present.
119
+ SECTION_NAME="option1"|"option2" # Either one or the other literal may be used.
120
+ SECTION_NAME={"asdf"} # Any subset of characters may be used.
121
+ ```
122
+
123
+ The `B` flag always represents an option to execute in blocking mode.
127
124
 
128
- The **`"B"`** flag always represents an option to execute in blocking mode.
125
+ When listing the filters a command accepts, the letter which is passed into
126
+ `FILTERS` will be boldened. Like this: zone**f**ile
129
127
 
130
128
  #### Server
131
129
 
@@ -138,23 +136,23 @@ The **`"B"`** flag always represents an option to execute in blocking mode.
138
136
 
139
137
  #### Zone events
140
138
 
141
- `ZONE`: if none applies to all zones
139
+ The following commands apply to all zones if `ZONE` is left empty.
142
140
 
143
141
  * `zone-status([ZONE], [FILTERS={"rstefc"}])`
144
- + `FILTERS`: role `(r)`, serial `(s)`, transaction `(t)`, events `(e)`, freeze `(f)`, catalog `(c)`
142
+ + filters: **r**ole, **s**erial, **t**ransaction, **e**vents, **f**reeze, **c**atalog <!-- , **u**nixtime -->
145
143
  * `zone-reload([ZONE], [FLAGS={"BF"}])`
146
- + `FLAGS`: `F` reload modules
144
+ + the `F` flag commands to also reload modules
147
145
  * `zone-refresh([ZONE], [FLAGS="B"])`
148
146
  * `zone-retransfer([ZONE], [FLAGS="B"])`
149
147
  * `zone-notify([ZONE], [FLAGS="B"])`
150
148
  * `zone-flush([ZONE], [FILTERS="d", DATA], [FLAGS="B"])`
151
- + the outputdir `(d)` filter commands that zone(s) be flushed to path stored in the `DATA` section
149
+ + the output**d**ir filter commands that zone(s) be flushed to path stored in the `DATA` section
152
150
  * `zone-backup([ZONE], [FILTERS={"dzjtkocqZJTKOCQ"}, [DATA]], [FLAGS="B"])`
153
- + `FILTERS`
154
- - for description of the outputdir `(d)` filter see `zone-flush`
155
- - zonefile `(z)`, journal `(j)`, timers `(t)`, kaspdb `(k)`, keysonly `(o)`, catalog `(c)`, quic `(q)`
156
- - negative counterparts (eg. `nozonefile`) are symmetrical and capitalized
157
- * `zone-restore` <i>analogous to `zone-backup`</i>
151
+ + filters
152
+ - the backup**d**ir filter commands that backups be made to path stored in the `DATA` section
153
+ - **z**onefile, **j**ournal, **t**imers, **k**aspdb, keys**o**nly, **c**atalog, **q**uic
154
+ - negative counterparts (eg. no**Z**onefile) are symmetrical and capitalized
155
+ * `zone-restore` *analogous to `zone-backup`*
158
156
  * `zone-sign([ZONE], [FLAGS="B"])`
159
157
  * `zone-validate([ZONE], [FLAGS="B"])`
160
158
  * `zone-keys-load([ZONE], [FLAGS="B"])`
@@ -167,42 +165,71 @@ The **`"B"`** flag always represents an option to execute in blocking mode.
167
165
 
168
166
  #### Zone editing
169
167
 
170
- Use `"@"` as `OWNER` if you want to denote `ZONE` itself as the owner.
168
+ Use `@` as `OWNER` if you want to denote `ZONE` itself as the owner.
171
169
 
172
170
  * `zone-read([ZONE], [OWNER], [TYPE])`
173
171
  + if `ZONE` is left empty all zones are read
174
- * `zone-begin(ZONE)`
172
+ * `zone-begin(ZONE, [FILTERS="b"])`
173
+ + filters: **b**enevolent
175
174
  * `zone-commit(ZONE)`
176
175
  * `zone-abort(ZONE)`
177
176
  * `zone-diff(ZONE)`
178
- * `zone-get(ZONE, [OWNER], [TYPE])` <!-- TODO: test if OWNER and TYPE may be specified independently -->
177
+ * `zone-get(ZONE, [OWNER], [TYPE])`
179
178
  * `zone-set(ZONE, OWNER, [TTL], TYPE, DATA)`
180
179
  * `zone-unset(ZONE, OWNER, [TYPE, [DATA]])`
181
180
  * `zone-purge(ZONE, [FILTERS={ocejktf}], [FLAGS="B"])`
182
- + `FILTERS`: orphan `(o)`, catalog `(c)`, expire `(e)`, journal `(j)`, kaspdb `(k)`, timers `(t)`, zonefile `(f)`
181
+ + filters: **o**rphan, **c**atalog, **e**xpire, **j**ournal, **k**aspdb, **t**imers, zone**f**ile
183
182
  * `zone-stats(ZONE, [SECTION], [ITEM], [FLAGS="F"])`
184
183
  + `SECTION` stores the module, `ITEM` stores the counter
185
184
  + the `F` flag specifies to include 0 counters in server's response
186
185
 
187
186
  #### Configuration
188
187
 
189
- optional list schema option ('s') in FILTERS <!-- TODO: k cemu to je? -->
188
+ For the following commands:
190
189
 
191
- For the following commands:<br/>
192
- &middot; `SECTION` holds the configuration section name (eg. `template`)<br/>
193
- &middot; `ID` holds the configuration id (eg. `default`)<br/>
194
- &middot; `ITEM` holds the configuration item name (eg. `storage`)<br/>
190
+ * `SECTION` holds the configuration section name (eg. `template`)
191
+ * `ID` holds the configuration id (eg. `default`)
192
+ * `ITEM` holds the configuration item name (eg. `storage`)
195
193
 
196
- * `conf-list([SECTION, [ID], [ITEM]], [FILTERS="s"])`
194
+ <!-- hacky comment to separate markdown lists -->
195
+
196
+ * `conf-list([SECTION, [ID], [ITEM]], [FILTERS="z"|{"st"}])`
197
+ + filters:
198
+ - **z**one: list all zone names, including those from the catalog
199
+ - li**s**t: list configuration section items instead of its identifiers
200
+ - **t**ransaction: If a transaction is open (`conf-begin`) queries the
201
+ transaction's configuration schema instead of the server's
197
202
  * `conf-read([SECTION, [ID], [ITEM]])`
198
203
  * `conf-begin()`
199
204
  * `conf-commit()`
200
205
  * `conf-abort()`
201
206
  * `conf-diff([SECTION, [ID], [ITEM]])`
202
207
  * `conf-get([SECTION, [ID], [ITEM]])`
203
- * `conf-set(SECTION, ID, ITEM, [DATA], [FILTERS="s"])`
208
+ * `conf-set(SECTION, ID, ITEM, [DATA])`
204
209
  * `conf-unset([SECTION, [ID], [ITEM]], [DATA])`
205
210
 
211
+ ### Control usage<a id="control-usage"></a>
212
+
213
+ The module usage consists of several steps:
214
+
215
+ * Initialization and connection to the daemon control socket.
216
+ * One or more control operations. An operation is called by sending a command
217
+ with optional data to the daemon. The operation result has to be received
218
+ afterwards.
219
+ * Closing the connection and deinitialization.
220
+
221
+ #### Sending
222
+
223
+ There are two methods on the `KnotCtl` class which send data to the socket.
224
+
225
+ `KnotCtl.send(KnotCtlType, KnotCtlData)` is the more rudimentary one. It only
226
+ sends the section identifier along with its data, if any are provided. When
227
+ using this function users must beware of the different characteristics
228
+ regarding buffering of different unit types.
229
+
230
+ `KnotCtl.send_block(...)` is more convenient in that it always flushes by
231
+ sending a `BLOCK` unit. Otherwise the two methods are functionally equivalent.
232
+
206
233
  ### Control examples<a id="control-examples"></a>
207
234
 
208
235
  ```python3
{libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/pyproject.toml RENAMED
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "libknot"
7
- version = "3.3.14dev"
7
+ version = "3.3.16dev"
8
8
  description = "Python bindings for libknot"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.5"
{libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/setup.py RENAMED
@@ -7,7 +7,7 @@ if p.exists():
7
7
 
8
8
  setuptools.setup(
9
9
  name='libknot',
10
- version='3.3.14dev',
10
+ version='3.3.16dev',
11
11
  description='Python bindings for libknot',
12
12
  long_description=long_description,
13
13
  long_description_content_type="text/markdown",
{libknot-3.3.14.dev0 → libknot-3.3.16.dev0}/setup.cfg RENAMED
File without changes