PyPI - libknot - Versions diffs - 3.3.14.dev0__tar.gz → 3.3.15.dev0__tar.gz - Mend

libknot 3.3.14.dev0tar.gz → 3.3.15.dev0tar.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

{libknot-3.3.14.dev0 → libknot-3.3.15.dev0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: libknot
-Version: 3.3.14.dev0
+Version: 3.3.15.dev0
 Summary: Python bindings for libknot
 Home-page: https://gitlab.nic.cz/knot/knot-dns/-/tree/master/python/libknot
 Author: CZ.NIC, z.s.p.o.
@@ -28,9 +28,9 @@ A Python interface for managing the Knot DNS daemon.
 * [Introduction](#introduction)
 * [Control module](#control-module)
-  + [Usage](#control-usage)
   + [Protocol reference](#kctl-proto)
   + [Commands reference](#kctl-cmds)
+  + [Usage](#control-usage)
   + [Examples](#control-examples)
 * [Probe module](#probe-module)
   + [Probe usage](#probe-usage)
@@ -58,25 +58,15 @@ i.e. communication via a Unix socket.
 The module API is stored in `libknot.control`.
-### Control usage<a id="control-usage"></a>
-The module usage consists of several steps:
-* Initialization and connection to the daemon control socket.
-* One or more control operations. An operation is called by sending a command
-  with optional data to the daemon. The operation result has to be received
-  afterwards.
-* Closing the connection and deinitialization.
 ### Protocol overview<a id="kctl-proto"></a>
 Connections are supposed to be short-lived, because maintaining a passive
-connection is costly for the server. Therefore the expected usage of the ctl
+connection is costly for the server. Therefore the expected usage of the CTL
 interface is to always open a new connection on demand, then close it once it's
 not immediately needed.
-Messages are composed of units. These are of four types whose identifiers are
-defined in `libknot.control.KnotCtlType`:
+Messages are composed of units. These are of four types the identifiers of
+which are defined in `libknot.control.KnotCtlType`:
 | Type    | Description                                                | IO action |
 | ------- | ---------------------------------------------------------- | --------- |
@@ -85,6 +75,9 @@ defined in `libknot.control.KnotCtlType`:
 | `EXTRA` | Additional data.                                           | cache     |
 | `BLOCK` | End of data block.                                         | flush     |
+`DATA` and `EXTRA` units aren't immediately sent, rather they're buffered and
+then sent along with the next `END` or `BLOCK` unit.
 A unit can optionaly hold data, though this is only meaningful for the `DATA`
 and `EXTRA` types. The data consists of several sections of which usually only
 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.
 The data section identifiers are defined in `libknot.control.KnotCtlDataIdx`:
-| Section name | Description                                            |
-| ------------ | ------------------------------------------------------ |
-| `COMMAND`    | Command name.                                          |
-| `FLAGS`      | Command flags.                                         |
-| `ERROR`      | Error message.                                         |
-| `SECTION`    | Configuration section name.                            |
-| `ITEM`       | Configuration item name.                               |
-| `ID`         | Configuration item identifier.                         |
-| `ZONE`       | Zone name.                                             |
-| `OWNER`      | Zone record owner                                      |
-| `TTL`        | Zone record TTL.                                       |
-| `TYPE`       | Zone record type name.                                 |
-| `DATA`       | Configuration item/zone record data.                   |
-| `FILTERS`    | Command options or filters for output data processing. |
+| Section name | `send_block()` arg name | Description                                            |
+| ------------ | ----------------------- | ------------------------------------------------------ |
+| `COMMAND`    | cmd                     | Command name.                                          |
+| `FLAGS`      | flags                   | Command flags.                                         |
+| `ERROR`      | *n/a*                   | Error message. Only sent by the server.                |
+| `SECTION`    | section                 | Configuration section name.                            |
+| `ITEM`       | item                    | Configuration item name.                               |
+| `ID`         | identifier              | Configuration item identifier.                         |
+| `ZONE`       | zone                    | Zone name.                                             |
+| `OWNER`      | owner                   | Zone record owner                                      |
+| `TTL`        | ttl                     | Zone record TTL.                                       |
+| `TYPE`       | rtype                   | Zone record type name.                                 |
+| `DATA`       | data                    | Configuration item/zone record data.                   |
+| `FILTERS`    | filters                 | Command options or filters for output data processing. |
 ### Commands reference<a id="kctl-cmds"></a>
@@ -115,17 +108,19 @@ of the commands' semantics, please consult the
 A concise notation is used for command synopsis:
-<pre>
-cmd-name(SECTION_NAME,
-    [OPTIONAL_SECTION="literal value"],
-    [OPT_SECTION1, OPT_SECTION2],      # Sections must be present together or not at all
-    [OPT_MASTER, [OPT_SLAVE]],         # OPT_SLAVE may only appear if OPT_MASTER is present
-    SECTION_NAME2="option1"|"option2", # Either one or the other literal may be used
-    SECTION_NAME3={"asdf"},            # any subset of characters
-)
-</pre>
+```
+# command "cmd-name" accepts section of type SECTION_NAME and optionally
+# another section of type OPT_SECTION
+cmd-name(SECTION_NAME, [OPT_SECTION])
+[OPT_SECTION="literal value"],   # Optional section with fixed expected value.
+[SECTION1, SECTION2]             # Sections must be present together or not at all.
+[PRIMARY, [SECONDARY]]           # SECONDARY may only appear if PRIMARY is present.
+SECTION_NAME="option1"|"option2" # Either one or the other literal may be used.
+SECTION_NAME={"asdf"}            # Any subset of characters may be used.
+```
-The **`"B"`** flag always represents an option to execute in blocking mode.
+The `B` flag always represents an option to execute in blocking mode.
 #### Server
@@ -138,23 +133,23 @@ The **`"B"`** flag always represents an option to execute in blocking mode.
 #### Zone events
-`ZONE`: if none applies to all zones
+The following commands apply to all zones if `ZONE` is left empty.
 * `zone-status([ZONE], [FILTERS={"rstefc"}])`
-  + `FILTERS`: role `(r)`, serial `(s)`, transaction `(t)`, events `(e)`, freeze `(f)`, catalog `(c)`
+  + filters: **r**ole, **s**erial, **t**ransaction, **e**vents, **f**reeze, **c**atalog <!-- , **u**nixtime -->
 * `zone-reload([ZONE], [FLAGS={"BF"}])`
-  + `FLAGS`: `F` reload modules
+  + the `F` flag commands to also reload modules
 * `zone-refresh([ZONE], [FLAGS="B"])`
 * `zone-retransfer([ZONE], [FLAGS="B"])`
 * `zone-notify([ZONE], [FLAGS="B"])`
 * `zone-flush([ZONE], [FILTERS="d", DATA], [FLAGS="B"])`
-  + the outputdir `(d)` filter commands that zone(s) be flushed to path stored in the `DATA` section
+  + the output**d**ir filter commands that zone(s) be flushed to path stored in the `DATA` section
 * `zone-backup([ZONE], [FILTERS={"dzjtkocqZJTKOCQ"}, [DATA]], [FLAGS="B"])`
-  + `FILTERS`
-    - for description of the outputdir `(d)` filter see `zone-flush`
-    - zonefile `(z)`, journal `(j)`, timers `(t)`, kaspdb `(k)`, keysonly `(o)`, catalog `(c)`, quic `(q)`
-    - negative counterparts (eg. `nozonefile`) are symmetrical and capitalized
-* `zone-restore` <i>analogous to `zone-backup`</i>
+  + filters
+    - the backup**d**ir filter commands that backups be made to path stored in the `DATA` section
+    - **z**onefile, **j**ournal, **t**imers, **k**aspdb, keys**o**nly, **c**atalog, **q**uic
+    - negative counterparts (eg. no**Z**onefile) are symmetrical and capitalized
+* `zone-restore` *analogous to `zone-backup`*
 * `zone-sign([ZONE], [FLAGS="B"])`
 * `zone-validate([ZONE], [FLAGS="B"])`
 * `zone-keys-load([ZONE], [FLAGS="B"])`
@@ -167,42 +162,71 @@ The **`"B"`** flag always represents an option to execute in blocking mode.
 #### Zone editing
-Use `"@"` as `OWNER` if you want to denote `ZONE` itself as the owner.
+Use `@` as `OWNER` if you want to denote `ZONE` itself as the owner.
 * `zone-read([ZONE], [OWNER], [TYPE])`
   + if `ZONE` is left empty all zones are read
-* `zone-begin(ZONE)`
+* `zone-begin(ZONE, [FILTERS="b"])`
+  + filters: **b**enevolent
 * `zone-commit(ZONE)`
 * `zone-abort(ZONE)`
 * `zone-diff(ZONE)`
-* `zone-get(ZONE, [OWNER], [TYPE])` <!-- TODO: test if OWNER and TYPE may be specified independently -->
+* `zone-get(ZONE, [OWNER], [TYPE])`
 * `zone-set(ZONE, OWNER, [TTL], TYPE, DATA)`
 * `zone-unset(ZONE, OWNER, [TYPE, [DATA]])`
 * `zone-purge(ZONE, [FILTERS={ocejktf}], [FLAGS="B"])`
-  + `FILTERS`: orphan `(o)`, catalog `(c)`, expire `(e)`, journal `(j)`, kaspdb `(k)`, timers `(t)`, zonefile `(f)`
+  + filters: **o**rphan, **c**atalog, **e**xpire, **j**ournal, **k**aspdb, **t**imers, zone**f**ile
 * `zone-stats(ZONE, [SECTION], [ITEM], [FLAGS="F"])`
   + `SECTION` stores the module, `ITEM` stores the counter
   + the `F` flag specifies to include 0 counters in server's response
 #### Configuration
-optional list schema option ('s') in FILTERS <!-- TODO: k cemu to je? -->
+For the following commands:
-For the following commands:<br/>
- &middot; `SECTION` holds the configuration section name (eg. `template`)<br/>
- &middot; `ID` holds the configuration id (eg. `default`)<br/>
- &middot; `ITEM` holds the configuration item name (eg. `storage`)<br/>
+* `SECTION` holds the configuration section name (eg. `template`)
+* `ID` holds the configuration id (eg. `default`)
+* `ITEM` holds the configuration item name (eg. `storage`)
-* `conf-list([SECTION, [ID], [ITEM]], [FILTERS="s"])`
+<!-- hacky comment to separate markdown lists -->
+* `conf-list([SECTION, [ID], [ITEM]], [FILTERS="z"|{"st"}])`
+  + filters:
+    - **z**one: list all zone names, including those from the catalog
+    - li**s**t: list configuration section items instead of its identifiers
+    - **t**ransaction: If a transaction is open (`conf-begin`) queries the
+      transaction's configuration schema instead of the server's
 * `conf-read([SECTION, [ID], [ITEM]])`
 * `conf-begin()`
 * `conf-commit()`
 * `conf-abort()`
 * `conf-diff([SECTION, [ID], [ITEM]])`
 * `conf-get([SECTION, [ID], [ITEM]])`
-* `conf-set(SECTION, ID, ITEM, [DATA], [FILTERS="s"])`
+* `conf-set(SECTION, ID, ITEM, [DATA])`
 * `conf-unset([SECTION, [ID], [ITEM]], [DATA])`
+### Control usage<a id="control-usage"></a>
+The module usage consists of several steps:
+* Initialization and connection to the daemon control socket.
+* One or more control operations. An operation is called by sending a command
+  with optional data to the daemon. The operation result has to be received
+  afterwards.
+* Closing the connection and deinitialization.
+#### Sending
+There are two methods on the `KnotCtl` class which send data to the socket.
+`KnotCtl.send(KnotCtlType, KnotCtlData)` is the more rudimentary one. It only
+sends the section identifier along with its data, if any are provided. When
+using this function users must beware of the different characteristics
+regarding buffering of different unit types.
+`KnotCtl.send_block(...)` is more convenient in that it always flushes by
+sending a `BLOCK` unit. Otherwise the two methods are functionally equivalent.
 ### Control examples<a id="control-examples"></a>
 ```python3

{libknot-3.3.14.dev0 → libknot-3.3.15.dev0}/README.md RENAMED Viewed

@@ -6,9 +6,9 @@ A Python interface for managing the Knot DNS daemon.
 * [Introduction](#introduction)
 * [Control module](#control-module)
-  + [Usage](#control-usage)
   + [Protocol reference](#kctl-proto)
   + [Commands reference](#kctl-cmds)
+  + [Usage](#control-usage)
   + [Examples](#control-examples)
 * [Probe module](#probe-module)
   + [Probe usage](#probe-usage)
@@ -36,25 +36,15 @@ i.e. communication via a Unix socket.
 The module API is stored in `libknot.control`.
-### Control usage<a id="control-usage"></a>
-The module usage consists of several steps:
-* Initialization and connection to the daemon control socket.
-* One or more control operations. An operation is called by sending a command
-  with optional data to the daemon. The operation result has to be received
-  afterwards.
-* Closing the connection and deinitialization.
 ### Protocol overview<a id="kctl-proto"></a>
 Connections are supposed to be short-lived, because maintaining a passive
-connection is costly for the server. Therefore the expected usage of the ctl
+connection is costly for the server. Therefore the expected usage of the CTL
 interface is to always open a new connection on demand, then close it once it's
 not immediately needed.
-Messages are composed of units. These are of four types whose identifiers are
-defined in `libknot.control.KnotCtlType`:
+Messages are composed of units. These are of four types the identifiers of
+which are defined in `libknot.control.KnotCtlType`:
 | Type    | Description                                                | IO action |
 | ------- | ---------------------------------------------------------- | --------- |
@@ -63,6 +53,9 @@ defined in `libknot.control.KnotCtlType`:
 | `EXTRA` | Additional data.                                           | cache     |
 | `BLOCK` | End of data block.                                         | flush     |
+`DATA` and `EXTRA` units aren't immediately sent, rather they're buffered and
+then sent along with the next `END` or `BLOCK` unit.
 A unit can optionaly hold data, though this is only meaningful for the `DATA`
 and `EXTRA` types. The data consists of several sections of which usually only
 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.
 The data section identifiers are defined in `libknot.control.KnotCtlDataIdx`:
-| Section name | Description                                            |
-| ------------ | ------------------------------------------------------ |
-| `COMMAND`    | Command name.                                          |
-| `FLAGS`      | Command flags.                                         |
-| `ERROR`      | Error message.                                         |
-| `SECTION`    | Configuration section name.                            |
-| `ITEM`       | Configuration item name.                               |
-| `ID`         | Configuration item identifier.                         |
-| `ZONE`       | Zone name.                                             |
-| `OWNER`      | Zone record owner                                      |
-| `TTL`        | Zone record TTL.                                       |
-| `TYPE`       | Zone record type name.                                 |
-| `DATA`       | Configuration item/zone record data.                   |
-| `FILTERS`    | Command options or filters for output data processing. |
+| Section name | `send_block()` arg name | Description                                            |
+| ------------ | ----------------------- | ------------------------------------------------------ |
+| `COMMAND`    | cmd                     | Command name.                                          |
+| `FLAGS`      | flags                   | Command flags.                                         |
+| `ERROR`      | *n/a*                   | Error message. Only sent by the server.                |
+| `SECTION`    | section                 | Configuration section name.                            |
+| `ITEM`       | item                    | Configuration item name.                               |
+| `ID`         | identifier              | Configuration item identifier.                         |
+| `ZONE`       | zone                    | Zone name.                                             |
+| `OWNER`      | owner                   | Zone record owner                                      |
+| `TTL`        | ttl                     | Zone record TTL.                                       |
+| `TYPE`       | rtype                   | Zone record type name.                                 |
+| `DATA`       | data                    | Configuration item/zone record data.                   |
+| `FILTERS`    | filters                 | Command options or filters for output data processing. |
 ### Commands reference<a id="kctl-cmds"></a>
@@ -93,17 +86,19 @@ of the commands' semantics, please consult the
 A concise notation is used for command synopsis:
-<pre>
-cmd-name(SECTION_NAME,
-    [OPTIONAL_SECTION="literal value"],
-    [OPT_SECTION1, OPT_SECTION2],      # Sections must be present together or not at all
-    [OPT_MASTER, [OPT_SLAVE]],         # OPT_SLAVE may only appear if OPT_MASTER is present
-    SECTION_NAME2="option1"|"option2", # Either one or the other literal may be used
-    SECTION_NAME3={"asdf"},            # any subset of characters
-)
-</pre>
+```
+# command "cmd-name" accepts section of type SECTION_NAME and optionally
+# another section of type OPT_SECTION
+cmd-name(SECTION_NAME, [OPT_SECTION])
+[OPT_SECTION="literal value"],   # Optional section with fixed expected value.
+[SECTION1, SECTION2]             # Sections must be present together or not at all.
+[PRIMARY, [SECONDARY]]           # SECONDARY may only appear if PRIMARY is present.
+SECTION_NAME="option1"|"option2" # Either one or the other literal may be used.
+SECTION_NAME={"asdf"}            # Any subset of characters may be used.
+```
-The **`"B"`** flag always represents an option to execute in blocking mode.
+The `B` flag always represents an option to execute in blocking mode.
 #### Server
@@ -116,23 +111,23 @@ The **`"B"`** flag always represents an option to execute in blocking mode.
 #### Zone events
-`ZONE`: if none applies to all zones
+The following commands apply to all zones if `ZONE` is left empty.
 * `zone-status([ZONE], [FILTERS={"rstefc"}])`
-  + `FILTERS`: role `(r)`, serial `(s)`, transaction `(t)`, events `(e)`, freeze `(f)`, catalog `(c)`
+  + filters: **r**ole, **s**erial, **t**ransaction, **e**vents, **f**reeze, **c**atalog <!-- , **u**nixtime -->
 * `zone-reload([ZONE], [FLAGS={"BF"}])`
-  + `FLAGS`: `F` reload modules
+  + the `F` flag commands to also reload modules
 * `zone-refresh([ZONE], [FLAGS="B"])`
 * `zone-retransfer([ZONE], [FLAGS="B"])`
 * `zone-notify([ZONE], [FLAGS="B"])`
 * `zone-flush([ZONE], [FILTERS="d", DATA], [FLAGS="B"])`
-  + the outputdir `(d)` filter commands that zone(s) be flushed to path stored in the `DATA` section
+  + the output**d**ir filter commands that zone(s) be flushed to path stored in the `DATA` section
 * `zone-backup([ZONE], [FILTERS={"dzjtkocqZJTKOCQ"}, [DATA]], [FLAGS="B"])`
-  + `FILTERS`
-    - for description of the outputdir `(d)` filter see `zone-flush`
-    - zonefile `(z)`, journal `(j)`, timers `(t)`, kaspdb `(k)`, keysonly `(o)`, catalog `(c)`, quic `(q)`
-    - negative counterparts (eg. `nozonefile`) are symmetrical and capitalized
-* `zone-restore` <i>analogous to `zone-backup`</i>
+  + filters
+    - the backup**d**ir filter commands that backups be made to path stored in the `DATA` section
+    - **z**onefile, **j**ournal, **t**imers, **k**aspdb, keys**o**nly, **c**atalog, **q**uic
+    - negative counterparts (eg. no**Z**onefile) are symmetrical and capitalized
+* `zone-restore` *analogous to `zone-backup`*
 * `zone-sign([ZONE], [FLAGS="B"])`
 * `zone-validate([ZONE], [FLAGS="B"])`
 * `zone-keys-load([ZONE], [FLAGS="B"])`
@@ -145,42 +140,71 @@ The **`"B"`** flag always represents an option to execute in blocking mode.
 #### Zone editing
-Use `"@"` as `OWNER` if you want to denote `ZONE` itself as the owner.
+Use `@` as `OWNER` if you want to denote `ZONE` itself as the owner.
 * `zone-read([ZONE], [OWNER], [TYPE])`
   + if `ZONE` is left empty all zones are read
-* `zone-begin(ZONE)`
+* `zone-begin(ZONE, [FILTERS="b"])`
+  + filters: **b**enevolent
 * `zone-commit(ZONE)`
 * `zone-abort(ZONE)`
 * `zone-diff(ZONE)`
-* `zone-get(ZONE, [OWNER], [TYPE])` <!-- TODO: test if OWNER and TYPE may be specified independently -->
+* `zone-get(ZONE, [OWNER], [TYPE])`
 * `zone-set(ZONE, OWNER, [TTL], TYPE, DATA)`
 * `zone-unset(ZONE, OWNER, [TYPE, [DATA]])`
 * `zone-purge(ZONE, [FILTERS={ocejktf}], [FLAGS="B"])`
-  + `FILTERS`: orphan `(o)`, catalog `(c)`, expire `(e)`, journal `(j)`, kaspdb `(k)`, timers `(t)`, zonefile `(f)`
+  + filters: **o**rphan, **c**atalog, **e**xpire, **j**ournal, **k**aspdb, **t**imers, zone**f**ile
 * `zone-stats(ZONE, [SECTION], [ITEM], [FLAGS="F"])`
   + `SECTION` stores the module, `ITEM` stores the counter
   + the `F` flag specifies to include 0 counters in server's response
 #### Configuration
-optional list schema option ('s') in FILTERS <!-- TODO: k cemu to je? -->
+For the following commands:
-For the following commands:<br/>
- &middot; `SECTION` holds the configuration section name (eg. `template`)<br/>
- &middot; `ID` holds the configuration id (eg. `default`)<br/>
- &middot; `ITEM` holds the configuration item name (eg. `storage`)<br/>
+* `SECTION` holds the configuration section name (eg. `template`)
+* `ID` holds the configuration id (eg. `default`)
+* `ITEM` holds the configuration item name (eg. `storage`)
-* `conf-list([SECTION, [ID], [ITEM]], [FILTERS="s"])`
+<!-- hacky comment to separate markdown lists -->
+* `conf-list([SECTION, [ID], [ITEM]], [FILTERS="z"|{"st"}])`
+  + filters:
+    - **z**one: list all zone names, including those from the catalog
+    - li**s**t: list configuration section items instead of its identifiers
+    - **t**ransaction: If a transaction is open (`conf-begin`) queries the
+      transaction's configuration schema instead of the server's
 * `conf-read([SECTION, [ID], [ITEM]])`
 * `conf-begin()`
 * `conf-commit()`
 * `conf-abort()`
 * `conf-diff([SECTION, [ID], [ITEM]])`
 * `conf-get([SECTION, [ID], [ITEM]])`
-* `conf-set(SECTION, ID, ITEM, [DATA], [FILTERS="s"])`
+* `conf-set(SECTION, ID, ITEM, [DATA])`
 * `conf-unset([SECTION, [ID], [ITEM]], [DATA])`
+### Control usage<a id="control-usage"></a>
+The module usage consists of several steps:
+* Initialization and connection to the daemon control socket.
+* One or more control operations. An operation is called by sending a command
+  with optional data to the daemon. The operation result has to be received
+  afterwards.
+* Closing the connection and deinitialization.
+#### Sending
+There are two methods on the `KnotCtl` class which send data to the socket.
+`KnotCtl.send(KnotCtlType, KnotCtlData)` is the more rudimentary one. It only
+sends the section identifier along with its data, if any are provided. When
+using this function users must beware of the different characteristics
+regarding buffering of different unit types.
+`KnotCtl.send_block(...)` is more convenient in that it always flushes by
+sending a `BLOCK` unit. Otherwise the two methods are functionally equivalent.
 ### Control examples<a id="control-examples"></a>
 ```python3

{libknot-3.3.14.dev0 → libknot-3.3.15.dev0}/libknot.egg-info/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: libknot
-Version: 3.3.14.dev0
+Version: 3.3.15.dev0
 Summary: Python bindings for libknot
 Home-page: https://gitlab.nic.cz/knot/knot-dns/-/tree/master/python/libknot
 Author: CZ.NIC, z.s.p.o.
@@ -28,9 +28,9 @@ A Python interface for managing the Knot DNS daemon.
 * [Introduction](#introduction)
 * [Control module](#control-module)
-  + [Usage](#control-usage)
   + [Protocol reference](#kctl-proto)
   + [Commands reference](#kctl-cmds)
+  + [Usage](#control-usage)
   + [Examples](#control-examples)
 * [Probe module](#probe-module)
   + [Probe usage](#probe-usage)
@@ -58,25 +58,15 @@ i.e. communication via a Unix socket.
 The module API is stored in `libknot.control`.
-### Control usage<a id="control-usage"></a>
-The module usage consists of several steps:
-* Initialization and connection to the daemon control socket.
-* One or more control operations. An operation is called by sending a command
-  with optional data to the daemon. The operation result has to be received
-  afterwards.
-* Closing the connection and deinitialization.
 ### Protocol overview<a id="kctl-proto"></a>
 Connections are supposed to be short-lived, because maintaining a passive
-connection is costly for the server. Therefore the expected usage of the ctl
+connection is costly for the server. Therefore the expected usage of the CTL
 interface is to always open a new connection on demand, then close it once it's
 not immediately needed.
-Messages are composed of units. These are of four types whose identifiers are
-defined in `libknot.control.KnotCtlType`:
+Messages are composed of units. These are of four types the identifiers of
+which are defined in `libknot.control.KnotCtlType`:
 | Type    | Description                                                | IO action |
 | ------- | ---------------------------------------------------------- | --------- |
@@ -85,6 +75,9 @@ defined in `libknot.control.KnotCtlType`:
 | `EXTRA` | Additional data.                                           | cache     |
 | `BLOCK` | End of data block.                                         | flush     |
+`DATA` and `EXTRA` units aren't immediately sent, rather they're buffered and
+then sent along with the next `END` or `BLOCK` unit.
 A unit can optionaly hold data, though this is only meaningful for the `DATA`
 and `EXTRA` types. The data consists of several sections of which usually only
 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.
 The data section identifiers are defined in `libknot.control.KnotCtlDataIdx`:
-| Section name | Description                                            |
-| ------------ | ------------------------------------------------------ |
-| `COMMAND`    | Command name.                                          |
-| `FLAGS`      | Command flags.                                         |
-| `ERROR`      | Error message.                                         |
-| `SECTION`    | Configuration section name.                            |
-| `ITEM`       | Configuration item name.                               |
-| `ID`         | Configuration item identifier.                         |
-| `ZONE`       | Zone name.                                             |
-| `OWNER`      | Zone record owner                                      |
-| `TTL`        | Zone record TTL.                                       |
-| `TYPE`       | Zone record type name.                                 |
-| `DATA`       | Configuration item/zone record data.                   |
-| `FILTERS`    | Command options or filters for output data processing. |
+| Section name | `send_block()` arg name | Description                                            |
+| ------------ | ----------------------- | ------------------------------------------------------ |
+| `COMMAND`    | cmd                     | Command name.                                          |
+| `FLAGS`      | flags                   | Command flags.                                         |
+| `ERROR`      | *n/a*                   | Error message. Only sent by the server.                |
+| `SECTION`    | section                 | Configuration section name.                            |
+| `ITEM`       | item                    | Configuration item name.                               |
+| `ID`         | identifier              | Configuration item identifier.                         |
+| `ZONE`       | zone                    | Zone name.                                             |
+| `OWNER`      | owner                   | Zone record owner                                      |
+| `TTL`        | ttl                     | Zone record TTL.                                       |
+| `TYPE`       | rtype                   | Zone record type name.                                 |
+| `DATA`       | data                    | Configuration item/zone record data.                   |
+| `FILTERS`    | filters                 | Command options or filters for output data processing. |
 ### Commands reference<a id="kctl-cmds"></a>
@@ -115,17 +108,19 @@ of the commands' semantics, please consult the
 A concise notation is used for command synopsis:
-<pre>
-cmd-name(SECTION_NAME,
-    [OPTIONAL_SECTION="literal value"],
-    [OPT_SECTION1, OPT_SECTION2],      # Sections must be present together or not at all
-    [OPT_MASTER, [OPT_SLAVE]],         # OPT_SLAVE may only appear if OPT_MASTER is present
-    SECTION_NAME2="option1"|"option2", # Either one or the other literal may be used
-    SECTION_NAME3={"asdf"},            # any subset of characters
-)
-</pre>
+```
+# command "cmd-name" accepts section of type SECTION_NAME and optionally
+# another section of type OPT_SECTION
+cmd-name(SECTION_NAME, [OPT_SECTION])
+[OPT_SECTION="literal value"],   # Optional section with fixed expected value.
+[SECTION1, SECTION2]             # Sections must be present together or not at all.
+[PRIMARY, [SECONDARY]]           # SECONDARY may only appear if PRIMARY is present.
+SECTION_NAME="option1"|"option2" # Either one or the other literal may be used.
+SECTION_NAME={"asdf"}            # Any subset of characters may be used.
+```
-The **`"B"`** flag always represents an option to execute in blocking mode.
+The `B` flag always represents an option to execute in blocking mode.
 #### Server
@@ -138,23 +133,23 @@ The **`"B"`** flag always represents an option to execute in blocking mode.
 #### Zone events
-`ZONE`: if none applies to all zones
+The following commands apply to all zones if `ZONE` is left empty.
 * `zone-status([ZONE], [FILTERS={"rstefc"}])`
-  + `FILTERS`: role `(r)`, serial `(s)`, transaction `(t)`, events `(e)`, freeze `(f)`, catalog `(c)`
+  + filters: **r**ole, **s**erial, **t**ransaction, **e**vents, **f**reeze, **c**atalog <!-- , **u**nixtime -->
 * `zone-reload([ZONE], [FLAGS={"BF"}])`
-  + `FLAGS`: `F` reload modules
+  + the `F` flag commands to also reload modules
 * `zone-refresh([ZONE], [FLAGS="B"])`
 * `zone-retransfer([ZONE], [FLAGS="B"])`
 * `zone-notify([ZONE], [FLAGS="B"])`
 * `zone-flush([ZONE], [FILTERS="d", DATA], [FLAGS="B"])`
-  + the outputdir `(d)` filter commands that zone(s) be flushed to path stored in the `DATA` section
+  + the output**d**ir filter commands that zone(s) be flushed to path stored in the `DATA` section
 * `zone-backup([ZONE], [FILTERS={"dzjtkocqZJTKOCQ"}, [DATA]], [FLAGS="B"])`
-  + `FILTERS`
-    - for description of the outputdir `(d)` filter see `zone-flush`
-    - zonefile `(z)`, journal `(j)`, timers `(t)`, kaspdb `(k)`, keysonly `(o)`, catalog `(c)`, quic `(q)`
-    - negative counterparts (eg. `nozonefile`) are symmetrical and capitalized
-* `zone-restore` <i>analogous to `zone-backup`</i>
+  + filters
+    - the backup**d**ir filter commands that backups be made to path stored in the `DATA` section
+    - **z**onefile, **j**ournal, **t**imers, **k**aspdb, keys**o**nly, **c**atalog, **q**uic
+    - negative counterparts (eg. no**Z**onefile) are symmetrical and capitalized
+* `zone-restore` *analogous to `zone-backup`*
 * `zone-sign([ZONE], [FLAGS="B"])`
 * `zone-validate([ZONE], [FLAGS="B"])`
 * `zone-keys-load([ZONE], [FLAGS="B"])`
@@ -167,42 +162,71 @@ The **`"B"`** flag always represents an option to execute in blocking mode.
 #### Zone editing
-Use `"@"` as `OWNER` if you want to denote `ZONE` itself as the owner.
+Use `@` as `OWNER` if you want to denote `ZONE` itself as the owner.
 * `zone-read([ZONE], [OWNER], [TYPE])`
   + if `ZONE` is left empty all zones are read
-* `zone-begin(ZONE)`
+* `zone-begin(ZONE, [FILTERS="b"])`
+  + filters: **b**enevolent
 * `zone-commit(ZONE)`
 * `zone-abort(ZONE)`
 * `zone-diff(ZONE)`
-* `zone-get(ZONE, [OWNER], [TYPE])` <!-- TODO: test if OWNER and TYPE may be specified independently -->
+* `zone-get(ZONE, [OWNER], [TYPE])`
 * `zone-set(ZONE, OWNER, [TTL], TYPE, DATA)`
 * `zone-unset(ZONE, OWNER, [TYPE, [DATA]])`
 * `zone-purge(ZONE, [FILTERS={ocejktf}], [FLAGS="B"])`
-  + `FILTERS`: orphan `(o)`, catalog `(c)`, expire `(e)`, journal `(j)`, kaspdb `(k)`, timers `(t)`, zonefile `(f)`
+  + filters: **o**rphan, **c**atalog, **e**xpire, **j**ournal, **k**aspdb, **t**imers, zone**f**ile
 * `zone-stats(ZONE, [SECTION], [ITEM], [FLAGS="F"])`
   + `SECTION` stores the module, `ITEM` stores the counter
   + the `F` flag specifies to include 0 counters in server's response
 #### Configuration
-optional list schema option ('s') in FILTERS <!-- TODO: k cemu to je? -->
+For the following commands:
-For the following commands:<br/>
- &middot; `SECTION` holds the configuration section name (eg. `template`)<br/>
- &middot; `ID` holds the configuration id (eg. `default`)<br/>
- &middot; `ITEM` holds the configuration item name (eg. `storage`)<br/>
+* `SECTION` holds the configuration section name (eg. `template`)
+* `ID` holds the configuration id (eg. `default`)
+* `ITEM` holds the configuration item name (eg. `storage`)
-* `conf-list([SECTION, [ID], [ITEM]], [FILTERS="s"])`
+<!-- hacky comment to separate markdown lists -->
+* `conf-list([SECTION, [ID], [ITEM]], [FILTERS="z"|{"st"}])`
+  + filters:
+    - **z**one: list all zone names, including those from the catalog
+    - li**s**t: list configuration section items instead of its identifiers
+    - **t**ransaction: If a transaction is open (`conf-begin`) queries the
+      transaction's configuration schema instead of the server's
 * `conf-read([SECTION, [ID], [ITEM]])`
 * `conf-begin()`
 * `conf-commit()`
 * `conf-abort()`
 * `conf-diff([SECTION, [ID], [ITEM]])`
 * `conf-get([SECTION, [ID], [ITEM]])`
-* `conf-set(SECTION, ID, ITEM, [DATA], [FILTERS="s"])`
+* `conf-set(SECTION, ID, ITEM, [DATA])`
 * `conf-unset([SECTION, [ID], [ITEM]], [DATA])`
+### Control usage<a id="control-usage"></a>
+The module usage consists of several steps:
+* Initialization and connection to the daemon control socket.
+* One or more control operations. An operation is called by sending a command
+  with optional data to the daemon. The operation result has to be received
+  afterwards.
+* Closing the connection and deinitialization.
+#### Sending
+There are two methods on the `KnotCtl` class which send data to the socket.
+`KnotCtl.send(KnotCtlType, KnotCtlData)` is the more rudimentary one. It only
+sends the section identifier along with its data, if any are provided. When
+using this function users must beware of the different characteristics
+regarding buffering of different unit types.
+`KnotCtl.send_block(...)` is more convenient in that it always flushes by
+sending a `BLOCK` unit. Otherwise the two methods are functionally equivalent.
 ### Control examples<a id="control-examples"></a>
 ```python3

{libknot-3.3.14.dev0 → libknot-3.3.15.dev0}/pyproject.toml RENAMED Viewed

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 [project]
 name = "libknot"
-version = "3.3.14dev"
+version = "3.3.15dev"
 description = "Python bindings for libknot"
 readme = "README.md"
 requires-python = ">=3.5"

{libknot-3.3.14.dev0 → libknot-3.3.15.dev0}/setup.py RENAMED Viewed

@@ -7,7 +7,7 @@ if p.exists():
 setuptools.setup(
     name='libknot',
-    version='3.3.14dev',
+    version='3.3.15dev',
     description='Python bindings for libknot',
     long_description=long_description,
     long_description_content_type="text/markdown",