docs: Improve test.py

Author: tony

src/libtmux/test.py

@@ -1,4 +1,11 @@
-"""Helper methods for libtmux and downstream libtmux libraries."""
+"""Provide helper methods for libtmux and downstream libtmux libraries.
+
+This module includes various testing utilities, context managers, and utility
+functions to facilitate session creation, window creation, retries, and
+environment variable manipulation. It preserves existing testing scenarios and
+patterns, ensuring stable and consistent integration tests across different
+libtmux-based projects.
+"""
 
 from __future__ import annotations
 
@@ -30,30 +37,31 @@
 
 
 class RandomStrSequence:
-    """Factory to generate random string."""
+    """Generate random string values (8 chars each) from a given character set.
+
+    Examples
+    --------
+    >>> rng = RandomStrSequence()
+    >>> next(rng)
+    '...'
+    >>> len(next(rng))
+    8
+    >>> type(next(rng))
+    <class 'str'>
+    """
 
     def __init__(
         self,
         characters: str = "abcdefghijklmnopqrstuvwxyz0123456789_",
     ) -> None:
-        """Create a random letter / number generator. 8 chars in length.
-
-        >>> rng = RandomStrSequence()
-        >>> next(rng)
-        '...'
-        >>> len(next(rng))
-        8
-        >>> type(next(rng))
-        <class 'str'>
-        """
         self.characters: str = characters
 
     def __iter__(self) -> RandomStrSequence:
-        """Return self."""
+        """Return self as iterator."""
         return self
 
     def __next__(self) -> str:
-        """Return next random string."""
+        """Return next random 8-character string."""
         return "".join(random.sample(self.characters, k=8))
 
 
@@ -70,22 +78,21 @@ def retry_until(
     interval: float = RETRY_INTERVAL_SECONDS,
     raises: bool | None = True,
 ) -> bool:
-    """
-    Retry a function until a condition meets or the specified time passes.
+    r"""Retry a function until it returns True or time expires.
 
     Parameters
     ----------
     fun : callable
-        A function that will be called repeatedly until it returns ``True``  or
-        the specified time passes.
-    seconds : float
-        Seconds to retry. Defaults to ``8``, which is configurable via
-        ``RETRY_TIMEOUT_SECONDS`` environment variables.
-    interval : float
-        Time in seconds to wait between calls. Defaults to ``0.05`` and is
-        configurable via ``RETRY_INTERVAL_SECONDS`` environment variable.
-    raises : bool
-        Whether or not to raise an exception on timeout. Defaults to ``True``.
+        A function that will be called repeatedly until it returns True or the
+        specified time passes.
+    seconds : float, optional
+        Time limit for retries. Defaults to 8 seconds or the environment
+        variable `RETRY_TIMEOUT_SECONDS`.
+    interval : float, optional
+        Time in seconds to wait between calls. Defaults to 0.05 or
+        `RETRY_INTERVAL_SECONDS`.
+    raises : bool, optional
+        Whether to raise :exc:`WaitTimeout` on timeout. Defaults to True.
 
     Examples
     --------
@@ -100,11 +107,11 @@ def retry_until(
 
     >>> assert retry_until(fn, raises=False)
     """
-    ini = time.time()
+    start_time = time.time()
 
     while not fun():
-        end = time.time()
-        if end - ini >= seconds:
+        now = time.time()
+        if now - start_time >= seconds:
             if raises:
                 raise WaitTimeout
             return False
@@ -114,20 +121,19 @@ def retry_until(
 
 def get_test_session_name(server: Server, prefix: str = TEST_SESSION_PREFIX) -> str:
     """
-    Faker to create a session name that doesn't exist.
+    Generate a unique session name that does not exist on the server.
 
     Parameters
     ----------
-    server : :class:`libtmux.Server`
-        libtmux server
+    server : Server
+        The tmux server instance.
     prefix : str
-        prefix for sessions (e.g. ``libtmux_``). Defaults to
-        ``TEST_SESSION_PREFIX``.
+        Prefix for the generated session name. Defaults to 'libtmux_'.
 
     Returns
     -------
     str
-        Random session name guaranteed to not collide with current ones.
+        Random session name guaranteed not to collide with existing sessions.
 
     Examples
     --------
@@ -150,22 +156,19 @@ def get_test_window_name(
     prefix: str | None = TEST_SESSION_PREFIX,
 ) -> str:
     """
-    Faker to create a window name that doesn't exist.
+    Generate a unique window name that does not exist in the given session.
 
     Parameters
     ----------
-    session : :class:`libtmux.Session`
-        libtmux session
-    prefix : str
-        prefix for windows (e.g. ``libtmux_``). Defaults to
-        ``TEST_SESSION_PREFIX``.
-
-        ATM we reuse the test session prefix here.
+    session : Session
+        The tmux session instance.
+    prefix : str, optional
+        Prefix for the generated window name. Defaults to 'libtmux_'.
 
     Returns
     -------
     str
-        Random window name guaranteed to not collide with current ones.
+        Random window name guaranteed not to collide with existing windows.
 
     Examples
     --------
@@ -191,28 +194,25 @@ def temp_session(
     **kwargs: t.Any,
 ) -> Generator[Session, t.Any, t.Any]:
     """
-    Return a context manager with a temporary session.
-
-    If no ``session_name`` is entered, :func:`get_test_session_name` will make
-    an unused session name.
+    Provide a context manager for a temporary session, killed on exit.
 
-    The session will destroy itself upon closing with :meth:`Session.session()`.
+    If no ``session_name`` is specified, :func:`get_test_session_name` will
+    generate an unused one. The session is destroyed upon exiting the context
+    manager.
 
     Parameters
     ----------
-    server : :class:`libtmux.Server`
-
-    Other Parameters
-    ----------------
+    server : Server
+        The tmux server instance.
     args : list
-        Arguments passed into :meth:`Server.new_session`
+        Additional positional arguments for :meth:`Server.new_session`.
     kwargs : dict
-        Keyword arguments passed into :meth:`Server.new_session`
+        Keyword arguments for :meth:`Server.new_session`.
 
     Yields
     ------
-    :class:`libtmux.Session`
-        Temporary session
+    Session
+        The newly created temporary session.
 
     Examples
     --------
@@ -242,37 +242,32 @@ def temp_window(
     **kwargs: t.Any,
 ) -> Generator[Window, t.Any, t.Any]:
     """
-    Return a context manager with a temporary window.
+    Provide a context manager for a temporary window, killed on exit.
 
-    The window will destroy itself upon closing with :meth:`window.
-    kill()`.
-
-    If no ``window_name`` is entered, :func:`get_test_window_name` will make
-    an unused window name.
+    If no ``window_name`` is specified, :func:`get_test_window_name` will
+    generate an unused one. The window is destroyed upon exiting the context
+    manager.
 
     Parameters
     ----------
-    session : :class:`libtmux.Session`
-
-    Other Parameters
-    ----------------
+    session : Session
+        The tmux session instance.
     args : list
-        Arguments passed into :meth:`Session.new_window`
+        Additional positional arguments for :meth:`Session.new_window`.
     kwargs : dict
-        Keyword arguments passed into :meth:`Session.new_window`
+        Keyword arguments for :meth:`Session.new_window`.
 
     Yields
     ------
-    :class:`libtmux.Window`
-        temporary window
+    Window
+        The newly created temporary window.
 
     Examples
     --------
     >>> with temp_window(session) as window:
     ...     window
     Window(@2 2:... Session($1 libtmux_...))
 
-
     >>> with temp_window(session) as window:
     ...     window.split()
     Pane(%4 Window(@3 2:libtmux_..., Session($1 libtmux_...)))
@@ -283,8 +278,6 @@ def temp_window(
         window_name = kwargs.pop("window_name")
 
     window = session.new_window(window_name, *args, **kwargs)
-
-    # Get ``window_id`` before returning it, it may be killed within context.
     window_id = window.window_id
     assert window_id is not None
     assert isinstance(window_id, str)
@@ -298,21 +291,19 @@ def temp_window(
 
 
 class EnvironmentVarGuard:
-    """Mock environmental variables safely.
+    """Safely mock environmental variables within a context manager.
 
-    Helps rotect the environment variable properly.  Can be used as context
-    manager.
+    Ensures any changes to environment variables are reverted upon exit.
 
     Notes
     -----
-    Vendorized to fix issue with Anaconda Python 2 not including test module,
-    see #121 [1]_
+    This is vendorized to address issues where some Python distributions do
+    not include test modules such as test_support.
 
     References
     ----------
-    .. [1] Just installed, "ImportError: cannot import name test_support".
-       GitHub issue for tmuxp. https://github.com/tmux-python/tmuxp/issues/121.
-       Created October 12th, 2015. Accessed April 7th, 2018.
+    #. "ImportError: cannot import name test_support" found in certain Python
+       distributions, see issue #121 in the tmuxp project.
     """
 
     def __init__(self) -> None:
@@ -321,21 +312,21 @@ def __init__(self) -> None:
         self._reset: dict[str, str] = {}
 
     def set(self, envvar: str, value: str) -> None:
-        """Set environment variable."""
+        """Set an environment variable, preserving prior state."""
         if envvar not in self._environ:
             self._unset.add(envvar)
         else:
             self._reset[envvar] = self._environ[envvar]
         self._environ[envvar] = value
 
     def unset(self, envvar: str) -> None:
-        """Unset environment variable."""
+        """Unset an environment variable, preserving prior state."""
         if envvar in self._environ:
             self._reset[envvar] = self._environ[envvar]
             del self._environ[envvar]
 
     def __enter__(self) -> Self:
-        """Return context for for context manager."""
+        """Enter context manager."""
         return self
 
     def __exit__(
@@ -344,7 +335,7 @@ def __exit__(
         exc_value: BaseException | None,
         exc_tb: types.TracebackType | None,
     ) -> None:
-        """Cleanup to run after context manager finishes."""
+        """Exit context manager, reverting environment changes."""
         for envvar, value in self._reset.items():
             self._environ[envvar] = value
         for unset in self._unset: