deprecations(refactor): Replace DeprecationWarning with DeprecatedError (#611)

why: Legacy APIs deprecated in 0.16-0.33 should now raise hard errors instead
of soft warnings to encourage migration to new APIs.
what:
- Add DeprecatedError exception class in exc.py
- Server: kill_server, get_by_id, where, find_where, list_sessions, etc.
- Session: attach_session, kill_session, attached_window/pane, etc.
- Window: split_window, select_window, kill_window, attached_pane, etc.
- Pane: resize_pane, select_pane, split_window, dict access
- Keep 0.50 deprecations (g param, window options) as soft warnings

Author: tony

src/libtmux/exc.py

@@ -19,6 +19,35 @@ class LibTmuxException(Exception):
     """Base Exception for libtmux Errors."""
 
 
+class DeprecatedError(LibTmuxException):
+    """Raised when a deprecated function, method, or parameter is used.
+
+    This exception provides clear guidance on what to use instead.
+
+    Parameters
+    ----------
+    deprecated : str
+        The name of the deprecated API (e.g., "Pane.resize_pane()")
+    replacement : str
+        The recommended replacement API to use instead
+    version : str
+        The version when the API was deprecated (e.g., "0.28.0")
+    """
+
+    def __init__(
+        self,
+        *,
+        deprecated: str,
+        replacement: str,
+        version: str,
+    ) -> None:
+        msg = (
+            f"{deprecated} was deprecated in {version} and has been removed. "
+            f"Use {replacement} instead."
+        )
+        super().__init__(msg)
+
+
 class TmuxSessionExists(LibTmuxException):
     """Session does not exist in the server."""
 

src/libtmux/options.py

@@ -797,8 +797,9 @@ def _show_options_raw(
 
         Parameters
         ----------
-        g : str, optional
-            Pass ``-g`` flag for global variable, default False.
+        g : bool, optional
+            .. deprecated:: 0.50.0
+               Use ``global_`` instead. Raises :exc:`~libtmux.exc.DeprecatedError`.
 
         Examples
         --------
@@ -834,8 +835,9 @@ def _show_options_raw(
                 category=DeprecationWarning,
                 stacklevel=2,
             )
-            flags += ("-g",)
-        elif global_:
+            global_ = g
+
+        if global_:
             flags += ("-g",)
 
         if scope is not None and not isinstance(scope, _DefaultOptionScope):
@@ -864,8 +866,9 @@ def _show_options_dict(
 
         Parameters
         ----------
-        g : str, optional
-            Pass ``-g`` flag for global variable, default False.
+        g : bool, optional
+            .. deprecated:: 0.50.0
+               Use ``global_`` instead. Raises :exc:`~libtmux.exc.DeprecatedError`.
 
         Examples
         --------
@@ -913,8 +916,9 @@ def _show_options(
 
         Parameters
         ----------
-        g : str, optional
-            Pass ``-g`` flag for global variable, default False.
+        g : bool, optional
+            .. deprecated:: 0.50.0
+               Use ``global_`` instead. Raises :exc:`~libtmux.exc.DeprecatedError`.
 
         Examples
         --------
@@ -1013,7 +1017,8 @@ def _show_option_raw(
         ----------
         option : str
         g : bool, optional
-            Pass ``-g`` flag, global. Default False.
+            .. deprecated:: 0.50.0
+               Use ``global_`` instead. Raises :exc:`~libtmux.exc.DeprecatedError`.
 
         Raises
         ------
@@ -1063,8 +1068,9 @@ def _show_option_raw(
                 category=DeprecationWarning,
                 stacklevel=2,
             )
-            flags += ("-g",)
-        elif global_:
+            global_ = g
+
+        if global_:
             flags += ("-g",)
 
         if scope is not None and not isinstance(scope, _DefaultOptionScope):
@@ -1104,7 +1110,8 @@ def _show_option(
         ----------
         option : str
         g : bool, optional
-            Pass ``-g`` flag, global. Default False.
+            .. deprecated:: 0.50.0
+               Use ``global_`` instead. Raises :exc:`~libtmux.exc.DeprecatedError`.
 
         Raises
         ------
@@ -1206,7 +1213,8 @@ def show_option(
         ----------
         option : str
         g : bool, optional
-            Pass ``-g`` flag, global. Default False.
+            .. deprecated:: 0.50.0
+               Use ``global_`` instead. Raises :exc:`~libtmux.exc.DeprecatedError`.
 
         Raises
         ------

src/libtmux/pane.py

@@ -11,7 +11,6 @@
 import logging
 import pathlib
 import typing as t
-import warnings
 
 from libtmux import exc
 from libtmux.common import tmux_cmd
@@ -554,16 +553,11 @@ def select_pane(self) -> Pane:
 
            Deprecated in favor of :meth:`.select()`.
         """
-        warnings.warn(
-            "Pane.select_pane() is deprecated in favor of Pane.select()",
-            category=DeprecationWarning,
-            stacklevel=2,
+        raise exc.DeprecatedError(
+            deprecated="Pane.select_pane()",
+            replacement="Pane.select()",
+            version="0.30.0",
         )
-        assert isinstance(self.pane_id, str)
-        pane = self.window.select_pane(self.pane_id)
-        if pane is None:
-            raise exc.PaneNotFound(pane_id=self.pane_id)
-        return pane
 
     def split(
         self,
@@ -731,7 +725,7 @@ def set_width(self, width: int) -> Pane:
         :class:`Pane`
             Self, for method chaining.
         """
-        self.resize_pane(width=width)
+        self.resize(width=width)
         return self
 
     def set_height(self, height: int) -> Pane:
@@ -747,7 +741,7 @@ def set_height(self, height: int) -> Pane:
         :class:`Pane`
             Self, for method chaining.
         """
-        self.resize_pane(height=height)
+        self.resize(height=height)
         return self
 
     def enter(self) -> Pane:
@@ -915,54 +909,41 @@ def split_window(
 
            Deprecated in favor of :meth:`.split`.
         """
-        warnings.warn(
-            "Pane.split_window() is deprecated in favor of Pane.split()",
-            category=DeprecationWarning,
-            stacklevel=2,
-        )
-        if size is None and percent is not None:
-            size = f"{str(percent).rstrip('%')}%"
-        return self.split(
-            target=target,
-            attach=attach,
-            start_directory=start_directory,
-            direction=PaneDirection.Below if vertical else PaneDirection.Right,
-            shell=shell,
-            size=size,
-            environment=environment,
+        raise exc.DeprecatedError(
+            deprecated="Pane.split_window()",
+            replacement="Pane.split()",
+            version="0.33.0",
         )
 
     def get(self, key: str, default: t.Any | None = None) -> t.Any:
         """Return key-based lookup. Deprecated by attributes.
 
-        .. deprecated:: 0.16
+        .. deprecated:: 0.17
 
            Deprecated by attribute lookup, e.g. ``pane['window_name']`` is now
            accessed via ``pane.window_name``.
 
         """
-        warnings.warn(
-            "Pane.get() is deprecated",
-            category=DeprecationWarning,
-            stacklevel=2,
+        raise exc.DeprecatedError(
+            deprecated="Pane.get()",
+            replacement="direct attribute access (e.g., pane.pane_id)",
+            version="0.17.0",
         )
-        return getattr(self, key, default)
 
     def __getitem__(self, key: str) -> t.Any:
         """Return item lookup by key. Deprecated in favor of attributes.
 
-        .. deprecated:: 0.16
+        .. deprecated:: 0.17
 
            Deprecated in favor of attributes. e.g. ``pane['window_name']`` is now
            accessed via ``pane.window_name``.
 
         """
-        warnings.warn(
-            f"Item lookups, e.g. pane['{key}'] is deprecated",
-            category=DeprecationWarning,
-            stacklevel=2,
+        raise exc.DeprecatedError(
+            deprecated="Pane[key] lookup",
+            replacement="direct attribute access (e.g., pane.pane_id)",
+            version="0.17.0",
         )
-        return getattr(self, key)
 
     def resize_pane(
         self,
@@ -985,17 +966,8 @@ def resize_pane(
 
            Deprecated by :meth:`Pane.resize`.
         """
-        warnings.warn(
-            "Deprecated: Use Pane.resize() instead of Pane.resize_pane()",
-            category=DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.resize(
-            adjustment_direction=adjustment_direction,
-            adjustment=adjustment,
-            height=height,
-            width=width,
-            zoom=zoom,
-            mouse=mouse,
-            trim_below=trim_below,
+        raise exc.DeprecatedError(
+            deprecated="Pane.resize_pane()",
+            replacement="Pane.resize()",
+            version="0.28.0",
         )