review: warn at config construction, per branch, and on the contradiction

Author: lesnik512

docs/integrations/fastmcp.md

@@ -62,9 +62,9 @@ FastMcpConfig(
 Enabled, each message is logged with its `method`, `source` and `type`, plus `duration` in
 nanoseconds. A message that raises is logged at exception level and the exception is re-raised.
 
-`logging_turn_off_middleware` still works and keeps the behaviour its setter asked for, but it is
-superseded and warns: `logging_turn_off_middleware=False` turns the middleware on, `True` leaves it
-off.
+`logging_turn_off_middleware` still works but is superseded and warns:
+`logging_turn_off_middleware=False` turns the middleware on, `True` leaves it off. If you set both
+fields, `fastmcp_logging_middleware_enabled` wins and the superseded one is reported as ignored.
 
 Set `health_checks_enabled=False` to omit the health route.
 

docs/introduction/configuration.md

@@ -261,7 +261,7 @@ The per-MCP-message access log is **off by default**:
 
 - `fastmcp_logging_middleware_enabled` - turn on the access log (default: `False`).
 - `logging_turn_off_middleware` - superseded by the field above and warns when set. `False` turns the
-  middleware on, `True` leaves it off.
+  middleware on, `True` leaves it off, and if both are set the field above wins.
 
 See [the FastMCP integration guide](../integrations/fastmcp.md#logging) for what gets logged.
 

lite_bootstrap/bootstrappers/fastmcp_bootstrapper.py

@@ -85,6 +85,30 @@ class FastMcpConfig(HealthChecksConfig, LoggingConfig, PrometheusConfig, Pyrosco
     fastmcp_logging_middleware_enabled: bool = False
     logging_turn_off_middleware: bool | None = None
 
+    def __post_init__(self) -> None:
+        # Not super(): the missing-dependency tests reload this module, which rebinds the global
+        # name, so `super(FastMcpConfig, self)` would not match the instance's own class.
+        HealthChecksConfig.__post_init__(self)
+        if self.logging_turn_off_middleware is None:
+            return
+        if self.fastmcp_logging_middleware_enabled:
+            warn_at_caller(
+                "logging_turn_off_middleware is ignored because fastmcp_logging_middleware_enabled "
+                "is set; drop logging_turn_off_middleware."
+            )
+            return
+        if self.logging_turn_off_middleware:
+            warn_at_caller(
+                "logging_turn_off_middleware is superseded by fastmcp_logging_middleware_enabled, "
+                "which is False by default; drop logging_turn_off_middleware."
+            )
+            return
+        warn_at_caller(
+            "logging_turn_off_middleware is superseded by fastmcp_logging_middleware_enabled; "
+            "set fastmcp_logging_middleware_enabled=True instead."
+        )
+        object.__setattr__(self, "fastmcp_logging_middleware_enabled", True)
+
 
 @dataclasses.dataclass(kw_only=True)
 class FastMcpHealthChecksInstrument(HealthChecksInstrument):
@@ -134,20 +158,10 @@ class FastMcpLoggingInstrument(LoggingInstrument):
 
     def bootstrap(self) -> None:
         super().bootstrap()
-        if not self._middleware_enabled():
+        if not self.bootstrap_config.fastmcp_logging_middleware_enabled:
             return
         self.bootstrap_config.application.add_middleware(FastMcpLoggingMiddleware())
 
-    def _middleware_enabled(self) -> bool:
-        config = self.bootstrap_config
-        if config.logging_turn_off_middleware is None:
-            return config.fastmcp_logging_middleware_enabled
-        warn_at_caller(
-            "logging_turn_off_middleware is superseded by fastmcp_logging_middleware_enabled, "
-            "which is False by default; set fastmcp_logging_middleware_enabled=True to log messages."
-        )
-        return not config.logging_turn_off_middleware
-
 
 class FastMcpBootstrapper(BaseBootstrapper["FastMCP[typing.Any]"]):
     __slots__ = "bootstrap_config", "instruments"

tests/test_fastmcp_bootstrap.py

@@ -249,14 +249,14 @@ def test_fastmcp_logging_middleware_is_mounted_when_enabled() -> None:
     ids=["turn_off_false_still_mounts", "turn_off_true_does_not_mount"],
 )
 def test_fastmcp_logging_turn_off_middleware_still_works(turn_off: bool, expected_count: int) -> None:
-    """The superseded flag keeps the behaviour its setter asked for, and says it is superseded."""
-    config = _make_test_config(logging_turn_off_middleware=turn_off)
+    """The superseded flag keeps the behaviour it was set for, and says that it is superseded."""
     with warnings.catch_warnings(record=True) as caught:
         warnings.simplefilter("always")
-        mounted = _mounted_logging_middleware(config)
+        config = _make_test_config(logging_turn_off_middleware=turn_off)
 
     assert [str(one.message) for one in caught if "logging_turn_off_middleware" in str(one.message)]
-    assert len(mounted) == expected_count
+    assert config.fastmcp_logging_middleware_enabled is (not turn_off)
+    assert len(_mounted_logging_middleware(config)) == expected_count
 
 
 def test_fastmcp_logging_turn_off_middleware_warning_names_the_caller() -> None:
@@ -265,14 +265,33 @@ def test_fastmcp_logging_turn_off_middleware_warning_names_the_caller() -> None:
     Same reason as the config-validation warnings in test_config_cascade.py: every frame between
     the warn call and the user is lite-bootstrap's, and the distance is not a constant.
     """
-    config = _make_test_config(logging_turn_off_middleware=True)
     with warnings.catch_warnings(record=True) as caught:
         warnings.simplefilter("always")
-        _mounted_logging_middleware(config)
+        _make_test_config(logging_turn_off_middleware=True)
 
     assert warning_source_files(caught, UserWarning) == [__file__]
 
 
+@pytest.mark.parametrize("overrides", [{}, {"fastmcp_logging_middleware_enabled": True}], ids=["default", "enabled"])
+def test_fastmcp_logging_warns_nothing_without_the_superseded_flag(overrides: dict[str, bool]) -> None:
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        _make_test_config(**overrides)
+
+    assert [str(one.message) for one in caught] == []
+
+
+def test_fastmcp_logging_explicit_flag_wins_over_the_superseded_one() -> None:
+    """Setting both keeps the current field and says the superseded one is ignored."""
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        config = _make_test_config(fastmcp_logging_middleware_enabled=True, logging_turn_off_middleware=True)
+
+    assert [one for one in caught if "is ignored because" in str(one.message)]
+    assert config.fastmcp_logging_middleware_enabled is True
+    assert len(_mounted_logging_middleware(config)) == 1
+
+
 @pytest.mark.parametrize(
     ("package_name", "extra_config"),
     [