From: Michael Orlitzky <michael@orlitzky.com>
Date: Fri, 16 Sep 2022 00:13:17 +0000 (-0400)
Subject: bin/djbdns-logparse.py: add docstring for decode_client().
X-Git-Tag: 0.0.1~37
X-Git-Url: https://gitweb.michael.orlitzky.com/?a=commitdiff_plain;h=3ae973bcb6088d5cc25996a3888eab77d228dd88;p=djbdns-logparse.git

bin/djbdns-logparse.py: add docstring for decode_client().
---

diff --git a/bin/djbdns-logparse.py b/bin/djbdns-logparse.py
index e955183..31427a6 100755
--- a/bin/djbdns-logparse.py
+++ b/bin/djbdns-logparse.py
@@ -105,7 +105,46 @@ def convert_ip(ip : str):
         return ":".join([ip[(4*i) : (4*i+4)] for i in range(8)])
 
 
-def decode_client(words, i):
+def decode_client(words : list, i : int):
+    r"""
+    Helper function to decode the client field in a dnscache log
+    entry.
+
+    There are two possible formats for the client field,
+
+      1. clientip:clientport, used by tcpopen/tcpclose entries,
+      2. clientip:clientport:id, used by "query" entries.
+
+    Parameters
+    ----------
+
+    words : list
+        The ``words`` list (a list of fields) from
+        :func:`handle_dnscache_log`.
+
+    i : int
+        The index of the client field within ``words``
+
+    Returns
+    -------
+
+    Nothing; the ``i``th entry in the ``words`` list is modified
+    in-place.
+
+    Examples
+    --------
+
+        >>> words = ["foo", "bar", "7f000001:9253", "quux"]
+        >>> decode_client(words, 2)
+        >>> words
+        ['foo', 'bar', '127.0.0.1:37459', 'quux']
+
+        >>> words = ["foo", "7f000001:a3db:4fb9", "bar", "quux"]
+        >>> decode_client(words, 1)
+        >>> words
+        ['foo', '127.0.0.1:41947 (id 20409)', 'bar', 'quux']
+
+    """
     chunks = words[i].split(":")
 
     ip = convert_ip(chunks[0])