Add MaybeTimeStamper

Fixes #81

CHANGELOG.md

@@ -24,6 +24,8 @@ You can find our backwards-compatibility policy [here](https://github.com/hynek/
 
 - Official support for Python 3.12.
   [#515](https://github.com/hynek/structlog/issues/515)
+- `structlog.processors.MaybeTimeStamper` that only adds a timestamp if there isn't one already.
+  [#81](https://github.com/hynek/structlog/issues/81)
 
 
 ### Fixed

docs/api.rst

@@ -261,6 +261,16 @@ API Reference
       >>> TimeStamper(fmt="%Y", key="year")(None, None, {})  # doctest: +SKIP
       {'year': '2013'}
 
+.. autoclass:: MaybeTimeStamper
+
+   .. doctest::
+
+      >>> from structlog.processors import MaybeTimeStamper
+      >>> MaybeTimeStamper()(None, None, {})  # doctest: +SKIP
+      {'timestamp': 1690036074.494428}
+      >>> MaybeTimeStamper()(None, None, {"timestamp": 42})
+      {'timestamp': 42}
+
 .. autoclass:: CallsiteParameter
    :members:
 

src/structlog/processors.py

@@ -519,6 +519,37 @@ def stamper_fmt(event_dict: EventDict) -> EventDict:
     return stamper_fmt
 
 
+class MaybeTimeStamper:
+    """
+    A timestamper that only adds a timestamp if there is none.
+
+    This allows you to overwrite the ``timestamp`` key in the event dict for
+    example when the event is coming from another system.
+
+    It takes the same arguments as `TimeStamper`.
+
+    .. versionadded:: 23.2.0
+    """
+
+    __slots__ = ("stamper",)
+
+    def __init__(
+        self,
+        fmt: str | None = None,
+        utc: bool = True,
+        key: str = "timestamp",
+    ):
+        self.stamper = TimeStamper(fmt=fmt, utc=utc, key=key)
+
+    def __call__(
+        self, logger: WrappedLogger, name: str, event_dict: EventDict
+    ) -> EventDict:
+        if "timestamp" not in event_dict:
+            return self.stamper(logger, name, event_dict)
+
+        return event_dict
+
+
 def _figure_out_exc_info(v: Any) -> ExcInfo:
     """
     Depending on the Python version will try to do the smartest thing possible

tests/test_processors.py

@@ -35,6 +35,7 @@
     JSONRenderer,
     KeyValueRenderer,
     LogfmtRenderer,
+    MaybeTimeStamper,
     StackInfoRenderer,
     TimeStamper,
     UnicodeDecoder,
@@ -452,6 +453,24 @@ def test_apply_freezegun_after_instantiation(self):
             assert "1980-03-25T17:00:00" == d["timestamp"]
 
 
+class TestMaybeTimeStamper:
+    def test_overwrite(self):
+        """
+        If there is a timestamp, leave it.
+        """
+        mts = MaybeTimeStamper()
+
+        assert {"timestamp": 42} == mts(None, None, {"timestamp": 42})
+
+    def test_none(self):
+        """
+        If there is no timestamp, add one.
+        """
+        mts = MaybeTimeStamper()
+
+        assert "timestamp" in mts(None, None, {})
+
+
 class TestFormatExcInfo:
     def test_custom_formatter(self):
         """