From ead09de3b84a9500e4a12b18e687a53bbe867b90 Mon Sep 17 00:00:00 2001
From: Jan Hak <jan.hak@nic.cz>
Date: Tue, 27 Jul 2021 16:48:21 +0200
Subject: [PATCH] python: brief description of the Python API in README.md

---
 python/README.md | 78 ++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 66 insertions(+), 12 deletions(-)

diff --git a/python/README.md b/python/README.md
index 9339f37d18..eeff9d21ae 100644
--- a/python/README.md
+++ b/python/README.md
@@ -1,52 +1,106 @@
 # Libknot API in Python
 
-## Control API
+A Python interface for managing the Knot DNS daemon.
 
-Example:
+# Table of contents
+
+* [Introduction](#introduction)
+* [Control module](#control-module)
+  + [Usage](#using-the-control-module)
+  + [Example](#control-module-example)
+* [Probe module](#probe-module)
+  + [Usage](#using-the-probe-module)
+  + [Example](#probe-module-example)
+
+## Introduction
+
+If the shared `libknot.so` library isn't available in the library search path, it's
+necessary to load the library first, e.g.:
+
+```python3
+import libknot
+libknot.Knot("/usr/lib/libknot.so")
+```
+
+## Control module
+
+Using this module it's possible to create scripts for efficient tasks that
+would require complex shell scripts with multiple calls of `knotc`. For
+communication with the daemon it uses the same mechanism as the `knotc` utility,
+i.e. communication via a Unix socket.
+
+The module API is stored in `libknot.control`.
+
+### Using the Control module
+
+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.
+
+### Control module example
 
 ```python3
 import json
 import libknot.control
 
-#import libknot
-#libknot.Knot("/usr/lib/libknot.so")
-
+# Initialization
 ctl = libknot.control.KnotCtl()
 ctl.connect("/var/run/knot/knot.sock")
 
 try:
+    # Operation without parameters
     ctl.send_block(cmd="conf-begin")
     resp = ctl.receive_block()
 
+    # Operation with parameters
     ctl.send_block(cmd="conf-set", section="zone", item="domain", data="test")
     resp = ctl.receive_block()
 
     ctl.send_block(cmd="conf-commit")
     resp = ctl.receive_block()
 
+    # Operation with a result displayed in JSON format
     ctl.send_block(cmd="conf-read", section="zone", item="domain")
     resp = ctl.receive_block()
     print(json.dumps(resp, indent=4))
 finally:
+    # Deinitialization
     ctl.send(libknot.control.KnotCtlType.END)
     ctl.close()
 ```
 
-## Probe API
+## Probe module
+
+Using this module it's possible to receive traffic data from a running daemon with
+active probe module.
 
-Example:
+The module API is stored in `libknot.probe`.
+
+### Using the Probe module
+
+The module usage consists of several steps:
+
+* Initialization of one or more probe channels
+* Periodical receiving of data units from the channels and data processing
+
+### Probe module example
 
 ```python3
 import libknot.probe
 
-#import libknot
-#libknot.Knot("/usr/lib/libknot.so")
-
-probe = libknot.probe.KnotProbe("/run/knot")
+# Initialization of the first probe channel stored in `/run/knot`
+probe = libknot.probe.KnotProbe("/run/knot", 1)
 
+# Array for storing up to 8 data units
 data = libknot.probe.KnotProbeDataArray(8)
 while (True):
-    if probe.consume(data) > 0:
+    # Receiving data units with timeout of 1000 ms
+    if probe.consume(data, 1000) > 0:
+        # Printing received data units in the default format
         for item in data:
             print(item)
 ```
-- 
2.47.3