bin/djbdns-logparse.py: add a dosctring for decode_serial().

[djbdns-logparse.git] / bin / djbdns-logparse.py

diff --git a/bin/djbdns-logparse.py b/bin/djbdns-logparse.py
index f2a69b5a333a6b4fb3c421661bd158972d988144..1df2bf8ce8340297ba8b9882ed6d1a22a0f05c5e 100755 (executable)
--- a/bin/djbdns-logparse.py
+++ b/bin/djbdns-logparse.py
@@ -1,5 +1,5 @@
 #!/usr/bin/python3
-"""
+r"""
 Convert tinydns and dnscache logs to human-readable form
 """
 
@@ -80,7 +80,7 @@ query_drop_reason = {
 
 
 def convert_ip(ip : str) -> str:
-    """
+    r"""
     Convert a hex string representing an IP address to
     human-readable form.
 
@@ -125,6 +125,9 @@ def decode_client(words : list, i : int):
       1. clientip:clientport, used by tcpopen/tcpclose entries,
       2. clientip:clientport:id, used by "query" entries.
 
+    We convert each part from hex to decimal, and in the second
+    format, separate the packet id from the client information.
+
     Parameters
     ----------
 
@@ -166,13 +169,13 @@ def decode_client(words : list, i : int):
         id = int(chunks[2], 16)
         words[i] += f" (id {id})"
 
-def decode_ip(words, i):
+def decode_ip(words : list, i : int):
     r"""
     Helper function to decode the ip field in a dnscache log
     entry.
 
     A single "serverip" field is present in the lame, nodata,
-    nxdomain, and rr entry types.
+    nxdomain, and rr entry types. We convert it from hex to decimal.
 
     Parameters
     ----------
@@ -202,23 +205,86 @@ def decode_ip(words, i):
         >>> decode_ip(words, 1)
         >>> words
         ['foo', '0000:0000:0000:0000:0000:ffff:7f00:0001', 'bar', 'quux']
-
     """
     words[i] = convert_ip(words[i])
 
-def decode_ttl(words, i):
+def decode_ttl(words : list, i : int):
+    r"""
+    Helper function to decode the ttl field in a dnscache log
+    entry.
+
+    A single "ttl" field is present in the nodata, nxdomain, and
+    rr entry types. We prefix it with "TTL=" so that its meaning
+    is clear in the human-readable logs.
+
+    Parameters
+    ----------
+
+    words : list
+        The ``words`` list (a list of fields) from
+        :func:`handle_dnscache_log`.
+
+    i : int
+        The index of the ttl field within ``words``
+
+    Returns
+    -------
+
+    Nothing; the ``i``th entry in the ``words`` list is modified
+    in-place.
+
+    Examples
+    --------
+
+        >>> words = ["c0a80101", "20865", "1", "www.example.com.", "5db8d822"]
+        >>> decode_ttl(words, 1)
+        >>> words
+        ['c0a80101', 'TTL=20865', '1', 'www.example.com.', '5db8d822']
+
+    """
     words[i] = f"TTL={words[i]}"
 
-def decode_serial(words, i):
-    serial = int(words[i])
-    words[i] = f"#{serial}"
+def decode_serial(words : list, i : int):
+    r"""
+    Helper function to decode the serial field in a dnscache log
+    entry.
+
+    A single "serial" field is present in the drop and query entry
+    types. It's already in decimal; we simply prefix it with a hash.
+
+    Parameters
+    ----------
+
+    words : list
+        The ``words`` list (a list of fields) from
+        :func:`handle_dnscache_log`.
+
+    i : int
+        The index of the serial field within ``words``
+
+    Returns
+    -------
 
-def decode_type(words, i):
+    Nothing; the ``i``th entry in the ``words`` list is modified
+    in-place.
+
+    Examples
+    --------
+
+        >>> words = ["1", "7f000001:a3db:4fb9", "1", "www.example.com."]
+        >>> decode_serial(words, 0)
+        >>> words
+        ['#1', '7f000001:a3db:4fb9', '1', 'www.example.com.']
+
+    """
+    words[i] = f"#{words[i]}"
+
+def decode_type(words : list, i : int):
     qt = words[i]
     words[i] = query_type.get(int(qt), qt)
 
-def handle_dnscache_log(line) -> typing.Optional[str]:
-    """
+def handle_dnscache_log(line : str) -> typing.Optional[str]:
+    r"""
     Handle a single log line if it matches the ``dnscache_log_re`` regex.
 
     Parameters
@@ -343,7 +409,7 @@ def handle_dnscache_log(line) -> typing.Optional[str]:
 
 
 def handle_tinydns_log(line : str) -> typing.Optional[str]:
-    """
+    r"""
     Handle a single log line if it matches the ``tinydns_log_re`` regex.
 
     Parameters