common.py(refactor): Bump TMUX_MIN_VERSION to 3.2a

why: tmux versions below 3.2a are no longer supported as of libtmux 0.49.0
what:
- Change TMUX_MIN_VERSION from "1.8" to "3.2a"
- Remove TMUX_SOFT_MIN_VERSION constant (no longer needed)
- Remove _version_deprecation_checked flag
- Remove _check_deprecated_version() function
- Remove deprecation warning call from get_version()
- Update has_minimum_version() docstring to reflect 3.2a requirement
- Update error message to mention v0.48.x backport

Author: tony

src/libtmux/common.py

@@ -24,49 +24,16 @@
 
 
 #: Minimum version of tmux required to run libtmux
-TMUX_MIN_VERSION = "1.8"
+TMUX_MIN_VERSION = "3.2a"
 
 #: Most recent version of tmux supported
 TMUX_MAX_VERSION = "3.6"
 
-#: Minimum version before deprecation warning is shown
-TMUX_SOFT_MIN_VERSION = "3.2a"
-
 SessionDict = dict[str, t.Any]
 WindowDict = dict[str, t.Any]
 WindowOptionDict = dict[str, t.Any]
 PaneDict = dict[str, t.Any]
 
-#: Flag to ensure deprecation warning is only shown once per process
-_version_deprecation_checked: bool = False
-
-
-def _check_deprecated_version(version: LooseVersion) -> None:
-    """Check if tmux version is deprecated and warn once.
-
-    This is called from get_version() on first invocation.
-    """
-    global _version_deprecation_checked
-    if _version_deprecation_checked:
-        return
-    _version_deprecation_checked = True
-
-    import os
-    import warnings
-
-    if os.environ.get("LIBTMUX_SUPPRESS_VERSION_WARNING"):
-        return
-
-    if version < LooseVersion(TMUX_SOFT_MIN_VERSION):
-        warnings.warn(
-            f"tmux {version} is deprecated and will be unsupported in a future "
-            f"libtmux release. Please upgrade to tmux {TMUX_SOFT_MIN_VERSION} "
-            "or newer. Set LIBTMUX_SUPPRESS_VERSION_WARNING=1 to suppress this "
-            "warning.",
-            FutureWarning,
-            stacklevel=4,
-        )
-
 
 class EnvironmentMixin:
     """Mixin for manager session and server level environment variables in tmux."""
@@ -336,9 +303,7 @@ def get_version() -> LooseVersion:
 
     version = re.sub(r"[a-z-]", "", version)
 
-    version_obj = LooseVersion(version)
-    _check_deprecated_version(version_obj)
-    return version_obj
+    return LooseVersion(version)
 
 
 def has_version(version: str) -> bool:
@@ -422,7 +387,7 @@ def has_lt_version(max_version: str) -> bool:
 
 
 def has_minimum_version(raises: bool = True) -> bool:
-    """Return True if tmux meets version requirement. Version >1.8 or above.
+    """Return True if tmux meets version requirement. Version >= 3.2a.
 
     Parameters
     ----------
@@ -441,6 +406,9 @@ def has_minimum_version(raises: bool = True) -> bool:
 
     Notes
     -----
+    .. versionchanged:: 0.49.0
+        Minimum version bumped to 3.2a. For older tmux, use libtmux v0.48.x.
+
     .. versionchanged:: 0.7.0
         No longer returns version, returns True or False
 
@@ -454,7 +422,7 @@ def has_minimum_version(raises: bool = True) -> bool:
             msg = (
                 f"libtmux only supports tmux {TMUX_MIN_VERSION} and greater. This "
                 f"system has {get_version()} installed. Upgrade your tmux to use "
-                "libtmux."
+                "libtmux, or use libtmux v0.48.x for older tmux versions."
             )
             raise exc.VersionTooLow(msg)
         return False

tests/test_common.py

@@ -508,134 +508,3 @@ def mock_get_version() -> LooseVersion:
     elif check_type == "type_check":
         assert mock_version is not None  # For type checker
         assert isinstance(has_version(mock_version), bool)
-
-
-class VersionDeprecationFixture(t.NamedTuple):
-    """Test fixture for version deprecation warning."""
-
-    test_id: str
-    version: str
-    suppress_env: bool
-    expected_warning: bool
-
-
-VERSION_DEPRECATION_FIXTURES: list[VersionDeprecationFixture] = [
-    VersionDeprecationFixture(
-        test_id="deprecated_version_warns",
-        version="3.1",
-        suppress_env=False,
-        expected_warning=True,
-    ),
-    VersionDeprecationFixture(
-        test_id="old_deprecated_version_warns",
-        version="2.9",
-        suppress_env=False,
-        expected_warning=True,
-    ),
-    VersionDeprecationFixture(
-        test_id="current_version_no_warning",
-        version="3.2a",
-        suppress_env=False,
-        expected_warning=False,
-    ),
-    VersionDeprecationFixture(
-        test_id="newer_version_no_warning",
-        version="3.5",
-        suppress_env=False,
-        expected_warning=False,
-    ),
-    VersionDeprecationFixture(
-        test_id="env_var_suppresses_warning",
-        version="3.0",
-        suppress_env=True,
-        expected_warning=False,
-    ),
-]
-
-
-@pytest.mark.parametrize(
-    list(VersionDeprecationFixture._fields),
-    VERSION_DEPRECATION_FIXTURES,
-    ids=[test.test_id for test in VERSION_DEPRECATION_FIXTURES],
-)
-def test_version_deprecation_warning(
-    test_id: str,
-    version: str,
-    suppress_env: bool,
-    expected_warning: bool,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    """Test version deprecation warning behavior."""
-    import warnings
-
-    import libtmux.common
-
-    # Reset the warning flag for each test
-    monkeypatch.setattr(libtmux.common, "_version_deprecation_checked", False)
-
-    # Set or clear the suppress env var
-    if suppress_env:
-        monkeypatch.setenv("LIBTMUX_SUPPRESS_VERSION_WARNING", "1")
-    else:
-        monkeypatch.delenv("LIBTMUX_SUPPRESS_VERSION_WARNING", raising=False)
-
-    with warnings.catch_warnings(record=True) as w:
-        warnings.simplefilter("always")
-        libtmux.common._check_deprecated_version(LooseVersion(version))
-
-    if expected_warning:
-        assert len(w) == 1
-        assert issubclass(w[0].category, FutureWarning)
-        assert version in str(w[0].message)
-        assert "3.2a" in str(w[0].message)
-    else:
-        assert len(w) == 0
-
-
-def test_version_deprecation_warns_once(monkeypatch: pytest.MonkeyPatch) -> None:
-    """Test that deprecation warning only fires once per process."""
-    import warnings
-
-    import libtmux.common
-
-    monkeypatch.setattr(libtmux.common, "_version_deprecation_checked", False)
-    monkeypatch.delenv("LIBTMUX_SUPPRESS_VERSION_WARNING", raising=False)
-
-    with warnings.catch_warnings(record=True) as w:
-        warnings.simplefilter("always")
-        libtmux.common._check_deprecated_version(LooseVersion("3.1"))
-        libtmux.common._check_deprecated_version(LooseVersion("3.1"))
-
-    assert len(w) == 1
-
-
-def test_version_deprecation_via_get_version(monkeypatch: pytest.MonkeyPatch) -> None:
-    """Test deprecation warning fires through get_version() call.
-
-    This integration test verifies the warning is emitted when calling
-    get_version() with an old tmux version, testing the full call chain.
-    """
-    import warnings
-
-    import libtmux.common
-
-    class MockTmuxOutput:
-        stdout: t.ClassVar = ["tmux 3.1"]
-        stderr: t.ClassVar[list[str]] = []
-
-    def mock_tmux_cmd(*args: t.Any, **kwargs: t.Any) -> MockTmuxOutput:
-        return MockTmuxOutput()
-
-    monkeypatch.setattr(libtmux.common, "_version_deprecation_checked", False)
-    monkeypatch.setattr(libtmux.common, "tmux_cmd", mock_tmux_cmd)
-    monkeypatch.delenv("LIBTMUX_SUPPRESS_VERSION_WARNING", raising=False)
-
-    with warnings.catch_warnings(record=True) as w:
-        warnings.simplefilter("always")
-        version = libtmux.common.get_version()
-
-    assert str(version) == "3.1"
-    assert len(w) == 1
-    assert issubclass(w[0].category, FutureWarning)
-    assert "3.1" in str(w[0].message)
-    assert "3.2a" in str(w[0].message)