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

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

diff --git a/bin/djbdns-logparse.py b/bin/djbdns-logparse.py
index 95bc4e07758763fdab7af3bb1e40a7633bcf42a4..689e33bf221e703b47d26a19342c9406a0997b77 100755 (executable)
--- a/bin/djbdns-logparse.py
+++ b/bin/djbdns-logparse.py
@@ -70,11 +70,15 @@ query_type = {
 
 # tinydns can drop a query for one of three reasons; this dictionary
 # maps the symbol that gets logged in each case to a human-readable
-# reason.
+# reason. We include the "+" case here, indicating that the query was
+# NOT dropped, to avoid a special case later on when we're formatting
+# the human-readable output.
 query_drop_reason = {
+    "+": None,
     "-": "no authority",
     "I": "invalid query",
     "C": "invalid class",
+    "/": "couldn't parse"
 }
 
 
@@ -232,23 +236,26 @@ def handle_tinydns_log(line : str, match: re.Match):
 
     print(timestamp, end=' ')
 
+    reason = query_drop_reason[code]
     if code == "+":
-        print ("sent response to %s:%s (id %s): %s %s"
-               % (ip, port, id, type, name))
-    elif code in ("-", "I", "C"):
-        reason = query_drop_reason[code]
-        print ("dropped query (%s) from %s:%s (id %s): %s %s"
-               % (reason, ip, port, id, type, name))
-    elif code == "/":
-        print ("dropped query (couldn't parse) from %s:%s"
-               % (ip, port))
+        line_tpl = "sent response to {ip}:{port} (id {id}): {type} {name}"
     else:
-        print ("%s from %s:%s (id %s): %s %s"
-               % (code, ip, port, id, type, name))
+        line_tpl = "dropped query ({reason}) from {ip}:{port}"
+        if code != "/":
+            # If the query can actually be parsed, the log line is a
+            # bit more informative than it would have been otherwise.
+            line_tpl += " (id {id}): {type} {name}"
+
+    print(line_tpl.format(reason=reason,
+                          ip=ip,
+                          port=port,
+                          id=id,
+                          type=type,
+                          name=name))
 
 
 def parse_logfile(file : typing.TextIO):
-    """
+    r"""
     Process a single log ``file``.
 
     Parameters
@@ -257,6 +264,20 @@ def parse_logfile(file : typing.TextIO):
     file : typing.TextIO
         An open log file, or stdin.
 
+    Examples
+    --------
+
+        >>> line = "@4000000063227a320c4f3114 7f000001:9d61:be69 - 0001 www.example.com\n"
+        >>> from tempfile import NamedTemporaryFile
+        >>> with NamedTemporaryFile(mode="w", delete=False) as f:
+        ...     _ = f.write(line)
+        >>> f = open(f.name, 'r')
+        >>> parse_logfile(f)
+        2022-09-14 21:04:40.206516500 dropped query (no authority) from 127.0.0.1:40289 (id 48745): a www.example.com
+        >>> f.close()
+        >>> from os import remove
+        >>> remove(f.name)
+
     """
     # Open pipe to tai64nlocal: we will write lines of our input (the
     # raw log file) to it, and read log lines with readable timestamps
@@ -280,6 +301,12 @@ def parse_logfile(file : typing.TextIO):
         print(line)
 
 def main():
+    r"""
+    The entry point to the program.
+
+    This function is responsible only for parsing any command-line
+    arguments, and then calling :func`parse_logfile` on them.
+    """
     # Create an argument parser using the file's docsctring as its
     # description.
     from argparse import ArgumentParser, FileType
@@ -295,6 +322,15 @@ def main():
                         default=[stdin],
                         help="djbdns logfile to process (default: stdin)")
 
+    # Warning: argparse automatically opens its file arguments here,
+    # and they only get closed when the program terminates. There's no
+    # real benefit to closing them one-at-a-time after calling
+    # parse_logfile(), because the "scarce" resource of open file
+    # descriptors gets consumed immediately, before any processing has
+    # happened. In other words, if you're going to run out of file
+    # descriptors, it's going to happen right now.
+    #
+    # So anyway, don't run this on several million logfiles.
     args = parser.parse_args()
     for f in args.logfiles:
         parse_logfile(f)