deprecate @ez.thread decorator

Author: griffinmilsap

ISSUE_deprecate_ez_thread.md

@@ -0,0 +1,27 @@
+# Deprecate `@ez.thread` Decorator
+
+## Summary
+Deprecate `@ez.thread` in `ezmsg.core` and guide users to explicit background execution patterns (`loop.run_in_executor(...)` / explicit task lifecycle management).
+
+## Motivation
+- `@ez.thread` has no cooperative termination contract and does not integrate cleanly with unit lifecycle shutdown.
+- Equivalent behavior is already available with explicit executor usage.
+- Keeping `@ez.thread` adds an extra concurrency model surface area without strong adoption.
+
+## Proposal
+1. Mark `@ez.thread` as deprecated by emitting `DeprecationWarning` when the decorator is applied.
+2. Update docs to indicate deprecation and migration guidance.
+3. Add tests to ensure the warning is emitted and existing decorator behavior remains intact for compatibility.
+
+## Non-Goals
+- Removing `@ez.thread` in this issue.
+- Changing runtime behavior of existing `@ez.thread`-decorated functions beyond warning emission.
+
+## Acceptance Criteria
+- Calling `ez.thread(...)` emits `DeprecationWarning`.
+- API docs clearly mark `@ez.thread` as deprecated with migration guidance.
+- Test coverage exists for warning behavior and attribute tagging.
+
+## Follow-Up
+- Remove `@ez.thread` in a future major release after deprecation window.
+- Add release note/migration note before removal.

PR_deprecate_ez_thread.md

@@ -0,0 +1,25 @@
+# Deprecate `@ez.thread`
+
+## Summary
+This changeset deprecates the `@ez.thread` decorator and documents the preferred replacement (`loop.run_in_executor(...)` / explicit task lifecycle management).
+
+## Changes
+- Emit `DeprecationWarning` from `ezmsg.core.unit.thread`.
+- Add deprecation note to function decorator docs.
+- Add a unit test verifying warning emission and backward-compatible decorator tagging.
+
+## Files
+- `src/ezmsg/core/unit.py`
+- `docs/source/reference/API/functiondecorators.rst`
+- `tests/test_unit_deprecations.py`
+- `ISSUE_deprecate_ez_thread.md`
+
+## Testing
+- `PYTHONPYCACHEPREFIX=/tmp/pycache .venv/bin/pytest tests/test_unit_deprecations.py -q`
+
+## Backward Compatibility
+- Existing `@ez.thread` usage continues to function in this release.
+- Users now receive a deprecation warning at decorator application time.
+
+## Future Work
+- Remove `@ez.thread` in a future major release after migration window and release-note notice.

docs/source/reference/API/functiondecorators.rst

@@ -11,6 +11,10 @@ These function decorators can be added to member functions of an ezmsg ``Unit``
 
 .. autodecorator:: ezmsg.core.thread
 
+.. note::
+   ``@ez.thread`` is deprecated and will be removed in a future release.
+   Prefer explicit background work via ``loop.run_in_executor(...)``.
+
 .. autodecorator:: ezmsg.core.task
 
 .. autodecorator:: ezmsg.core.process

src/ezmsg/core/unit.py

@@ -274,11 +274,22 @@ def thread(func: Callable):
     Thread functions run concurrently with the main message processing and can be used
     for background tasks, monitoring, or other concurrent operations.
 
+    .. deprecated::
+       ``@thread`` is deprecated and will be removed in a future release.
+       Prefer explicit background work using ``loop.run_in_executor(...)`` or
+       explicit task management in ``initialize()``/``shutdown()``.
+
     :param func: The function to run as a background thread
     :type func: collections.abc.Callable
     :return: The decorated function
     :rtype: collections.abc.Callable
     """
+    warnings.warn(
+        "`@ez.thread` is deprecated and will be removed in a future release. "
+        "Prefer explicit background work via `loop.run_in_executor(...)`.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     setattr(func, THREAD_ATTR, True)
     return func
 

tests/test_unit_deprecations.py

@@ -0,0 +1,18 @@
+import pytest
+
+import ezmsg.core as ez
+from ezmsg.core.unit import THREAD_ATTR
+
+
+def test_thread_decorator_warns_and_sets_attribute():
+    def fn(_):
+        return None
+
+    with pytest.warns(
+        DeprecationWarning,
+        match=r"`@ez\.thread` is deprecated and will be removed in a future release",
+    ):
+        decorated = ez.thread(fn)
+
+    assert decorated is fn
+    assert hasattr(decorated, THREAD_ATTR)