bin/djbdns-logparse.py: localize subprocess imports.

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

diff --git a/bin/djbdns-logparse.py b/bin/djbdns-logparse.py
index e9551834836476f41d18d7ae9fd9c4718ff8d5f2..2a7f6cab5bb4a1f4411d8de82c9ac88db46c0be4 100755 (executable)
--- a/bin/djbdns-logparse.py
+++ b/bin/djbdns-logparse.py
@@ -5,7 +5,6 @@ Convert tinydns and dnscache logs to human-readable form
 
 import re, typing
 from struct import pack
-from subprocess import Popen, PIPE
 from time import strftime, gmtime
 
 
@@ -82,11 +81,25 @@ query_drop_reason = {
 }
 
 
-def convert_ip(ip : str):
+def convert_ip(ip : str) -> str:
     """
-    Convert a hex string representing an IP address to conventional
-    human-readable form, ie. dotted-quad decimal for IPv4, and
-    8 colon-separated hex shorts for IPv6.
+    Convert a hex string representing an IP address to
+    human-readable form.
+
+    Parameters
+    ----------
+
+    ip : str
+        The hexadecimal representation of either an IPv4 or an IPv6
+        address.
+
+    Returns
+    -------
+
+    The usual decimal dotted-quad representation is returned for an
+    IPv4 address. IPv6 addresses are returned almost as-is, but with
+    colons inserted in the appropriate places, between every four
+    characters.
 
     Examples
     --------
@@ -95,7 +108,6 @@ def convert_ip(ip : str):
         '127.0.0.1'
         >>> convert_ip("00000000000000000000ffff7f000001")
         '0000:0000:0000:0000:0000:ffff:7f00:0001'
-
     """
     if len(ip) == 8:
         # IPv4, eg. "7f000001" -> "7f 00 00 01" -> "127.0.0.1"
@@ -105,7 +117,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])
@@ -341,9 +392,10 @@ def parse_logfile(file : typing.TextIO):
         >>> 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
-    # from it.
+    # Open a pipe to tai64nlocal. We'll write lines of our input file
+    # (the log file) to it, and read back the same lines but with
+    # friendly timestamps in them.
+    from subprocess import Popen, PIPE
     tai = Popen(["tai64nlocal"], stdin=PIPE, stdout=PIPE, text=True, bufsize=0)
 
     for line in file: