chore: autouse state reset + backward-compat shim coverage (#189)

- Added autouse test-state reset fixture for deprecated wrapper warning counters
- Added coverage for backward-compatible audit shims and public deprecated aliases
- Added one-time misconfiguration warning coverage
- Added `args_extra` ARGS_REMAP call-plan coverage
- Added `num_warns=1` budget-exhaustion regression coverage
- Added sync `@deprecated` caller-frame stacklevel coverage
- Completed `DeprecationStatus` lifecycle unit coverage
- Removed global pytest warning suppression so unexpected warning leaks are visible
- Fixed proxy warning stacklevel attribution to caller frames
- Fixed `no_warning_call` stacklevel attribution with class-based context manager behavior
- Moved `no_warning_call` deprecation warning to instantiation time
- Added chain-detection coverage for target chains of depth three or more
- Added stacked-source short-circuit coverage in `_build_call_plan`
- Deferred test fixture imports to avoid doctest/site-package import mismatch
- Reworked wrapper-state iteration to avoid proxy side effects and warning-budget exhaustion
- Added direct instantiation coverage for `DeprecatedCallableInfo`
- Added no-warning-call instantiation-without-entering coverage
- Improved Windows-portable filename assertions
- Documented proxy stream stacklevel constraints
- Clarified test-fixture reset limits and `warned_misconfigured` hazards
- Expanded `no_warning_call` docstring with args and runnable example
- Cleaned misleading test docs, lint findings, and reverted non-surviving autofix

---------

Co-authored-by: Claude Code <noreply@anthropic.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Author: 5 people

pyproject.toml

@@ -97,7 +97,6 @@ ini_options.addopts = [
   "--strict-markers",
   "--doctest-modules",
   "--color=yes",
-  "--disable-pytest-warnings",
 ]
 # filterwarnings = ["error::FutureWarning"]
 # Suppress only the specific legacy-sentinel warnings emitted by `TargetMode.from_legacy()`

src/deprecate/proxy.py

@@ -40,6 +40,11 @@
 )
 from deprecate.docstring.inject import _update_docstring_with_deprecation, normalize_docstring_style
 
+#: Stacklevel from inside ``_warn`` to the caller's frame.
+#: Chain: ``caller → __getattr__/__getitem__/__iter__/__call__ → _warn → stream → warnings.warn``.
+#: From ``warnings.warn`` upwards: ``1=_warn``, ``2=accessor`` (e.g. ``__getattr__``), ``3=caller``.
+_DEFAULT_STACKLEVEL_TO_CALLER: int = 3
+
 
 class _DeprecatedProxy:
     """Transparent proxy that emits deprecation warnings on attribute and item access.
@@ -60,7 +65,10 @@ class _DeprecatedProxy:
         remove_in: Version string when the object will be removed.
         num_warns: Maximum number of warnings to emit. ``1`` (default) warns once; ``-1`` warns on every access.
         stream: Callable used to emit warnings. Defaults to :data:`~deprecate.deprecation.deprecation_warning`
-            (:class:`FutureWarning`).  Pass ``None`` to suppress warnings.
+            (:class:`FutureWarning`).  Pass ``None`` to suppress warnings.  **Note:** the built-in
+            stacklevel budget assumes *stream* is :func:`warnings.warn` itself or a C-level
+            :func:`functools.partial` of it; a Python-defined wrapper interposes an extra frame and
+            the warning will appear to originate inside :mod:`deprecate.proxy` rather than the caller.
         template_mgs: Optional custom warning message template that overrides the built-in templates.  When ``None``
             (default), the built-in template for the active scenario is used (callable-target, no-target, or
             per-argument).  See :func:`~deprecate.proxy.deprecated_class` for the available ``%``-style placeholders.
@@ -245,7 +253,13 @@ def _warn(self, *, arg_name: Optional[str] = None) -> None:
                 "deprecated_in": dep.deprecated_in,
                 "remove_in": dep.remove_in,
             }
-        stream(msg)
+        # Route the warning to the caller's frame rather than ``proxy.py``.  Mirrors the
+        # ``_raise_warn`` fallback in ``deprecation.py``: when ``stream`` does not accept a
+        # ``stacklevel`` kwarg (e.g. ``print``, custom callables), fall back to a positional call.
+        try:
+            stream(msg, stacklevel=_DEFAULT_STACKLEVEL_TO_CALLER)
+        except TypeError:
+            stream(msg)
         if arg_name is not None:
             cfg.warned_args[arg_name] = cfg.warned_args.get(arg_name, 0) + 1
         else:

src/deprecate/utils.py

@@ -23,6 +23,7 @@
 from collections.abc import Generator
 from contextlib import contextmanager
 from functools import lru_cache
+from types import TracebackType
 from typing import Any, Callable, Optional, Union
 
 
@@ -174,22 +175,56 @@ def assert_no_warnings(warning_type: Optional[type[Warning]] = None, match: Opti
             )
 
 
-@contextmanager
-def no_warning_call(warning_type: Optional[type[Warning]] = None, match: Optional[str] = None) -> Generator:
+class no_warning_call:  # noqa: N801 - kept for backward compatibility with prior snake_case API
     """Deprecated alias for :func:`~deprecate.utils.assert_no_warnings`.
 
     This context manager is kept for backward compatibility so that existing imports like
     ``from deprecate.utils import no_warning_call`` continue to work until v1.0.
 
+    Warning fires at instantiation — the ``no_warning_call(...)`` call line receives the
+    deprecation notice, regardless of how the context manager is subsequently used.
+
+    Args:
+        warning_type: The :class:`Warning` subclass to watch for.  Defaults to :class:`Warning`
+            (all warning categories).
+        match: Optional substring that must appear in the warning message.  When ``None`` (default),
+            any warning of the right category triggers an :class:`AssertionError`.
+
+    Examples:
+        >>> import warnings
+        >>> with warnings.catch_warnings():
+        ...     warnings.simplefilter("ignore", DeprecationWarning)
+        ...     with no_warning_call():
+        ...         pass  # no AssertionError means no warnings were emitted
+
     """
-    warnings.warn(
-        "`deprecate.utils.no_warning_call` is deprecated in `0.6` and will be removed in `1.0`; "
-        "use `deprecate.utils.assert_no_warnings` instead.",
-        DeprecationWarning,
-        stacklevel=2,
-    )
-    with assert_no_warnings(warning_type=warning_type, match=match):
-        yield
+
+    def __init__(self, warning_type: Optional[type[Warning]] = None, match: Optional[str] = None) -> None:
+        """Emit the alias-deprecation warning and capture args for the no-warning assertion."""
+        warnings.warn(
+            "`deprecate.utils.no_warning_call` is deprecated in `0.6` and will be removed in `1.0`; "
+            "use `deprecate.utils.assert_no_warnings` instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self._warning_type = warning_type
+        self._match = match
+        self._inner: Any = None  # ``assert_no_warnings`` returns a ``_GeneratorContextManager``
+
+    def __enter__(self) -> None:
+        """Enter the underlying ``assert_no_warnings`` context."""
+        self._inner = assert_no_warnings(warning_type=self._warning_type, match=self._match)
+        self._inner.__enter__()
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> Optional[bool]:
+        """Forward exit to the underlying ``assert_no_warnings`` so its AssertionError still surfaces."""
+        assert self._inner is not None  # noqa: S101 — internal invariant: __exit__ only runs after __enter__
+        return self._inner.__exit__(exc_type, exc_val, exc_tb)
 
 
 def void(*args: Any, **kwrgs: Any) -> Any:  # noqa: ANN401

tests/collection_chains.py

@@ -316,3 +316,22 @@ def caller_sum_direct(a: int, b: int = 3) -> int:
 
     """
     return void(a, b)
+
+
+# Three-link chain: ``caller_three_hop_sum`` → ``caller_sum_via_depr_sum`` (deprecated) →
+# ``decorated_sum`` (deprecated) → ``base_sum_kwargs`` (final).  The audit only inspects the
+# immediate target — ``caller_sum_via_depr_sum`` is itself deprecated with a non-stacking
+# (callable) target, so ``caller_three_hop_sum`` reports ``ChainType.TARGET``.  Used to pin that
+# chain detection works at depths greater than 2 (existing fixtures only cover 2-hop chains).
+@deprecated(target=caller_sum_via_depr_sum, deprecated_in="1.6", remove_in="2.6")
+def caller_three_hop_sum(a: int, b: int = 5) -> int:
+    """Three-link deprecation chain for chain-depth coverage.
+
+    Examples:
+        Each hop is deprecated:
+        ``caller_three_hop_sum`` → ``caller_sum_via_depr_sum`` → ``decorated_sum`` →
+        ``base_sum_kwargs`` (final).  Fix: collapse all hops and point directly to
+        ``base_sum_kwargs``.
+
+    """
+    return void(a, b)

tests/conftest.py

@@ -0,0 +1,98 @@
+"""Project-wide pytest configuration.
+
+This module provides an :func:`pytest.fixture` (``autouse=True``) that resets the mutable
+``_WrapperState`` on every module-level deprecated wrapper exported from
+:mod:`tests.collection_deprecate` before each test runs.
+
+Why this matters
+----------------
+
+Module-level :func:`@deprecated <deprecate.deprecation.deprecated>` wrappers in
+``tests/collection_deprecate.py`` are singletons whose warning counters (``warned_calls`` and
+``warned_args``) persist across tests once that module is imported.  When a wrapper is
+configured with ``num_warns=1`` (the default), the first test that exercises it exhausts the
+budget; any subsequent test that asserts "no warning fired" via patterns like
+``no_warning_call`` will silently pass for the wrong reason — the counter is spent, not the
+underlying behaviour.
+
+Two file-scoped ``autouse`` fixtures already cover the **async** and **generator** wrappers
+in ``tests/integration/test_callable_kinds.py`` (see ``_reset_gen_state``, ``_reset_async_state``,
+``_reset_async_gen_state``).  This conftest extends that reset to every other wrapper that
+lives at the module level of :mod:`tests.collection_deprecate`, including plain synchronous
+functions.  ``_DeprecatedProxy`` instances (created by ``deprecated_class``) are **not** covered —
+they store state in ``_cfg.warned`` rather than ``_state``; see the *What this fixture does not
+cover* section below.
+
+Reset semantics
+---------------
+
+Only the *counter-style* state is cleared:
+
+* ``warned_calls`` → ``0``
+* ``warned_args`` → empty :class:`dict`
+
+The following are intentionally preserved:
+
+* ``warned_misconfigured`` is **not** reset — it implements a one-time UserWarning per
+  wrapper lifetime (see ``test_callable_kinds.py`` autouse-fixture docstrings).  Resetting
+  it would falsify that contract.  Tests that assert misconfig warnings **emit** must explicitly
+  reset ``_state.warned_misconfigured = False`` in their own setup — do not rely on fixture
+  ordering.  Symmetrically, tests that assert misconfig warnings are **not** emitted against a
+  shared misconfigured wrapper depend silently on whether a prior test already consumed the
+  one-time slot: ``assert_no_warnings(UserWarning)`` may pass because the counter is spent, not
+  because the wrapper is correctly configured.  Both directions require explicit per-test setup.
+* ``called`` is **not** reset — it counts every invocation (including suppressed ones) and
+  is not used to gate warning emission.
+
+What this fixture does *not* cover
+-----------------------------------
+
+Class-proxy state (``_ProxyConfig.warned``) on ``_DeprecatedProxy`` instances is **separate**
+from ``_state`` and is a real cross-test leak surface for proxies configured with
+``num_warns=1`` (e.g. ``_class_deprecation_enum``, ``_class_deprecation_dataclass``).  Those
+proxies are reset by ``_ClassFormBase._reset_proxy_state`` in
+``tests/integration/test_classes.py``.  New tests that use ``num_warns=1`` proxies from
+``collection_deprecate`` must either inherit ``_ClassFormBase`` or add their own proxy-state
+reset.
+
+"""
+
+from __future__ import annotations
+
+import pytest
+
+
+def _iter_wrapper_states(module: object) -> list[object]:
+    """Return every module-level attribute of *module* that carries a ``_state`` attribute.
+
+    Uses ``vars(module)`` (direct ``__dict__`` lookup) and checks for ``_state`` via the
+    instance ``__dict__`` rather than ``hasattr``, so ``_DeprecatedProxy.__getattr__`` is
+    never triggered.  This avoids emitting spurious ``FutureWarning``s and consuming
+    ``num_warns`` budgets during fixture traversal.
+
+    """
+    found: list[object] = []
+    for obj in vars(module).values():  # type: ignore[arg-type]
+        if "_state" in getattr(obj, "__dict__", {}):
+            found.append(obj)
+    return found
+
+
+@pytest.fixture(autouse=True)
+def _reset_collection_deprecate_state() -> None:
+    """Reset every shared module-level wrapper's warning counters before each test.
+
+    Runs before every test function (autouse).  See module docstring for full motivation.
+    The import is deferred to avoid loading ``tests.collection_deprecate`` at conftest
+    parse time, which conflicts with ``--doctest-modules`` collection when pytest resolves
+    ``src/`` imports from the installed package rather than from ``src/``.
+
+    """
+    import tests.collection_deprecate as _collection_deprecate
+
+    for wrapper in _iter_wrapper_states(_collection_deprecate):
+        state = wrapper._state  # type: ignore[attr-defined]
+        # Reset only the counter-style state.  ``warned_misconfigured`` and ``called``
+        # are intentionally NOT cleared — see module docstring.
+        state.warned_calls = 0
+        state.warned_args.clear()

tests/integration/test_audit.py

@@ -15,7 +15,13 @@
 import tests.collection_chains as chain_module
 import tests.collection_deprecate as proxy_module
 import tests.collection_misconfigured as sample_module
-from deprecate import deprecated, validate_deprecation_expiry
+from deprecate import (
+    DeprecatedCallableInfo,
+    deprecated,
+    find_deprecated_callables,
+    validate_deprecated_callable,
+    validate_deprecation_expiry,
+)
 from deprecate._types import DeprecationConfig
 from deprecate.audit import (
     ChainType,
@@ -443,6 +449,24 @@ def test_detects_chain_with_composed_arg_mappings(self, chain_issues: list) -> N
         assert info.chain_type is ChainType.TARGET
         assert info.deprecated_info.args_mapping == {"predictions": "preds", "labels": "truth"}
 
+    def test_detects_three_hop_target_chain(self, chain_issues: list) -> None:
+        """Chain depth > 2 (A → B → C → final, all deprecated) is detected at the outermost hop.
+
+        The detection logic inspects only the immediate target (it does not recursively walk the
+        chain), so ``caller_three_hop_sum`` reports ``ChainType.TARGET`` because its target
+        ``caller_sum_via_depr_sum`` is itself deprecated.  Each intermediate hop is reported
+        independently when scanned — this test pins the outermost hop only, validating that
+        depth ≥ 3 does not break chain detection on the leading wrapper.
+
+        """
+        by_name = {i.function: i for i in chain_issues}
+        assert "caller_three_hop_sum" in by_name, "Three-hop chain fixture must be discovered by the audit"
+        assert by_name["caller_three_hop_sum"].chain_type is ChainType.TARGET
+        # Every intermediate hop is independently a deprecation chain — the audit reports
+        # all three (outer, middle, and inner-via-decorated_sum already covered) when
+        # scanning the module.
+        assert "caller_sum_via_depr_sum" in by_name, "Middle hop must also be flagged as TARGET chain"
+
     @pytest.mark.parametrize(
         "fn_pattern",
         [
@@ -844,3 +868,79 @@ def test_return_format(self) -> None:
         assert all(isinstance(msg, str) for msg in expired)
         for msg in expired:
             assert "Callable" in msg or "scheduled" in msg
+
+
+class TestBackwardCompatShims:
+    """Coverage for the three v0.6-era public aliases preserved in :mod:`deprecate.audit`.
+
+    The three shims are themselves wrapped with :func:`~deprecate.deprecation.deprecated` /
+    :func:`~deprecate.proxy.deprecated_class` (``deprecated_in="0.6"``, ``remove_in="1.0"``),
+    so calling them must (a) emit a :class:`FutureWarning` (the project default warning
+    category) and (b) forward to the new-name implementation transparently.
+
+    Only the shim's own deprecation warning is asserted.  The underlying audit helpers
+    (:func:`~deprecate.audit.validate_deprecation_wrapper`, :func:`~deprecate.audit.find_deprecation_wrappers`)
+    read ``__deprecated__`` metadata without invoking the deprecated callable, so no additional
+    warning originates from the fixture functions themselves.
+
+    """
+
+    def test_validate_deprecated_callable_emits_warning_and_forwards(self) -> None:
+        """``validate_deprecated_callable`` warns and returns the same result as the new name."""
+        with warnings.catch_warnings(record=True) as recorded:
+            warnings.simplefilter("always")
+            result_old = validate_deprecated_callable(proxy_module.decorated_pow_self)
+
+        # The shim's own deprecation warning must appear in the record; identify it by message.
+        shim_warns = [w for w in recorded if "validate_deprecated_callable" in str(w.message)]
+        assert shim_warns, "Calling the shim must emit a FutureWarning about its own deprecation"
+        assert shim_warns[0].category is FutureWarning
+
+        # Result must equal the underlying new-name implementation called on the same input.
+        result_new = validate_deprecation_wrapper(proxy_module.decorated_pow_self)
+        assert result_old == result_new
+
+    def test_find_deprecated_callables_emits_warning_and_forwards(self) -> None:
+        """``find_deprecated_callables`` warns and returns the same list as ``find_deprecation_wrappers``."""
+        with warnings.catch_warnings(record=True) as recorded:
+            warnings.simplefilter("always")
+            result_old = find_deprecated_callables(proxy_module, recursive=False)
+
+        shim_warns = [w for w in recorded if "find_deprecated_callables" in str(w.message)]
+        assert shim_warns, "Calling the shim must emit a FutureWarning about its own deprecation"
+        assert shim_warns[0].category is FutureWarning
+
+        result_new = find_deprecation_wrappers(proxy_module, recursive=False)
+        assert {r.function for r in result_old} == {r.function for r in result_new}
+
+    def test_deprecated_callable_info_alias_resolves(self) -> None:
+        """``DeprecatedCallableInfo`` is a :func:`deprecated_class` proxy aliasing ``DeprecationWrapperInfo``.
+
+        A real :class:`DeprecationWrapperInfo` instance (obtained from
+        :func:`find_deprecation_wrappers`) must satisfy ``isinstance(_, DeprecatedCallableInfo)`` —
+        the proxy implements ``__instancecheck__`` to delegate to the target class.
+
+        """
+        results = find_deprecation_wrappers(proxy_module, recursive=False)
+        assert results, "Fixture module must contain at least one deprecated wrapper"
+        # Filter to deterministic instance — first item from a non-empty list.
+        info = results[0]
+        assert isinstance(info, DeprecationWrapperInfo)
+        assert isinstance(info, DeprecatedCallableInfo)
+
+    def test_deprecated_callable_info_instantiation_warns(self) -> None:
+        """Calling ``DeprecatedCallableInfo(...)`` directly emits a ``FutureWarning`` about its own deprecation."""
+        # pytest introspection (inspect.hasattr '__wrapped__') may consume num_warns=1 before this
+        # test body runs; reset the proxy's warn counter so the call below always fires the warning.
+        DeprecatedCallableInfo._cfg.warned = 0  # type: ignore[attr-defined]
+        with warnings.catch_warnings(record=True) as recorded:
+            warnings.simplefilter("always")
+            info = DeprecatedCallableInfo(  # type: ignore[call-arg]
+                module="tests",
+                function="f",
+                deprecated_info=DeprecationConfig(deprecated_in="1.0", remove_in="2.0"),
+            )
+        shim_warns = [w for w in recorded if "DeprecatedCallableInfo" in str(w.message)]
+        assert shim_warns, "Calling DeprecatedCallableInfo(...) must emit FutureWarning about its own deprecation"
+        assert shim_warns[0].category is FutureWarning
+        assert isinstance(info, DeprecationWrapperInfo)