Additional doc clarifications and formatting improvements

This adds extra detail to some docstrings, and brings formatting
in line with Sphinx conventions.

Author: jholveck

docs/source/api.rst

@@ -7,11 +7,6 @@ Core Package
 
 .. automodule:: mss
 
-Factory Helpers
-===============
-
-.. automodule:: mss.factory
-
 Screenshot Objects
 ==================
 

docs/source/developers.rst

@@ -29,7 +29,7 @@ You will need `pytest <https://pypi.org/project/pytest/>`_::
 How to Test?
 ------------
 
-Launch the test suit::
+Launch the test suite::
 
     $ python -m pytest
 

src/mss/base.py

@@ -45,7 +45,7 @@
 class MSSBase(metaclass=ABCMeta):
     """This class will be overloaded by a system specific one."""
 
-    __slots__ = {"_monitors", "cls_image", "compression_level", "with_cursor", "_closed"}
+    __slots__ = {"_closed", "_monitors", "cls_image", "compression_level", "with_cursor"}
 
     def __init__(
         self,

src/mss/factory.py

@@ -17,6 +17,15 @@ def mss(**kwargs: Any) -> MSSBase:
 
     It then proxies its arguments to the class for
     instantiation.
+
+    .. seealso::
+        - :class:`mss.darwin.MSS`
+        - :class:`mss.linux.MSS`
+        - :class:`mss.windows.MSS`
+        - :func:`mss.linux.mss`
+        - :class:`mss.linux.xshmgetimage.MSS`
+        - :class:`mss.linux.xgetimage.MSS`
+        - :class:`mss.linux.xlib.MSS`
     """
     os_ = platform.system().lower()
 

src/mss/linux/__init__.py

@@ -1,23 +1,4 @@
-"""GNU/Linux backend dispatcher.
-
-This module picks the appropriate X11 backend implementation based on the
-``backend`` option. Available values:
-
-- ``"default"`` or ``"xshmgetimage"``: XCB-based backend using XShmGetImage
-    with automatic fallback to XGetImage when MIT-SHM is unavailable (default)
-- ``"xgetimage"``: XCB-based backend using XGetImage
-- ``"xlib"``: legacy Xlib-based backend retained for environments without
-    working XCB libraries
-
-Keyword arguments are forwarded to the selected backend. The ``display``
-argument (e.g., ``":0.0"``) targets a specific X server when needed.
-
-.. versionadded:: 10.2.0
-   The ``backend`` selector and the upper-case :func:`MSS` alias.
-
-The top-level :func:`mss` function proxies keyword arguments to the selected
-backend class and returns an :class:`mss.base.MSSBase` implementation.
-"""
+"""GNU/Linux backend dispatcher for X11 screenshot implementations."""
 
 from typing import Any
 
@@ -28,15 +9,32 @@
 
 
 def mss(backend: str = "default", **kwargs: Any) -> MSSBase:
-    """Return a backend-specific MSS implementation.
+    """Return a backend-specific MSS implementation for GNU/Linux.
+
+    Selects and instantiates the appropriate X11 backend based on the
+    ``backend`` parameter. Keyword arguments are forwarded to the selected
+    backend class.
 
-    The ``backend`` flag selects the implementation:
+    :param backend: Backend selector. Valid values:
 
-    - ``"default"``/``"xshmgetimage"`` (default): XCB backend using
-      XShmGetImage with automatic fallback to XGetImage
-    - ``"xgetimage"``: XCB backend using XGetImage
-    - ``"xlib"``: traditional Xlib backend retained for environments without
-      working XCB libraries
+        - ``"default"`` or ``"xshmgetimage"`` (default): XCB-based backend
+          using XShmGetImage with automatic fallback to XGetImage when MIT-SHM
+          is unavailable
+        - ``"xgetimage"``: XCB-based backend using XGetImage
+        - ``"xlib"``: Legacy Xlib-based backend retained for environments
+          without working XCB libraries
+
+        .. versionadded:: 10.2.0 Prior to this version, the
+            :class:`mss.linux.xlib.MSS` implementation was the only available
+            backend.
+
+    :param kwargs: Keyword arguments forwarded to the backend. Common options
+        include ``display`` (e.g., ``":0.0"``) to target a specific X server.
+    :returns: An MSS backend implementation.
+
+    .. versionadded:: 10.2.0 Prior to this version, this didn't exist:
+         the :func:`mss.linux.MSS` was a class equivalent to the current
+         :class:`mss.linux.xlib.MSS` implementation.
     """
     backend = backend.lower()
     if backend == "xlib":
@@ -61,4 +59,9 @@ def mss(backend: str = "default", **kwargs: Any) -> MSSBase:
 
 # Alias in upper-case for backward compatibility.  This is a supported name in the docs.
 def MSS(*args, **kwargs) -> MSSBase:  # type: ignore[no-untyped-def] # noqa: N802, ANN002, ANN003
+    """Alias for :func:`mss.linux.mss.mss` for backward compatibility.
+
+    .. versionchanged:: 10.2.0 Prior to this version, this was a class.
+    .. deprecated:: 10.2.0 Use :func:`mss.linux.mss` instead.
+    """
     return mss(*args, **kwargs)

src/mss/linux/base.py

@@ -23,19 +23,16 @@
 class MSSXCBBase(MSSBase):
     """Base class for XCB-based screenshot implementations.
 
-    This class provides common XCB initialization and monitor detection logic
-    that can be shared across different XCB screenshot methods (XGetImage,
-    XShmGetImage, XComposite, etc.).
+    Provides common XCB initialization and monitor detection logic that can be
+    shared across different XCB screenshot methods (``XGetImage``,
+    ``XShmGetImage``, ``XComposite``, etc.).
     """
 
     def __init__(self, /, **kwargs: Any) -> None:  # noqa: PLR0912
         """Initialize an XCB connection and validate the display configuration.
 
-        Args:
-            **kwargs: Keyword arguments, including optional 'display' for X11 display string.
-
-        Raises:
-            ScreenShotError: If the display configuration is not supported.
+        :param kwargs: Optional keyword arguments. Recognized key ``display``
+            specifies an X11 display string (bytes) to connect to.
         """
         super().__init__(**kwargs)
 
@@ -127,7 +124,12 @@ def _close_impl(self) -> None:
         self.conn = None
 
     def _monitors_impl(self) -> None:
-        """Get positions of monitors. It will populate self._monitors."""
+        """Populate monitor geometry information.
+
+        Detects and appends monitor rectangles to ``self._monitors``. The first
+        entry represents the entire X11 root screen; subsequent entries, when
+        available, represent individual monitors reported by XRandR.
+        """
         if self.conn is None:
             msg = "Cannot identify monitors while the connection is closed"
             raise ScreenShotError(msg)
@@ -187,6 +189,11 @@ def _monitors_impl(self) -> None:
         # style is.
 
     def _cursor_impl_check_xfixes(self) -> bool:
+        """Check XFixes availability and version.
+
+        :returns: ``True`` if the server provides XFixes with a compatible
+            version, otherwise ``False``.
+        """
         if self.conn is None:
             msg = "Cannot take screenshot while the connection is closed"
             raise ScreenShotError(msg)
@@ -201,7 +208,12 @@ def _cursor_impl_check_xfixes(self) -> bool:
         return (reply.major_version, reply.minor_version) >= (2, 0)
 
     def _cursor_impl(self) -> ScreenShot:
-        """Retrieve all cursor data. Pixels have to be RGBx."""
+        """Capture the current cursor image.
+
+        Pixels are returned in BGRA ordering.
+
+        :returns: A screenshot object containing the cursor image and region.
+        """
 
         if self.conn is None:
             msg = "Cannot take screenshot while the connection is closed"
@@ -229,10 +241,14 @@ def _cursor_impl(self) -> ScreenShot:
         return self.cls_image(data, region)
 
     def _grab_impl_xgetimage(self, monitor: Monitor, /) -> ScreenShot:
-        """Retrieve all pixels from a monitor using GetImage.
+        """Retrieve pixels from a monitor using ``GetImage``.
+
+        Used by the XGetImage backend and by the XShmGetImage backend in
+        fallback mode.
 
-        This is used by the XGetImage backend, and also the XShmGetImage
-        backend in fallback mode.
+        :param monitor: Monitor rectangle specifying ``left``, ``top``,
+            ``width``, and ``height`` to capture.
+        :returns: A screenshot object containing the captured region.
         """
 
         if self.conn is None:

src/mss/linux/xgetimage.py

@@ -2,6 +2,11 @@
 
 This backend issues XCB ``GetImage`` requests and supports the RandR and
 XFixes extensions when available for monitor enumeration and cursor capture.
+
+This backend will work on any X connection, but is slower than the xshmgetimage
+backend.
+
+.. versionadded:: 10.2.0
 """
 
 from mss.models import Monitor
@@ -11,11 +16,7 @@
 
 
 class MSS(MSSXCBBase):
-    """XCB backend using XGetImage requests on GNU/Linux.
-
-    Uses RandR (for monitor enumeration) and XFixes (for cursor capture) when
-    available.
-    """
+    """XCB backend using XGetImage requests on GNU/Linux."""
 
     def _grab_impl(self, monitor: Monitor) -> ScreenShot:
         """Retrieve all pixels from a monitor. Pixels have to be RGBX."""

src/mss/linux/xlib.py

@@ -3,6 +3,9 @@
 This backend talks to X11 via Xlib and the Xrandr extension, and is retained
 as a fallback when XCB backends are unavailable. Cursor capture uses XFixes
 when available.
+
+.. versionadded:: 10.2.0 Prior to this version, this was available as
+    ``mss.linux.MSS``.
 """
 
 from __future__ import annotations
@@ -415,15 +418,18 @@ def __init__(self, /, **kwargs: Any) -> None:
         if not _X11:
             msg = "No X11 library found."
             raise ScreenShotError(msg)
+        #: :meta private:
         self.xlib = cdll.LoadLibrary(_X11)
 
         if not _XRANDR:
             msg = "No Xrandr extension found."
             raise ScreenShotError(msg)
+        #: :meta private:
         self.xrandr = cdll.LoadLibrary(_XRANDR)
 
         if self.with_cursor:
             if _XFIXES:
+                #: :meta private:
                 self.xfixes = cdll.LoadLibrary(_XFIXES)
             else:
                 self.with_cursor = False

src/mss/linux/xshmgetimage.py

@@ -1,9 +1,14 @@
 """XCB backend using MIT-SHM XShmGetImage with automatic fallback.
 
+This is the fastest Linux backend available, and will work in most common
+cases. However, it will not work over remote X connections, such as over ssh.
+
 This implementation prefers shared-memory captures for performance and will
 fall back to XGetImage when the MIT-SHM extension is unavailable or fails at
 runtime. The fallback reason is exposed via ``shm_fallback_reason`` to aid
 debugging.
+
+.. versionadded:: 10.2.0
 """
 
 from __future__ import annotations
@@ -33,12 +38,7 @@ class ShmStatus(enum.Enum):
 
 
 class MSS(MSSXCBBase):
-    """XCB backend using XShmGetImage with an automatic XGetImage fallback.
-
-    The ``shm_status`` attribute tracks whether shared memory is available,
-    and ``shm_fallback_reason`` records why a fallback occurred when MIT-SHM
-    cannot be used.
-    """
+    """XCB backend using XShmGetImage with an automatic XGetImage fallback."""
 
     def __init__(self, /, **kwargs: Any) -> None:
         super().__init__(**kwargs)
@@ -52,7 +52,11 @@ def __init__(self, /, **kwargs: Any) -> None:
         # isn't available.  The factory in linux/__init__.py could then catch that and switch to XGetImage.
         # The conditions under which the attach will succeed but the xcb_shm_get_image will fail are extremely
         # rare, and I haven't yet found any that also will work with xcb_get_image.
+        #: Whether we can use the MIT-SHM extensions for this connection.
+        #: This will not be ``AVAILABLE`` until at least one capture has succeeded.
+        #: It may be set to ``UNAVAILABLE`` sooner.
         self.shm_status: ShmStatus = self._setup_shm()
+        #: If MIT-SHM is unavailable, the reason why (for debugging purposes).
         self.shm_fallback_reason: str | None = None
 
     def _shm_report_issue(self, msg: str, *args: Any) -> None:

src/mss/models.py

@@ -1,6 +1,5 @@
-"""This is part of the MSS Python's module.
-Source: https://github.com/BoboTiG/python-mss.
-"""
+# This is part of the MSS Python's module.
+# Source: https://github.com/BoboTiG/python-mss.
 
 from typing import Any, NamedTuple