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.