common(feat): Add deprecation warning for tmux < 3.2a

Author: tony

src/libtmux/common.py

@@ -29,11 +29,44 @@
 #: Most recent version of tmux supported
 TMUX_MAX_VERSION = "3.5a"
 
+#: 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.",
+            DeprecationWarning,
+            stacklevel=4,
+        )
+
 
 class EnvironmentMixin:
     """Mixin for manager session and server level environment variables in tmux."""
@@ -303,7 +336,9 @@ def get_version() -> LooseVersion:
 
     version = re.sub(r"[a-z-]", "", version)
 
-    return LooseVersion(version)
+    version_obj = LooseVersion(version)
+    _check_deprecated_version(version_obj)
+    return version_obj
 
 
 def has_version(version: str) -> bool: