fix(warnings): Use DeprecationWarning for APIs being deprecated

CHANGES

@@ -14,6 +14,14 @@ $ pip install --user --upgrade --pre libtmux
 
 <!-- Maintainers and contributors: Insert change notes for the next release above -->
 
+#### Bug fixes
+
+- Use {exc}`DeprecationWarning` for APIs set to be deprecated (#526)
+
+#### Testing
+
+- pytest: Ignore {exc}`DeprecationWarning` by default (#526)
+
 ## libtmux 0.28.1 (2024-02-15)
 
 _Maintenance only, no bug fixes or new features_

pyproject.toml

@@ -163,6 +163,8 @@ testpaths = [
 ]
 filterwarnings = [
   "ignore:The frontend.Option(Parser)? class.*:DeprecationWarning::",
+  "ignore::DeprecationWarning:libtmux.*:",
+  "ignore::DeprecationWarning:tests:",  # tests/
 ]
 
 [build-system]

src/libtmux/pane.py

@@ -521,7 +521,9 @@ def get(self, key: str, default: t.Optional[t.Any] = None) -> t.Any:
            accessed via ``pane.window_name``.
 
         """
-        warnings.warn("Pane.get() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Pane.get() is deprecated", category=DeprecationWarning, stacklevel=2
+        )
         return getattr(self, key, default)
 
     def __getitem__(self, key: str) -> t.Any:
@@ -533,7 +535,11 @@ def __getitem__(self, key: str) -> t.Any:
            accessed via ``pane.window_name``.
 
         """
-        warnings.warn(f"Item lookups, e.g. pane['{key}'] is deprecated", stacklevel=2)
+        warnings.warn(
+            f"Item lookups, e.g. pane['{key}'] is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         return getattr(self, key)
 
     def resize_pane(
@@ -559,6 +565,7 @@ def resize_pane(
         """
         warnings.warn(
             "Deprecated: Use Pane.resize() instead of Pane.resize_pane()",
+            category=DeprecationWarning,
             stacklevel=2,
         )
         return self.resize(

src/libtmux/server.py

@@ -588,7 +588,11 @@ def _list_panes(self) -> t.List[PaneDict]:
            Deprecated in favor of :attr:`.panes`.
 
         """
-        warnings.warn("Server._list_panes() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Server._list_panes() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         return [p.__dict__ for p in self.panes]
 
     def _update_panes(self) -> "Server":
@@ -602,7 +606,11 @@ def _update_panes(self) -> "Server":
         -------
         :class:`Server`
         """
-        warnings.warn("Server._update_panes() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Server._update_panes() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         self._list_panes()
         return self
 
@@ -614,7 +622,11 @@ def get_by_id(self, session_id: str) -> t.Optional[Session]:
            Deprecated by :meth:`.sessions.get()`.
 
         """
-        warnings.warn("Server.get_by_id() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Server.get_by_id() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         return self.sessions.get(session_id=session_id, default=None)
 
     def where(self, kwargs: t.Dict[str, t.Any]) -> t.List[Session]:
@@ -625,7 +637,11 @@ def where(self, kwargs: t.Dict[str, t.Any]) -> t.List[Session]:
            Deprecated by :meth:`.session.filter()`.
 
         """
-        warnings.warn("Server.find_where() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Server.find_where() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         try:
             return self.sessions.filter(**kwargs)
         except IndexError:
@@ -639,7 +655,11 @@ def find_where(self, kwargs: t.Dict[str, t.Any]) -> t.Optional[Session]:
            Slated to be removed in favor of :meth:`.sessions.get()`.
 
         """
-        warnings.warn("Server.find_where() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Server.find_where() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         return self.sessions.get(default=None, **kwargs)
 
     def _list_windows(self) -> t.List[WindowDict]:
@@ -655,7 +675,11 @@ def _list_windows(self) -> t.List[WindowDict]:
            Slated to be removed in favor of :attr:`.windows`.
 
         """
-        warnings.warn("Server._list_windows() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Server._list_windows() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         return [w.__dict__ for w in self.windows]
 
     def _update_windows(self) -> "Server":
@@ -666,7 +690,11 @@ def _update_windows(self) -> "Server":
            Deprecated in favor of :attr:`.windows` and returning ``self``.
 
         """
-        warnings.warn("Server._update_windows() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Server._update_windows() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         self._list_windows()
         return self
 
@@ -679,7 +707,9 @@ def _sessions(self) -> t.List[SessionDict]:
            Slated to be removed in favor of :attr:`.sessions`.
 
         """
-        warnings.warn("Server._sessions is deprecated", stacklevel=2)
+        warnings.warn(
+            "Server._sessions is deprecated", category=DeprecationWarning, stacklevel=2
+        )
         return self._list_sessions()
 
     def _list_sessions(self) -> t.List["SessionDict"]:
@@ -689,7 +719,11 @@ def _list_sessions(self) -> t.List["SessionDict"]:
 
            Slated to be removed in favor of :attr:`.sessions`.
         """
-        warnings.warn("Server._list_sessions() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Server._list_sessions() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         return [s.__dict__ for s in self.sessions]
 
     def list_sessions(self) -> t.List[Session]:
@@ -703,7 +737,11 @@ def list_sessions(self) -> t.List[Session]:
         -------
         list of :class:`Session`
         """
-        warnings.warn("Server.list_sessions is deprecated", stacklevel=2)
+        warnings.warn(
+            "Server.list_sessions is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         return self.sessions
 
     @property
@@ -715,5 +753,7 @@ def children(self) -> QueryList["Session"]:
            Slated to be removed in favor of :attr:`.sessions`.
 
         """
-        warnings.warn("Server.children is deprecated", stacklevel=2)
+        warnings.warn(
+            "Server.children is deprecated", category=DeprecationWarning, stacklevel=2
+        )
         return self.sessions

src/libtmux/session.py

@@ -604,7 +604,9 @@ def get(self, key: str, default: t.Optional[t.Any] = None) -> t.Any:
            accessed via ``session.session_name``.
 
         """
-        warnings.warn("Session.get() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Session.get() is deprecated", category=DeprecationWarning, stacklevel=2
+        )
         return getattr(self, key, default)
 
     def __getitem__(self, key: str) -> t.Any:
@@ -618,6 +620,7 @@ def __getitem__(self, key: str) -> t.Any:
         """
         warnings.warn(
             f"Item lookups, e.g. session['{key}'] is deprecated",
+            category=DeprecationWarning,
             stacklevel=2,
         )
         return getattr(self, key)
@@ -630,7 +633,11 @@ def get_by_id(self, session_id: str) -> t.Optional[Window]:
            Deprecated by :meth:`.windows.get()`.
 
         """
-        warnings.warn("Session.get_by_id() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Session.get_by_id() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         return self.windows.get(window_id=session_id, default=None)
 
     def where(self, kwargs: t.Dict[str, t.Any]) -> t.List[Window]:
@@ -641,7 +648,9 @@ def where(self, kwargs: t.Dict[str, t.Any]) -> t.List[Window]:
            Deprecated by :meth:`.windows.filter()`.
 
         """
-        warnings.warn("Session.where() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Session.where() is deprecated", category=DeprecationWarning, stacklevel=2
+        )
         try:
             return self.windows.filter(**kwargs)
         except IndexError:
@@ -655,7 +664,11 @@ def find_where(self, kwargs: t.Dict[str, t.Any]) -> t.Optional[Window]:
            Slated to be removed in favor of :meth:`.windows.get()`.
 
         """
-        warnings.warn("Session.find_where() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Session.find_where() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         return self.windows.get(default=None, **kwargs)
 
     def _list_windows(self) -> t.List["WindowDict"]:
@@ -666,7 +679,11 @@ def _list_windows(self) -> t.List["WindowDict"]:
            Slated to be removed in favor of :attr:`.windows`.
 
         """
-        warnings.warn("Session._list_windows() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Session._list_windows() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         return [w.__dict__ for w in self.windows]
 
     @property
@@ -678,7 +695,9 @@ def _windows(self) -> t.List["WindowDict"]:
            Slated to be removed in favor of :attr:`.windows`.
 
         """
-        warnings.warn("Session._windows is deprecated", stacklevel=2)
+        warnings.warn(
+            "Session._windows is deprecated", category=DeprecationWarning, stacklevel=2
+        )
         return self._list_windows()
 
     def list_windows(self) -> t.List["Window"]:
@@ -689,7 +708,11 @@ def list_windows(self) -> t.List["Window"]:
            Slated to be removed in favor of :attr:`.windows`.
 
         """
-        warnings.warn("Session.list_windows() is deprecated", stacklevel=2)
+        warnings.warn(
+            "Session.list_windows() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         return self.windows
 
     @property
@@ -701,5 +724,7 @@ def children(self) -> QueryList["Window"]:
            Slated to be removed in favor of :attr:`.windows`.
 
         """
-        warnings.warn("Session.children is deprecated", stacklevel=2)
+        warnings.warn(
+            "Session.children is deprecated", category=DeprecationWarning, stacklevel=2
+        )
         return self.windows