Document parameters

README.md

@@ -11,7 +11,19 @@ TimedSwitchingFileHandler
 -------------------------
 
 This file handler starts a new file at regular intervals, comparable to
-the TimedRotatingFileHandler.
+the TimedRotatingFileHandler. The switch always occurs at a “round”
+time, i.e. at the hour for hourly switches, at midnight for daily
+switches, etc. The old file stays open until just before the first log
+entry is written to the new file.
+
+### Parameters
+
+| Parameter | Default | Description |
+|-|-|-|
+| `filename` | (required) | Path to the log files. The timestamp and `.log` is appended |
+| `when` | `'h'` | When log files are switched: (every **s**econd, **m**inute, **h**our, **d**ay, **w**eek) |
+| `utc` | `False` | Timestamps are in UTC (otherwise local time) |
+| `create_directory` | `False` | Intermediate directories in `filename` are created if necessary |
 
 TimeoutSwitchingFileHandler
 ---------------------------
@@ -25,3 +37,12 @@ activity alternate with periods of inactivity. Log switchse will
 typically occur during inactivity, so each log file will include one
 complete active period. Also, since the log files are closed, they can
 be safely compressed or removed.
+
+### Parameters
+
+| Parameter | Default | Description |
+|-|-|-|
+| `filename` | (required) | Path to the log files. The timestamp is appended |
+| `min_timeout` | `60` | Logfile is closed if there hasn't been any activity for `min_timeout` seconds |
+| `max_timeout` | `3600` | Logfile is closed if is has been created `max_timeout` seconds ago |
+| `create_directory` | `False` | Intermediate directories in `filename` are created if necessary |

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "switchinglogfilehandlers"
-version = "0.0.3"
+version = "0.0.4"
 authors = [
   { name="Peter J. Holzer", email="hjp@hjp.at" },
 ]

src/switchinglogfilehandlers/__init__.py

@@ -1,13 +1,16 @@
 import logging
+import os
+import os.path
 import threading
 import time
 
 class TimeoutSwitchingFileHandler(logging.Handler):
-    def __init__(self, filename, min_timeout=60, max_timeout=3600):
+    def __init__(self, filename, min_timeout=60, max_timeout=3600, create_directory=False):
         super().__init__()
         self.basename = filename
         self.min_timeout = min_timeout
         self.max_timeout = max_timeout
+        self.create_directory = create_directory
         self.fh = None
         self.last_emit = 0
         self.first_emit = 0
@@ -21,6 +24,9 @@ class TimeoutSwitchingFileHandler(logging.Handler):
         if not self.fh:
             now_tm = time.localtime(now)
             filename = self.basename + time.strftime("%Y-%m-%d-%H-%M-%S", now_tm) + "-%06d" % (now % 1 * 1000000) + ".log"
+            if self.create_directory:
+                dirname = os.path.dirname(filename)
+                os.makedirs(dirname, exist_ok=True)
             self.fh = open(filename, "a")
             self.first_emit = now
         self.fh.write(msg)
@@ -42,7 +48,7 @@ class TimeoutSwitchingFileHandler(logging.Handler):
             self.release()
 
 class TimedSwitchingFileHandler(logging.Handler):
-    def __init__(self, filename, when='h', utc=False):
+    def __init__(self, filename, when='h', utc=False, create_directory=False):
         super().__init__()
         self.basename = filename
         when = when.lower()
@@ -59,6 +65,7 @@ class TimedSwitchingFileHandler(logging.Handler):
         else:
             raise ValueError(f"Unknown value “{when}” for when")
         self.utc = utc
+        self.create_directory = create_directory
         self.current_filename = None
         self.fh = None
 
@@ -73,6 +80,9 @@ class TimedSwitchingFileHandler(logging.Handler):
         if new_filename != self.current_filename:
             if self.fh:
                 self.fh.close()
+            if self.create_directory:
+                new_dirname = os.path.dirname(new_filename)
+                os.makedirs(new_dirname, exist_ok=True)
             self.fh = open(new_filename, "a")
             self.current_filename = new_filename
         self.fh.write(msg)