xvfbwrapper 0.2.29__tar.gz → 0.2.31__tar.gz

{xvfbwrapper-0.2.29/xvfbwrapper.egg-info → xvfbwrapper-0.2.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xvfbwrapper
-Version: 0.2.29
+Version: 0.2.31
 Summary: Manage headless displays with Xvfb (X virtual framebuffer)
 Author: Corey Goldberg
 Maintainer: Corey Goldberg
@@ -37,18 +37,19 @@ Dynamic: license-file
 
 ## About
 
-`xvfbwrapper` is a Python library for controlling X11 virtual displays with Xvfb.
+`xvfbwrapper` is a Python library for managing X11 virtual displays with
+[Xvfb (X virtual framebuffer)](https://x.org/releases/X11R7.7/doc/man/man1/Xvfb.1.xhtml),
+a virtual X server that runs without a physical display. It provides the
+[`Xvfb`][api-docs] class, a Python interface for configuring and controlling the Xvfb
+program.
+
+See the [module API documentation][api-docs] for more information.
 
 - Copyright (c) 2012-2026 [Corey Goldberg][github-profile]
 - Development: [GitHub][github-repo]
 - Releases: [PyPI][pypi-home]
 - License: [MIT][mit-license]
 
-The package provides the `xvfvwrapper.Xvfb` class that is used to interact with
-an Xvfb server.
-
-See the [module API documentation][api-docs] for more information.
-
 ----
 
 ## Status
@@ -116,7 +117,7 @@ pip install xvfbwrapper
 - Python 3.10+
 - X Window System
 - Xvfb (`sudo apt-get install xvfb`, `yum install xorg-x11-server-Xvfb`, etc)
-- Support for locking with `fcntl` system call (non-Windows systems)
+- Support for file locking using `fcntl` (POSIX systems)
 
 ----
 
@@ -244,10 +245,10 @@ finally:
     xvfb2.stop()
 ```
 
-#### Usage in testing - headless Selenium WebDriver tests:
+#### Example: headless browser tests:
 
-This is a test using `selenium` and `xvfbwrapper` to run tests
-on Chrome with a headless display. (see: [selenium docs][selenium-docs])
+This uses [`selenium`][selenium-docs] and `xvfbwrapper` to run a test
+on Chrome with a headless display.
 
 [selenium-docs]: https://www.selenium.dev/selenium/docs/api/py
 

{xvfbwrapper-0.2.29 → xvfbwrapper-0.2.31}/README.md

@@ -6,18 +6,19 @@
 
 ## About
 
-`xvfbwrapper` is a Python library for controlling X11 virtual displays with Xvfb.
+`xvfbwrapper` is a Python library for managing X11 virtual displays with
+[Xvfb (X virtual framebuffer)](https://x.org/releases/X11R7.7/doc/man/man1/Xvfb.1.xhtml),
+a virtual X server that runs without a physical display. It provides the
+[`Xvfb`][api-docs] class, a Python interface for configuring and controlling the Xvfb
+program.
+
+See the [module API documentation][api-docs] for more information.
 
 - Copyright (c) 2012-2026 [Corey Goldberg][github-profile]
 - Development: [GitHub][github-repo]
 - Releases: [PyPI][pypi-home]
 - License: [MIT][mit-license]
 
-The package provides the `xvfvwrapper.Xvfb` class that is used to interact with
-an Xvfb server.
-
-See the [module API documentation][api-docs] for more information.
-
 ----
 
 ## Status
@@ -85,7 +86,7 @@ pip install xvfbwrapper
 - Python 3.10+
 - X Window System
 - Xvfb (`sudo apt-get install xvfb`, `yum install xorg-x11-server-Xvfb`, etc)
-- Support for locking with `fcntl` system call (non-Windows systems)
+- Support for file locking using `fcntl` (POSIX systems)
 
 ----
 
@@ -213,10 +214,10 @@ finally:
     xvfb2.stop()
 ```
 
-#### Usage in testing - headless Selenium WebDriver tests:
+#### Example: headless browser tests:
 
-This is a test using `selenium` and `xvfbwrapper` to run tests
-on Chrome with a headless display. (see: [selenium docs][selenium-docs])
+This uses [`selenium`][selenium-docs] and `xvfbwrapper` to run a test
+on Chrome with a headless display.
 
 [selenium-docs]: https://www.selenium.dev/selenium/docs/api/py
 

{xvfbwrapper-0.2.29 → xvfbwrapper-0.2.31}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xvfbwrapper"
-version = "0.2.29"
+version = "0.2.31"
 description = "Manage headless displays with Xvfb (X virtual framebuffer)"
 license = "MIT"
 license-files = ["LICENSE"]

{xvfbwrapper-0.2.29 → xvfbwrapper-0.2.31}/test_xvfb.py

@@ -216,7 +216,8 @@ class TestXvfb(XvfbCleanTestCase):
         unwriteable_dir = "/etc"
         xvfb = Xvfb(tempdir=unwriteable_dir)
         with self.assertRaisesRegex(
-            RuntimeError, f"Could not access writable temp directory: {unwriteable_dir}"
+            RuntimeError,
+            f"Could not access writable temp directory: {unwriteable_dir}",
         ):
             xvfb.start()
         self.assertIsNone(xvfb.proc)
@@ -225,7 +226,8 @@ class TestXvfb(XvfbCleanTestCase):
         unknown_dir = "/tmp/some_unknown_path"
         xvfb = Xvfb(tempdir=unknown_dir)
         with self.assertRaisesRegex(
-            RuntimeError, f"Could not access writable temp directory: {unknown_dir}"
+            RuntimeError,
+            f"Could not access writable temp directory: {unknown_dir}",
         ):
             xvfb.start()
         self.assertIsNone(xvfb.proc)
@@ -300,7 +302,7 @@ class TestXvfb(XvfbCleanTestCase):
         self.assertIsNotNone(xvfb.proc)
 
     def test_start_fails_with_unknown_kwargs(self):
-        xvfb = Xvfb(foo="bar", timeout=5)
+        xvfb = Xvfb(foo="bar", timeout=2)
         expected_cmd_args = [
             "Xvfb",
             r":\d",
@@ -311,7 +313,8 @@ class TestXvfb(XvfbCleanTestCase):
             "bar",
         ]
         with self.assertRaisesRegex(
-            RuntimeError, f"Xvfb display did not open: {expected_cmd_args}"
+            RuntimeError,
+            f"Xvfb display did not open: {expected_cmd_args}",
         ):
             xvfb.start()
         self.assertIsNone(xvfb.proc)

{xvfbwrapper-0.2.29 → xvfbwrapper-0.2.31}/tox.ini

@@ -14,9 +14,6 @@ envlist =
     lint
     type
     py310
-    py311
-    py312
-    py313
     py314
     pypy3
 skip_missing_interpreters = true

{xvfbwrapper-0.2.29 → xvfbwrapper-0.2.31/xvfbwrapper.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xvfbwrapper
-Version: 0.2.29
+Version: 0.2.31
 Summary: Manage headless displays with Xvfb (X virtual framebuffer)
 Author: Corey Goldberg
 Maintainer: Corey Goldberg
@@ -37,18 +37,19 @@ Dynamic: license-file
 
 ## About
 
-`xvfbwrapper` is a Python library for controlling X11 virtual displays with Xvfb.
+`xvfbwrapper` is a Python library for managing X11 virtual displays with
+[Xvfb (X virtual framebuffer)](https://x.org/releases/X11R7.7/doc/man/man1/Xvfb.1.xhtml),
+a virtual X server that runs without a physical display. It provides the
+[`Xvfb`][api-docs] class, a Python interface for configuring and controlling the Xvfb
+program.
+
+See the [module API documentation][api-docs] for more information.
 
 - Copyright (c) 2012-2026 [Corey Goldberg][github-profile]
 - Development: [GitHub][github-repo]
 - Releases: [PyPI][pypi-home]
 - License: [MIT][mit-license]
 
-The package provides the `xvfvwrapper.Xvfb` class that is used to interact with
-an Xvfb server.
-
-See the [module API documentation][api-docs] for more information.
-
 ----
 
 ## Status
@@ -116,7 +117,7 @@ pip install xvfbwrapper
 - Python 3.10+
 - X Window System
 - Xvfb (`sudo apt-get install xvfb`, `yum install xorg-x11-server-Xvfb`, etc)
-- Support for locking with `fcntl` system call (non-Windows systems)
+- Support for file locking using `fcntl` (POSIX systems)
 
 ----
 
@@ -244,10 +245,10 @@ finally:
     xvfb2.stop()
 ```
 
-#### Usage in testing - headless Selenium WebDriver tests:
+#### Example: headless browser tests:
 
-This is a test using `selenium` and `xvfbwrapper` to run tests
-on Chrome with a headless display. (see: [selenium docs][selenium-docs])
+This uses [`selenium`][selenium-docs] and `xvfbwrapper` to run a test
+on Chrome with a headless display.
 
 [selenium-docs]: https://www.selenium.dev/selenium/docs/api/py
 

{xvfbwrapper-0.2.29 → xvfbwrapper-0.2.31}/xvfbwrapper.py

@@ -2,7 +2,14 @@
 # SPDX-License-Identifier: MIT
 
 
-"""Run a headless display inside X virtual framebuffer (Xvfb)."""
+"""Manage headless displays with Xvfb (X virtual framebuffer)
+
+This module provides a wrapper around Xvfb (X Virtual Framebuffer) for managing
+virtual X displays.
+
+- Releases: https://pypi.org/project/xvfbwrapper
+- Development: https://github.com/cgoldberg/xvfbwrapper
+"""
 
 import os
 import platform
@@ -25,6 +32,11 @@ except ImportError as e:
 
 
 class Xvfb:
+    """Manage an Xvfb (X Virtual Framebuffer) process.
+
+    Provides an interface for configuring and controlling a virtual X display.
+    """
+
     # Maximum value to use for a display. 32-bit maxint is the
     # highest Xvfb currently supports
     MAX_DISPLAY: int = 2147483647
@@ -39,46 +51,39 @@ class Xvfb:
         set_xdg_session_type: bool = False,
         environ: MutableMapping[str, str] | None = None,
         extra_args: Sequence[str] | None = None,
-        timeout: float = 10,
+        timeout: float | None = 10,
         **kwargs: str,
     ) -> None:
         self.width: int = width
         self.height: int = height
         self.colordepth: int = colordepth
         self._tempdir: Path | str = tempdir or tempfile.gettempdir()
-        self._timeout: float = timeout
+        self._timeout: float | None = timeout
         self.new_display: int | None = display
         self.environ: MutableMapping[str, str] = environ or os.environ
-
         if set_xdg_session_type:
             os.environ["XDG_SESSION_TYPE"] = "x11"
-
+            self.environ["XDG_SESSION_TYPE"] = "x11"
         if not self._xvfb_exists():
             raise FileNotFoundError(
                 "Could not find Xvfb. Please install it and try again"
             )
-
         self.xvfb_cmd: list[str] = []
-
         if not extra_args:
             extra_args = []
-
         self.extra_xvfb_args: list[str] = [
             "-screen",
             "0",
             f"{self.width}x{self.height}x{self.colordepth}",
             *extra_args,
         ]
-
         for key, value in kwargs.items():
             self.extra_xvfb_args += [f"-{key}", value]
-
         self.orig_display_var: str | None
         if "DISPLAY" in self.environ:
             self.orig_display_var = self.environ["DISPLAY"]
         else:
             self.orig_display_var = None
-
         self.proc: subprocess.Popen[bytes] | None = None
         self._lock_display_file: TextIO | None = None
 
@@ -95,6 +100,8 @@ class Xvfb:
         self.stop()
 
     def start(self) -> None:
+        """Start Xvfb."""
+
         if not os.access(self._tempdir, os.W_OK):
             raise RuntimeError(
                 f"Could not access writable temp directory: {self._tempdir}"
@@ -113,10 +120,11 @@ class Xvfb:
             close_fds=True,
             env=dict(self.environ),
         )
-        start = time.time()
+        start = time.monotonic()
         while not self._local_display_exists(self.new_display):
             time.sleep(1e-3)
-            if time.time() - start > self._timeout:
+            elapsed = time.monotonic() - start
+            if self._timeout is not None and elapsed > self._timeout:
                 self.stop()
                 raise RuntimeError(f"Xvfb display did not open: {self.xvfb_cmd}")
         ret_code = self.proc.poll()
@@ -127,6 +135,19 @@ class Xvfb:
             raise RuntimeError(f"Xvfb did not start ({ret_code}): {self.xvfb_cmd}")
 
     def stop(self) -> None:
+        """Stop Xvfb and clean up its resources.
+
+        Terminate the process, escalating to kill if it does not exit within the
+        timeout. If the process has already exited, termination is treated as
+        successful. If `self._timeout` is set, wait up to that duration for termination
+        and, if necessary, an additional duration of the same length after killing the
+        process. If `self._timeout` is `None`, wait indefinitely for the process to
+        exit and be reaped.
+
+        This is a one-way lifecycle transition: once called, this object is considered
+        stopped and cannot be reused, regardless of whether the process exits
+        successfully.
+        """
         if self.proc is None:
             return
         try:
@@ -134,13 +155,15 @@ class Xvfb:
                 self.environ.pop("DISPLAY", None)
             else:
                 self._set_display(self.orig_display_var)
-
-            with suppress(OSError):
+            with suppress(ProcessLookupError):
                 self.proc.terminate()
+            try:
+                self.proc.wait(self._timeout)
+            except subprocess.TimeoutExpired:
+                self.proc.kill()
                 self.proc.wait(self._timeout)
-
-            self.proc = None
         finally:
+            self.proc = None
             self._cleanup_lock_file()
 
     def _xvfb_exists(self) -> bool:
@@ -160,7 +183,6 @@ class Xvfb:
         """
         if self._lock_display_file is None:
             return
-
         self._lock_display_file.close()
         with suppress(OSError):
             Path(self._lock_display_file.name).unlink()