Expose remove_file_from_lock helper for WRITE_LOCKS cleanup

CHANGELOG.md

@@ -15,6 +15,12 @@ You can find our backwards-compatibility policy [here](https://github.com/hynek/
 
 ## [Unreleased](https://github.com/hynek/structlog/compare/25.5.0...HEAD)
 
+### Added
+
+- `structlog.remove_file_from_lock()` to release the write lock that is implicitly registered for a file by `PrintLogger`, `WriteLogger`, and `BytesLogger`.
+  Useful when the underlying file is being closed.
+
+
 ### Removed
 
 - Python 3.8 and 3.9 support.

docs/api.rst

@@ -64,6 +64,8 @@ API Reference
 
 .. autoclass:: BytesLoggerFactory
 
+.. autofunction:: remove_file_from_lock
+
 .. autoexception:: DropEvent
 
 .. autoclass:: BoundLoggerBase

src/structlog/__init__.py

@@ -37,6 +37,7 @@
     PrintLoggerFactory,
     WriteLogger,
     WriteLoggerFactory,
+    remove_file_from_lock,
 )
 from structlog.exceptions import DropEvent
 from structlog.testing import ReturnLogger, ReturnLoggerFactory
@@ -79,6 +80,7 @@
     "is_configured",
     "make_filtering_bound_logger",
     "processors",
+    "remove_file_from_lock",
     "reset_defaults",
     "stdlib",
     "testing",

src/structlog/_output.py

@@ -30,6 +30,19 @@ def _get_lock_for_file(file: IO[Any]) -> threading.Lock:
     return lock
 
 
+def remove_file_from_lock(file: IO[Any]) -> None:
+    """
+    Remove the write lock associated with *file* from the registry.
+
+    Useful when *file* is being closed and you want to release the lock that
+    was implicitly created for it by `PrintLogger`, `WriteLogger`, or
+    `BytesLogger`. A no-op if no lock is registered for *file*.
+
+    .. versionadded:: 26.1.0
+    """
+    WRITE_LOCKS.pop(file, None)
+
+
 class PrintLogger:
     """
     Print events into a file.

tests/test_output.py

@@ -17,6 +17,7 @@
     PrintLoggerFactory,
     WriteLogger,
     WriteLoggerFactory,
+    remove_file_from_lock,
 )
 from structlog._output import WRITE_LOCKS, stderr, stdout
 
@@ -68,6 +69,17 @@ def test_lock(self, logger_cls, sio):
 
         assert sio in WRITE_LOCKS
 
+    def test_remove_file_from_lock(self, logger_cls, sio):
+        """
+        remove_file_from_lock removes the lock entry for the given file.
+        """
+        logger_cls(sio)
+        assert sio in WRITE_LOCKS
+
+        remove_file_from_lock(sio)
+
+        assert sio not in WRITE_LOCKS
+
     @pytest.mark.parametrize("method", stdlib_log_methods)
     def test_stdlib_methods_support(self, logger_cls, method, sio):
         """

tests/typing/api.py

@@ -9,6 +9,7 @@
 
 from __future__ import annotations
 
+import io
 import logging
 import logging.config
 
@@ -412,3 +413,7 @@ def f() -> None:
 
 cr.repr_native_str
 cr.repr_native_str = True
+
+_f = io.StringIO()
+structlog.PrintLogger(_f)
+structlog.remove_file_from_lock(_f)