ruff(docs): Enable pydocstyle w/ numpy convention (#509)

See also:
- https://www.pydocstyle.org/en/stable/
- https://docs.astral.sh/ruff/settings/#pydocstyle

Author: tony

CHANGES

@@ -20,6 +20,14 @@ $ pip install --user --upgrade --pre libtmux
 
   Thank you @m1guelperez for `Window.__eq__`! (#505)
 
+### Development
+
+- ci: Add pydocstyle rule to ruff (#509)
+
+### Documentation
+
+- Add docstrings to functions, methods, classes, and packages (#509)
+
 ## libtmux 0.24.1 (2023-11-23)
 
 ### Packaging

conftest.py

@@ -1,4 +1,4 @@
-"""Conftest.py (root-level)
+"""Conftest.py (root-level).
 
 We keep this in root pytest fixtures in pytest's doctest plugin to be available, as well
 as avoiding conftest.py from being included in the wheel, in addition to pytest_plugin
@@ -27,6 +27,7 @@ def add_doctest_fixtures(
     request: pytest.FixtureRequest,
     doctest_namespace: t.Dict[str, t.Any],
 ) -> None:
+    """Configure doctest fixtures for pytest-doctest."""
     if isinstance(request._pyfuncitem, DoctestItem) and shutil.which("tmux"):
         request.getfixturevalue("set_home")
         doctest_namespace["server"] = request.getfixturevalue("server")
@@ -42,6 +43,7 @@ def set_home(
     monkeypatch: pytest.MonkeyPatch,
     user_path: pathlib.Path,
 ) -> None:
+    """Configure home directory for pytest tests."""
     monkeypatch.setenv("HOME", str(user_path))
 
 
@@ -51,5 +53,6 @@ def setup(
     request: pytest.FixtureRequest,
     config_file: pathlib.Path,
 ) -> None:
+    """Configure test fixtures for pytest."""
     if USING_ZSH:
         request.getfixturevalue("zshrc")

docs/__init__.py

@@ -0,0 +1 @@
+"""Documentation for the libtmux package."""

docs/conf.py

@@ -1,4 +1,5 @@
 # flake8: NOQA: E501
+"""Sphinx configuration for libtmux."""
 import contextlib
 import inspect
 import pathlib
@@ -132,7 +133,7 @@
 
 def linkcode_resolve(domain: str, info: t.Dict[str, str]) -> t.Union[None, str]:
     """
-    Determine the URL corresponding to Python object
+    Determine the URL corresponding to Python object.
 
     Notes
     -----
@@ -202,6 +203,7 @@ def linkcode_resolve(domain: str, info: t.Dict[str, str]) -> t.Union[None, str]:
 
 
 def remove_tabs_js(app: "Sphinx", exc: Exception) -> None:
+    """Remove tabs.js from _static after build."""
     # Fix for sphinx-inline-tabs#18
     if app.builder.format == "html" and not exc:
         tabs_js = pathlib.Path(app.builder.outdir) / "_static" / "tabs.js"
@@ -210,4 +212,5 @@ def remove_tabs_js(app: "Sphinx", exc: Exception) -> None:
 
 
 def setup(app: "Sphinx") -> None:
+    """Configure Sphinx app hooks."""
     app.connect("build-finished", remove_tabs_js)

pyproject.toml

@@ -128,6 +128,7 @@ select = [
   "TRY", # Trycertatops
   "PERF", # Perflint
   "RUF", # Ruff-specific rules
+  "D", # pydocstyle
 ]
 
 [tool.ruff.isort]
@@ -136,6 +137,9 @@ known-first-party = [
 ]
 combine-as-imports = true
 
+[tool.ruff.pydocstyle]
+convention = "numpy"
+
 [tool.ruff.per-file-ignores]
 "*/__init__.py" = ["F401"]
 

src/libtmux/__about__.py

@@ -1,3 +1,4 @@
+"""Metadata package for libtmux."""
 __title__ = "libtmux"
 __package_name__ = "libtmux"
 __version__ = "0.24.1"

src/libtmux/_internal/dataclasses.py

@@ -13,19 +13,20 @@
 
 
 class SkipDefaultFieldsReprMixin:
-    r"""Skip default fields in :func:`~dataclasses.dataclass`
-    :func:`object representation <repr()>`.
+    r"""Skip default fields in :func:`~dataclasses.dataclass` object representation.
+
+    See Also
+    --------
+    :func:`object representation <repr()>`
 
     Notes
     -----
-
     Credit: Pietro Oldrati, 2022-05-08, Unilicense
 
     https://stackoverflow.com/a/72161437/1396928
 
     Examples
     --------
-
     >>> @dataclasses.dataclass()
     ... class Item:
     ...     name: str

src/libtmux/_internal/query_list.py

@@ -19,7 +19,7 @@ def __call__(
             data: t.Union[str, t.List[str], "Mapping[str, str]"],
             rhs: t.Union[str, t.List[str], "Mapping[str, str]", "re.Pattern[str]"],
         ) -> bool:
-            """Callback for :class:`QueryList` filtering operators."""
+            """Return callback for :class:`QueryList` filtering operators."""
             ...
 
 
@@ -29,7 +29,7 @@ def __call__(
 
 
 class MultipleObjectsReturned(Exception):
-    """The requested object does not exist"""
+    """The requested object does not exist."""
 
 
 class ObjectDoesNotExist(Exception):
@@ -40,7 +40,7 @@ def keygetter(
     obj: "Mapping[str, t.Any]",
     path: str,
 ) -> t.Union[None, t.Any, str, t.List[str], "Mapping[str, str]"]:
-    """obj, "foods__breakfast", obj['foods']['breakfast']
+    """obj, "foods__breakfast", obj['foods']['breakfast'].
 
     >>> keygetter({ "foods": { "breakfast": "cereal" } }, "foods__breakfast")
     'cereal'

src/libtmux/_vendor/version.py

@@ -2,7 +2,8 @@
 # This file is dual licensed under the terms of the Apache License, Version
 # 2.0, and the BSD License. See the LICENSE file in the root of this repository
 # for complete details.
-"""
+"""Backport of the ``packaging.version`` module from Python 3.8.
+
 .. testsetup::
 
     from packaging.version import parse, Version
@@ -159,7 +160,7 @@ def __ne__(self, other: object) -> bool:
 
 
 class Version(_BaseVersion):
-    """This class abstracts handling of a project's versions.
+    """Class abstracts handling of a project's versions.
 
     A :class:`Version` instance is comparison aware and can be compared and
     sorted using the standard Python interfaces.
@@ -194,7 +195,6 @@ def __init__(self, version: str) -> None:
             If the ``version`` does not conform to PEP 440 in any way then this
             exception will be raised.
         """
-
         # Validate the version and parse it into pieces
         match = self._regex.search(version)
         if not match:
@@ -223,15 +223,15 @@ def __init__(self, version: str) -> None:
         )
 
     def __repr__(self) -> str:
-        """A representation of the Version that shows all internal state.
+        """Return representation of the Version that shows all internal state.
 
         >>> Version('1.0.0')
         <Version('1.0.0')>
         """
         return f"<Version('{self}')>"
 
     def __str__(self) -> str:
-        """A string representation of the version that can be rounded-tripped.
+        """Return string representation of the version that can be rounded-tripped.
 
         >>> str(Version("1.0a5"))
         '1.0a5'
@@ -492,9 +492,7 @@ def _parse_letter_version(
 
 
 def _parse_local_version(local: str) -> Optional[LocalType]:
-    """
-    Takes a string like abc.1.twelve and turns it into ("abc", 1, "twelve").
-    """
+    """Take a string like abc.1.twelve and turns it into ("abc", 1, "twelve")."""
     if local is not None:
         return tuple(
             part.lower() if not part.isdigit() else int(part)

src/libtmux/common.py

@@ -1,5 +1,5 @@
 # flake8: NOQA: W605
-"""Helper methods and mixins.
+"""Helper methods and mixins for libtmux.
 
 libtmux.common
 ~~~~~~~~~~~~~~
@@ -36,11 +36,7 @@
 
 
 class EnvironmentMixin:
-
-    """
-    Mixin class for managing session and server level environment variables in
-    tmux.
-    """
+    """Mixin for manager session and server level environment variables in tmux."""
 
     _add_option = None
 
@@ -194,13 +190,11 @@ def getenv(self, name: str) -> Optional[t.Union[str, bool]]:
 
 
 class tmux_cmd:
-
     """
     :term:`tmux(1)` command via :py:mod:`subprocess`.
 
     Examples
     --------
-
     .. code-block:: python
 
         proc = tmux_cmd('new-session', '-s%' % 'my session')
@@ -220,7 +214,6 @@ class tmux_cmd:
 
     Notes
     -----
-
     .. versionchanged:: 0.8
         Renamed from ``tmux`` to ``tmux_cmd``.
     """
@@ -413,7 +406,6 @@ def has_minimum_version(raises: bool = True) -> bool:
 
     Notes
     -----
-
     .. versionchanged:: 0.7.0
         No longer returns version, returns True or False
 
@@ -436,8 +428,7 @@ def has_minimum_version(raises: bool = True) -> bool:
 
 
 def session_check_name(session_name: t.Optional[str]) -> None:
-    """
-    Raises exception session name invalid, modeled after tmux function.
+    """Raise exception session name invalid, modeled after tmux function.
 
     tmux(1) session names may not be empty, or include periods or colons.
     These delimiters are reserved for noting session, window and pane.
@@ -461,7 +452,7 @@ def session_check_name(session_name: t.Optional[str]) -> None:
 
 
 def handle_option_error(error: str) -> t.Type[exc.OptionError]:
-    """Raises exception if error in option command found.
+    """Raise exception if error in option command found.
 
     In tmux 3.0, show-option and show-window-option return invalid option instead of
     unknown option. See https://github.com/tmux/tmux/blob/3.0/cmd-show-options.c.

src/libtmux/exc.py

@@ -13,17 +13,14 @@
 
 
 class LibTmuxException(Exception):
-
     """Base Exception for libtmux Errors."""
 
 
 class TmuxSessionExists(LibTmuxException):
-
     """Session does not exist in the server."""
 
 
 class TmuxCommandNotFound(LibTmuxException):
-
     """Application binary for tmux not found."""
 
 
@@ -47,12 +44,10 @@ def __init__(
 
 
 class VersionTooLow(LibTmuxException):
-
     """Raised if tmux below the minimum version to use libtmux."""
 
 
 class BadSessionName(LibTmuxException):
-
     """Disallowed session name for tmux (empty, contains periods or colons)."""
 
     def __init__(
@@ -65,52 +60,45 @@ def __init__(
 
 
 class OptionError(LibTmuxException):
-
     """Root error for any error involving invalid, ambiguous or bad options."""
 
 
 class UnknownOption(OptionError):
-
     """Option unknown to tmux show-option(s) or show-window-option(s)."""
 
 
 class UnknownColorOption(UnknownOption):
-
     """Unknown color option."""
 
     def __init__(self, *args: object):
         return super().__init__("Server.colors must equal 88 or 256")
 
 
 class InvalidOption(OptionError):
-
     """Option invalid to tmux, introduced in tmux v2.4."""
 
 
 class AmbiguousOption(OptionError):
-
     """Option that could potentially match more than one."""
 
 
 class WaitTimeout(LibTmuxException):
-
-    """Function timed out without meeting condition"""
+    """Function timed out without meeting condition."""
 
 
 class VariableUnpackingError(LibTmuxException):
-
-    """Error unpacking variable"""
+    """Error unpacking variable."""
 
     def __init__(self, variable: t.Optional[t.Any] = None, *args: object):
         return super().__init__(f"Unexpected variable: {variable!s}")
 
 
 class PaneError(LibTmuxException):
-    """Any type of pane related error"""
+    """Any type of pane related error."""
 
 
 class PaneNotFound(PaneError):
-    """Pane not found"""
+    """Pane not found."""
 
     def __init__(self, pane_id: t.Optional[str] = None, *args: object):
         if pane_id is not None:
@@ -119,29 +107,25 @@ def __init__(self, pane_id: t.Optional[str] = None, *args: object):
 
 
 class WindowError(LibTmuxException):
-
-    """Any type of window related error"""
+    """Any type of window related error."""
 
 
 class MultipleActiveWindows(WindowError):
-
-    """Multiple active windows"""
+    """Multiple active windows."""
 
     def __init__(self, count: int, *args: object):
         return super().__init__(f"Multiple active windows: {count} found")
 
 
 class NoActiveWindow(WindowError):
-
-    """No active window found"""
+    """No active window found."""
 
     def __init__(self, *args: object):
         return super().__init__("No active windows found")
 
 
 class NoWindowsExist(WindowError):
-
-    """No windows exist for object"""
+    """No windows exist for object."""
 
     def __init__(self, *args: object):
         return super().__init__("No windows exist for object")