xvfbwrapper 0.2.10__py3-none-any.whl

xvfbwrapper-0.2.10.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2012-2025 Corey Goldberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xvfbwrapper-0.2.10.dist-info/METADATA

@@ -0,0 +1,273 @@
+Metadata-Version: 2.2
+Name: xvfbwrapper
+Version: 0.2.10
+Summary: Manage headless displays with Xvfb (X virtual framebuffer)
+Home-page: https://github.com/cgoldberg/xvfbwrapper
+Download-URL: https://pypi.org/project/xvfbwrapper
+Author: Corey Goldberg
+License: MIT
+Keywords: xvfb,headless,virtual,display,x11,testing
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: summary
+
+
+===============
+    xvfbwrapper
+===============
+
+
+**Manage headless displays with Xvfb (X virtual framebuffer)**
+
+----
+
+---------
+    Info:
+---------
+
+- Development: https://github.com/cgoldberg/xvfbwrapper
+- Releases: https://pypi.org/project/xvfbwrapper
+- Author: `Corey Goldberg <https://github.com/cgoldberg>`_ - 2012-2025
+- License: MIT
+
+----
+
+----------------------
+    About xvfbwrapper:
+----------------------
+
+`xvfbwrapper` is a python module for controlling virtual displays with Xvfb.
+
+----
+
+------------------
+    What is Xvfb?:
+------------------
+
+`Xvfb` (X virtual framebuffer) is a display server implementing the X11 display server protocol.
+It runs in memory and does not require a physical display or input devices. Only a network layer is necessary.
+
+`Xvfb` is useful for running acceptance tests on headless servers.
+
+----
+
+----------------------------------
+    Install xvfbwrapper from PyPI:
+----------------------------------
+
+.. code:: bash
+
+    pip install xvfbwrapper
+
+----
+
+------------------------
+    System Requirements:
+------------------------
+
+* Python 3.8+
+* X Window System
+* Xvfb (`sudo apt-get install xvfb`, `yum install xorg-x11-server-Xvfb`, etc)
+* File locking with `fcntl` 
+
+----
+
+-------------
+    Examples:
+-------------
+
+****************
+    Basic Usage:
+****************
+
+.. code:: python
+
+    from xvfbwrapper import Xvfb
+
+    vdisplay = Xvfb()
+    vdisplay.start()
+
+    try:
+        # launch stuff inside virtual display here.
+    finally:
+        # always either wrap your usage of Xvfb() with try / finally,
+        # or alternatively use Xvfb as a context manager.
+        # If you don't, you'll probably end up with a bunch of junk in /tmp
+        vdisplay.stop()
+
+----
+
+*********************************************
+    Basic Usage, specifying display geometry:
+*********************************************
+
+.. code:: python
+
+    from xvfbwrapper import Xvfb
+
+    vdisplay = Xvfb(width=1280, height=740)
+    vdisplay.start()
+
+    try:
+        # launch stuff inside virtual display here.
+    finally:
+        vdisplay.stop()
+
+----
+
+*******************************************
+    Basic Usage, specifying display number:
+*******************************************
+
+.. code:: python
+
+    from xvfbwrapper import Xvfb
+
+    vdisplay = Xvfb(display=23)
+    vdisplay.start()
+    # Xvfb is started with display :23
+    # see vdisplay.new_display
+
+----
+
+*******************************
+    Usage as a Context Manager:
+*******************************
+
+.. code:: python
+
+    from xvfbwrapper import Xvfb
+
+    with Xvfb() as xvfb:
+        # launch stuff inside virtual display here.
+        # Xvfb will stop when this block completes
+
+----
+
+********************************************************
+    Usage in Testing: Headless Selenium WebDriver Tests:
+********************************************************
+
+This test class uses *selenium webdriver* and *xvfbwrapper* to run tests
+on Chrome with a headless display.
+
+.. code:: python
+
+    import unittest
+
+    from selenium import webdriver
+    from xvfbwrapper import Xvfb
+
+
+    class TestPages(unittest.TestCase):
+
+        def setUp(self):
+            self.xvfb = Xvfb(width=1280, height=720)
+            self.addCleanup(self.xvfb.stop)
+            self.xvfb.start()
+            self.browser = webdriver.Chrome()
+            self.addCleanup(self.browser.quit)
+
+        def testUbuntuHomepage(self):
+            self.browser.get('https://www.ubuntu.com')
+            self.assertIn('Ubuntu', self.browser.title)
+
+        def testGoogleHomepage(self):
+            self.browser.get('https://www.google.com')
+            self.assertIn('Google', self.browser.title)
+
+
+    if __name__ == '__main__':
+        unittest.main()
+
+* virtual display is launched
+* Chrome launches inside virtual display (headless)
+* browser is not shown while tests are run
+* conditions are asserted in each test case
+* browser quits during cleanup
+* virtual display stops during cleanup
+
+*Look Ma', no browser!*
+
+(You can also take screenshots inside the virtual display to help diagnose test failures)
+
+----
+
+***************************************
+    Usage with multi-threaded execution
+***************************************
+
+To run several xvfb servers at the same time, you can use the environ keyword
+when starting the Xvfb instances. This provides isolation between threads. Be
+sure to use the environment dictionary you initialize Xvfb with in your
+subsequent system calls. Also, if you wish to inherit your current environment
+you must use the copy method of os.environ and not simply assign a new
+variable to os.environ:
+
+.. code:: python
+
+    from xvfbwrapper import Xvfb
+    import subprocess as sp
+    import os
+
+    isolated_environment = os.environ.copy()
+    xvfb = Xvfb(environ=isolated_environment)
+    xvfb.start()
+    sp.run(
+        "xterm & sleep 1; kill %1 ",
+        shell=True,
+        env=isolated_environment,
+    )
+    xvfb.stop()
+
+----
+
+----------------------------------------------------
+    xvfbwrapper Development: running the unit tests:
+----------------------------------------------------
+
+To create a virtual env and install required testing libraries:
+
+.. code:: bash
+
+    $ python -m venv venv
+    $ source ./venv/bin/activate
+    (venv)$ pip install -r requirements_test.txt
+
+To run all tests, linting, and type checking across all
+supported/installed Python environments:
+
+.. code:: bash
+
+    (venv)$ tox
+
+To run all tests in the default Python environment:
+
+.. code:: bash
+
+    (venv)$ pytest

xvfbwrapper-0.2.10.dist-info/RECORD

@@ -0,0 +1,6 @@
+xvfbwrapper.py,sha256=o9h-9oAJ1YKeex0pcmMZpMfDgZIeTiKnF43z50kzCFQ,5805
+xvfbwrapper-0.2.10.dist-info/LICENSE,sha256=q0UOp9shMIWanBjEZAQuqDMHoTlIXkK9_6xigJGZp_M,1076
+xvfbwrapper-0.2.10.dist-info/METADATA,sha256=UX0LGCsmADH3zaNNV6Kes6qr9SXu5t2OvVKgLd2vgKY,6903
+xvfbwrapper-0.2.10.dist-info/WHEEL,sha256=52BFRY2Up02UkjOa29eZOS2VxUrpPORXg1pkohGGUS8,91
+xvfbwrapper-0.2.10.dist-info/top_level.txt,sha256=LAS6W1pYzXvAHmQ8-X5IVkjjtCrFgnkX11NNzKtmMOc,12
+xvfbwrapper-0.2.10.dist-info/RECORD,,

xvfbwrapper-0.2.10.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (76.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

xvfbwrapper-0.2.10.dist-info/top_level.txt

@@ -0,0 +1 @@
+xvfbwrapper

xvfbwrapper.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+# Corey Goldberg, 2012-2025
+# License: MIT
+
+
+'''Run a headless display inside X virtual framebuffer (Xvfb)'''
+
+
+import os
+import platform
+import subprocess
+import tempfile
+import time
+
+try:
+    import fcntl
+except ImportError:
+    system = platform.system()
+    raise EnvironmentError(f'xvfbwrapper is not supported on this platform: {system}')
+
+from random import randint
+
+
+class Xvfb:
+
+    # Maximum value to use for a display. 32-bit maxint is the
+    # highest Xvfb currently supports
+    MAX_DISPLAY = 2147483647
+
+    def __init__(
+        self,
+        width=800,
+        height=680,
+        colordepth=24,
+        tempdir=None,
+        display=None,
+        environ=None,
+        timeout=10,
+        **kwargs,
+    ):
+        self.width = width
+        self.height = height
+        self.colordepth = colordepth
+        self._tempdir = tempdir or tempfile.gettempdir()
+        self._timeout = timeout
+        self.new_display = display
+
+        if environ:
+            self.environ = environ
+        else:
+            self.environ = os.environ
+
+        if not self.xvfb_exists():
+            msg = 'Can not find Xvfb. Please install it and try again.'
+            raise EnvironmentError(msg)
+
+        self.xvfb_cmd = []
+        self.extra_xvfb_args = [
+            '-screen',
+            '0',
+            f'{self.width}x{self.height}x{self.colordepth}',
+        ]
+
+        for key, value in kwargs.items():
+            self.extra_xvfb_args += [f'-{key}', value]
+
+        if 'DISPLAY' in self.environ:
+            self.orig_display_var = self.environ['DISPLAY']
+        else:
+            self.orig_display_var = None
+
+        self.proc = None
+
+    def __enter__(self):
+        # type: (...) -> Xvfb
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.stop()
+
+    def start(self):
+        if self.new_display is not None:
+            if not self._get_lock_for_display(self.new_display):
+                raise ValueError(f'Could not lock display :{self.new_display}')
+        else:
+            self.new_display = self._get_next_unused_display()
+        display_var = f':{self.new_display}'
+        self.xvfb_cmd = ['Xvfb', display_var] + self.extra_xvfb_args
+        self.proc = subprocess.Popen(
+            self.xvfb_cmd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            close_fds=True,
+        )
+        start = time.time()
+        while not self._local_display_exists(self.new_display):
+            time.sleep(1e-3)
+            if time.time() - start > self._timeout:
+                self.stop()
+                raise RuntimeError(f'Xvfb display did not open: {self.xvfb_cmd}')
+        ret_code = self.proc.poll()
+        if ret_code is None:
+            self._set_display(display_var)
+        else:
+            self._cleanup_lock_file()
+            raise RuntimeError(f'Xvfb did not start ({ret_code}): {self.xvfb_cmd}')
+
+    def stop(self):
+        try:
+            if self.orig_display_var is None:
+                del self.environ['DISPLAY']
+            else:
+                self._set_display(self.orig_display_var)
+            if self.proc is not None:
+                try:
+                    self.proc.terminate()
+                    self.proc.wait(self._timeout)
+                except OSError:
+                    pass
+                self.proc = None
+        finally:
+            self._cleanup_lock_file()
+
+    def xvfb_exists(self):
+        # type: (...) -> bool
+        '''Check that Xvfb is available on PATH and is executable.'''
+        paths = self.environ['PATH'].split(os.pathsep)
+        return any(os.access(os.path.join(path, 'Xvfb'), os.X_OK) for path in paths)
+
+    def _cleanup_lock_file(self):
+        '''
+        This should always get called if the process exits safely
+        with Xvfb.stop() (whether called explicitly, or by __exit__).
+
+        If you are ending up with /tmp/X123-lock files when Xvfb is not
+        running, then Xvfb is not exiting cleanly. Always either call
+        Xvfb.stop() in a finally block, or use Xvfb as a context manager
+        to ensure lock files are purged.
+
+        '''
+        self._lock_display_file.close()
+        try:
+            os.remove(self._lock_display_file.name)
+        except OSError:
+            pass
+
+    def _get_lock_for_display(self, display):
+        # type: (...) -> bool
+        '''
+        In order to ensure multi-process safety, this method attempts
+        to acquire an exclusive lock on a temporary file whose name
+        contains the display number for Xvfb.
+        '''
+        tempfile_path = os.path.join(self._tempdir, f'.X{display}-lock')
+        try:
+            self._lock_display_file = open(tempfile_path, 'w')
+        except PermissionError:
+            return False
+        else:
+            try:
+                fcntl.flock(self._lock_display_file, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError:
+                return False
+            else:
+                return True
+
+    def _get_next_unused_display(self):
+        # type: (...) -> int
+        '''
+        Randomly chooses a display number and tries to acquire a lock for this
+        number. If the lock could be acquired, returns this number, otherwise
+        choses a new one.
+        :return: free display number
+        '''
+        while True:
+            rand = randint(1, self.__class__.MAX_DISPLAY)
+            if self._get_lock_for_display(rand):
+                return rand
+            else:
+                continue
+
+    def _local_display_exists(self, display):
+        temp_display_file = os.path.join(self._tempdir, '.X11-unix', f'X{display}')
+        return os.path.exists(temp_display_file)
+
+    def _set_display(self, display_var):
+        self.environ['DISPLAY'] = display_var