From 9f99ba7684a9bc404ccaa403e717d8667a46b855 Mon Sep 17 00:00:00 2001
From: Michael Orlitzky <michael@orlitzky.com>
Date: Thu, 15 Sep 2022 19:02:22 -0400
Subject: [PATCH] bin/djbdns-logparse.py: add docstring for
 handle_dnscache_log().

---
 bin/djbdns-logparse.py | 48 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/bin/djbdns-logparse.py b/bin/djbdns-logparse.py
index d97a812..97182b6 100755
--- a/bin/djbdns-logparse.py
+++ b/bin/djbdns-logparse.py
@@ -129,6 +129,54 @@ def decode_type(words, i):
     words[i] = query_type.get(int(qt), qt)
 
 def handle_dnscache_log(line) -> bool:
+    """
+    Handle a single log line if it matches the ``dnscache_log_re`` regex.
+
+    Parameters
+    ----------
+
+    line : string
+        The log line that might match ``dnscache_log_re``.
+
+    Returns
+    -------
+
+    ``True`` if the log line was handled (that is, if it was really a
+    dnscache log line), and ``False`` otherwise.
+
+    Examples
+    --------
+
+        >>> line = "2022-09-15 18:37:33.863805500 query 1 7f000001:a3db:4fb9 1 www.example.com."
+        >>> handle_dnscache_log(line)
+        2022-09-15 18:37:33.863805500 query #1 127.0.0.1:41947 (id 20409) a www.example.com.
+        True
+
+        >>> line = "2022-09-15 18:37:33.863874500 tx 0 1 www.example.com. . c0a80101"
+        >>> handle_dnscache_log(line)
+        2022-09-15 18:37:33.863874500 tx g=0 a www.example.com. . 192.168.1.1
+        True
+
+        >>> line = "2022-09-15 18:37:33.878529500 rr c0a80101 20865 1 www.example.com. 5db8d822"
+        >>> handle_dnscache_log(line)
+        2022-09-15 18:37:33.878529500 rr 192.168.1.1 TTL=20865 a www.example.com. 93.184.216.34
+        True
+
+        >>> line = "2022-09-15 18:37:33.878532500 stats 1 43 1 0"
+        >>> handle_dnscache_log(line)
+        2022-09-15 18:37:33.878532500 stats count=1 motion=43 udp-active=1 tcp-active=0
+        True
+
+        >>> line = "2022-09-15 18:37:33.878602500 sent 1 49"
+        >>> handle_dnscache_log(line)
+        2022-09-15 18:37:33.878602500 sent #1 49
+        True
+
+        >>> line = "this line is nonsense"
+        >>> handle_dnscache_log(line)
+        False
+
+    """
     match = dnscache_log_re.match(line)
     if not match:
         return False
-- 
2.43.2