sphinxcontrib-screenshot 0.1.3__py3-none-any.whl → 0.2.0__py3-none-any.whl

sphinxcontrib/screenshot.py

@@ -13,17 +13,25 @@
 # limitations under the License.
 
 import hashlib
+import importlib
+import importlib.metadata
 import os
+import threading
 import typing
+import wsgiref.simple_server
 from concurrent.futures import ThreadPoolExecutor
 from urllib.parse import urlparse
 
 from docutils import nodes
 from docutils.parsers.rst import directives
-from docutils.statemachine import ViewList
+from docutils.parsers.rst.directives.images import Figure
+from playwright._impl._helper import ColorScheme
+from playwright.sync_api import Browser, BrowserContext
 from playwright.sync_api import TimeoutError as PlaywrightTimeoutError
 from playwright.sync_api import sync_playwright
+from portpicker import pick_unused_port
 from sphinx.application import Sphinx
+from sphinx.config import Config
 from sphinx.util.docutils import SphinxDirective
 
 Meta = typing.TypedDict('Meta', {
@@ -32,10 +40,8 @@ Meta = typing.TypedDict('Meta', {
     'parallel_write_safe': bool
 })
 
-__version__ = '0.1.3'
 
-
-class ScreenshotDirective(SphinxDirective):
+class ScreenshotDirective(SphinxDirective, Figure):
   """Sphinx Screenshot Dirctive.
 
   This directive embeds a screenshot of a webpage.
@@ -48,20 +54,13 @@ class ScreenshotDirective(SphinxDirective):
   .. screenshot:: http://www.example.com
   ```
 
-  You can also specify the screen size for the screenshot with `width` and
-  `height` parameters in pixel.
-
-  ```rst
-  .. screenshot:: http://www.example.com
-    :width: 1280
-    :height: 960
-  ```
-
-  You can include a caption for the screenshot's `figure` directive.
+  You can also specify the screen size for the screenshot with
+  `viewport-width` and `viewport-height` parameters in pixel.
 
   ```rst
   .. screenshot:: http://www.example.com
-    :caption: This is a screenshot for www.example.com
+    :viewport-width: 1280
+    :viewport-height: 960
   ```
 
   You can describe the interaction that you want to have with the webpage
@@ -73,13 +72,6 @@ class ScreenshotDirective(SphinxDirective):
     document.querySelector('button').click();
   ```
 
-  Use `figclass` option if you want to specify a class name to the image.
-
-  ```rst
-  .. screenshot:: http://www.example.com
-    :figclass: foo
-  ```
-
   It also generates a PDF file when `pdf` option is given, which might be
   useful when you need scalable image assets.
 
@@ -90,25 +82,34 @@ class ScreenshotDirective(SphinxDirective):
   """
 
   required_arguments = 1  # URL
-  has_content = True
   option_spec = {
-      'height': directives.positive_int,
-      'width': directives.positive_int,
-      'caption': directives.unchanged,
-      'figclass': directives.unchanged,
+      **Figure.option_spec,
+      'browser': str,
+      'viewport-height': directives.positive_int,
+      'viewport-width': directives.positive_int,
+      'interactions': str,
       'pdf': directives.flag,
+      'color-scheme': str,
+      'full-page': directives.flag,
+      'context': str,
+      'headers': directives.unchanged,
   }
   pool = ThreadPoolExecutor()
 
   @staticmethod
-  def take_screenshot(url: str, width: int, height: int, filepath: str,
-                      init_script: str, interactions: str, generate_pdf: bool):
+  def take_screenshot(
+      url: str, browser_name: str, viewport_width: int, viewport_height: int,
+      filepath: str, init_script: str, interactions: str, generate_pdf: bool,
+      color_scheme: ColorScheme, full_page: bool,
+      context_builder: typing.Optional[typing.Callable[[Browser, str, str],
+                                                       BrowserContext]],
+      headers: dict):
     """Takes a screenshot with Playwright's Chromium browser.
 
     Args:
       url (str): The HTTP/HTTPS URL of the webpage to screenshot.
-      width (int): The width of the screenshot in pixels.
-      height (int): The height of the screenshot in pixels.
+      viewport_width (int): The width of the screenshot in pixels.
+      viewport_height (int): The height of the screenshot in pixels.
       filepath (str): The path to save the screenshot to.
       init_script (str): JavaScript code to be evaluated after the document
         was created but before any of its scripts were run. See more details at
@@ -116,15 +117,33 @@ class ScreenshotDirective(SphinxDirective):
       interactions (str): JavaScript code to run before taking the screenshot
         after the page was loaded.
       generate_pdf (bool): Generate a PDF file along with the screenshot.
+      color_scheme (str): The preferred color scheme. Can be 'light' or 'dark'.
+      context: A method to build the Playwright context.
     """
     with sync_playwright() as playwright:
-      browser = playwright.chromium.launch()
-      page = browser.new_page()
+      browser = getattr(playwright, browser_name).launch()
+
+      if context_builder:
+        try:
+          context = context_builder(browser, url, color_scheme)
+        except PlaywrightTimeoutError:
+          raise RuntimeError(
+              'Timeout error occured at %s in executing py init script %s' %
+              (url, context_builder.__name__))
+      else:
+        context = browser.new_context(color_scheme=color_scheme)
+
+      page = context.new_page()
       page.set_default_timeout(10000)
-      page.set_viewport_size({'width': width, 'height': height})
+      page.set_viewport_size({
+          'width': viewport_width,
+          'height': viewport_height
+      })
+
       try:
         if init_script:
           page.add_init_script(init_script)
+        page.set_extra_http_headers(headers)
         page.goto(url)
         page.wait_for_load_state('networkidle')
 
@@ -135,15 +154,24 @@ class ScreenshotDirective(SphinxDirective):
       except PlaywrightTimeoutError:
         raise RuntimeError('Timeout error occured at %s in executing\n%s' %
                            (url, interactions))
-      page.screenshot(path=filepath)
+      page.screenshot(path=filepath, full_page=full_page)
       if generate_pdf:
         page.emulate_media(media='screen')
         root, ext = os.path.splitext(filepath)
-        page.pdf(width=f'{width}px', height=f'{height}px', path=root + '.pdf')
+        page.pdf(
+            width=f'{viewport_width}px',
+            height=f'{viewport_height}px',
+            path=root + '.pdf')
       page.close()
       browser.close()
 
-  def run(self) -> typing.List[nodes.Node]:
+  def evaluate_substitutions(self, text: str) -> str:
+    substitutions = self.state.document.substitution_defs
+    for key, value in substitutions.items():
+      text = text.replace(f"|{key}|", value.astext())
+    return text
+
+  def run(self) -> typing.Sequence[nodes.Node]:
     screenshot_init_script: str = self.env.config.screenshot_init_script or ''
 
     # Ensure the screenshots directory exists
@@ -151,55 +179,147 @@ class ScreenshotDirective(SphinxDirective):
     os.makedirs(ss_dirpath, exist_ok=True)
 
     # Parse parameters
-    url = self.arguments[0]
-    height = self.options.get('height', 960)
-    width = self.options.get('width', 1280)
-    caption_text = self.options.get('caption', '')
-    figclass = self.options.get('figclass', '')
+    raw_url = self.arguments[0]
+    url = self.evaluate_substitutions(raw_url)
+    interactions = self.options.get('interactions', '')
+    browser = self.options.get('browser',
+                               self.env.config.screenshot_default_browser)
+    viewport_height = self.options.get(
+        'viewport-height', self.env.config.screenshot_default_viewport_height)
+    viewport_width = self.options.get(
+        'viewport-width', self.env.config.screenshot_default_viewport_width)
+    color_scheme = self.options.get(
+        'color-scheme', self.env.config.screenshot_default_color_scheme)
     pdf = 'pdf' in self.options
-    interactions = '\n'.join(self.content)
+    full_page = ('full-page' in self.options or
+                 self.env.config.screenshot_default_full_page)
+    context = self.options.get('context', '')
+    headers = self.options.get('headers', '')
+
+    request_headers = {**self.env.config.screenshot_default_headers}
+    if headers:
+      for header in headers.strip().split("\n"):
+        name, value = header.split(" ", 1)
+        request_headers[name] = value
 
     if urlparse(url).scheme not in {'http', 'https'}:
       raise RuntimeError(
           f'Invalid URL: {url}. Only HTTP/HTTPS URLs are supported.')
 
     # Generate filename based on hash of parameters
-    hash_input = f'{url}_{height}_{width}_{interactions}'
+    hash_input = "_".join([
+        raw_url, browser,
+        str(viewport_height),
+        str(viewport_width), color_scheme, context, interactions,
+        str(full_page)
+    ])
     filename = hashlib.md5(hash_input.encode()).hexdigest() + '.png'
     filepath = os.path.join(ss_dirpath, filename)
 
+    if context:
+      context_builder_path = self.config.screenshot_contexts[context]
+      context_builder = resolve_python_method(context_builder_path)
+    else:
+      context_builder = None
+
     # Check if the file already exists. If not, take a screenshot
     if not os.path.exists(filepath):
-      fut = self.pool.submit(ScreenshotDirective.take_screenshot, url, width,
-                             height, filepath, screenshot_init_script,
-                             interactions, pdf)
+      fut = self.pool.submit(ScreenshotDirective.take_screenshot, url, browser,
+                             viewport_width, viewport_height, filepath,
+                             screenshot_init_script, interactions, pdf,
+                             color_scheme, full_page, context_builder,
+                             request_headers)
       fut.result()
 
     # Create image and figure nodes
     docdir = os.path.dirname(self.env.doc2path(self.env.docname))
     rel_ss_dirpath = os.path.relpath(ss_dirpath, start=docdir)
     rel_filepath = os.path.join(rel_ss_dirpath, filename).replace(os.sep, '/')
-    image_node = nodes.image(uri=rel_filepath)
-    figure_node = nodes.figure('', image_node)
 
-    if figclass:
-      figure_node['classes'].append(figclass)
+    self.arguments[0] = rel_filepath
+    return super().run()
+
+
+app_threads = {}
+
+
+def resolve_python_method(import_path: str):
+  module_path, method_name = import_path.split(":")
+  module = importlib.import_module(module_path)
+  method = getattr(module, method_name)
+  return method
+
+
+def setup_apps(app: Sphinx, config: Config):
+  """Start the WSGI application threads.
+
+    A new replacement is created for each WSGI app."""
+  for wsgi_app_name, wsgi_app_path in config.screenshot_apps.items():
+    port = pick_unused_port()
+    config.rst_prolog = (
+        config.rst_prolog or
+        "") + f"\n.. |{wsgi_app_name}| replace:: http://localhost:{port}\n"
+    app_builder = resolve_python_method(wsgi_app_path)
+    wsgi_app = app_builder(app)
+    httpd = wsgiref.simple_server.make_server("localhost", port, wsgi_app)
+    thread = threading.Thread(target=httpd.serve_forever)
+    thread.start()
+    app_threads[wsgi_app_name] = (httpd, thread)
 
-    if caption_text:
-      parsed = nodes.Element()
-      self.state.nested_parse(
-          ViewList([caption_text], source=''), self.content_offset, parsed)
-      figure_node += nodes.caption(parsed[0].source or '', '',
-                                   *parsed[0].children)
 
-    return [figure_node]
+def teardown_apps(app: Sphinx, exception: typing.Optional[Exception]):
+  """Shut down the WSGI application threads."""
+  for httpd, thread in app_threads.values():
+    httpd.shutdown()
+    thread.join()
 
 
 def setup(app: Sphinx) -> Meta:
   app.add_directive('screenshot', ScreenshotDirective)
   app.add_config_value('screenshot_init_script', '', 'env')
+  app.add_config_value(
+      'screenshot_default_viewport_width',
+      1280,
+      'env',
+      description="The default width for screenshots")
+  app.add_config_value(
+      'screenshot_default_viewport_height',
+      960,
+      'env',
+      description="The default height for screenshots")
+  app.add_config_value(
+      'screenshot_default_browser',
+      'chromium',
+      'env',
+      description="The default browser for screenshots")
+  app.add_config_value(
+      'screenshot_default_full_page',
+      False,
+      'env',
+      description="Whether to take full page screenshots")
+  app.add_config_value(
+      'screenshot_default_color_scheme',
+      'null',
+      'env',
+      description="The default color scheme for screenshots")
+  app.add_config_value(
+      'screenshot_contexts', {},
+      'env',
+      types=[dict[str, str]],
+      description="A dict of paths to Playwright context build methods")
+  app.add_config_value(
+      'screenshot_default_headers', {},
+      'env',
+      description="The default headers to pass in requests")
+  app.add_config_value(
+      'screenshot_apps', {},
+      'env',
+      types=[dict[str, str]],
+      description="A dict of WSGI apps")
+  app.connect('config-inited', setup_apps)
+  app.connect('build-finished', teardown_apps)
   return {
-      'version': __version__,
+      'version': importlib.metadata.version('sphinxcontrib-screenshot'),
       'parallel_read_safe': True,
       'parallel_write_safe': True,
   }

{sphinxcontrib_screenshot-0.1.3.dist-info → sphinxcontrib_screenshot-0.2.0.dist-info}/METADATA

@@ -1,103 +1,64 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: sphinxcontrib-screenshot
-Version: 0.1.3
-Summary: A Shpinx extension to embed webpage screenshots.
-Home-page: https://github.com/tushuhei/sphinxcontrib-screenshot/
-Author: Shuhei Iitsuka
-Author-email: tushuhei@gmail.com
+Version: 0.2.0
+Summary: A Sphinx extension to embed webpage screenshots.
+Author-email: Shuhei Iitsuka <tushuhei@gmail.com>
 License: Apache-2.0
+Project-URL: repository, https://github.com/tushuhei/sphinxcontrib-screenshot/
 Classifier: Development Status :: 3 - Alpha
 Classifier: Operating System :: OS Independent
 Classifier: License :: OSI Approved :: Apache Software License
 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
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: playwright
 Requires-Dist: sphinx
+Requires-Dist: portpicker
 Provides-Extra: dev
 Requires-Dist: beautifulsoup4; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: flake8; extra == "dev"
+Requires-Dist: flake8-pyproject; extra == "dev"
 Requires-Dist: isort; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: Pillow; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-regressions[image]; extra == "dev"
 Requires-Dist: sphinx[test]; extra == "dev"
 Requires-Dist: toml; extra == "dev"
+Requires-Dist: tox; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: types-beautifulsoup4; extra == "dev"
 Requires-Dist: types-docutils; extra == "dev"
+Requires-Dist: types-portpicker; extra == "dev"
 Requires-Dist: types-Pillow; extra == "dev"
 Requires-Dist: types-setuptools; extra == "dev"
+Requires-Dist: user-agents; extra == "dev"
 Requires-Dist: yapf; extra == "dev"
+Provides-Extra: doc
+Requires-Dist: myst-parser; extra == "doc"
+Requires-Dist: shibuya; extra == "doc"
+Requires-Dist: sphinx; extra == "doc"
 
 # sphinxcontrib-screenshot
 
 A Sphinx extension to embed website screenshots.
 
-![Example screenshot](https://raw.githubusercontent.com/tushuhei/sphinxcontrib-screenshot/main/example.png)
-
-## Install
-
-```bash
-pip install sphinxcontrib-screenshot
-playwright install
-```
-
-## Usage
-
-Add `sphinxcontrib.screenshot` to your `conf.py`.
-
-```py
-extensions = ["sphinxcontrib.screenshot"]
-```
-
-Then use the `screenshot` directive in your Sphinx source file.
-
-```rst
-.. screenshot:: http://www.example.com
-```
-
-You can also specify the screen size for the screenshot with `width` and `height` parameters.
-
-```rst
-.. screenshot:: http://www.example.com
-  :width: 1280
-  :height: 960
-```
-
-You can include a caption for the screenshot's `figure` directive.
-
 ```rst
 .. screenshot:: http://www.example.com
-  :caption: This is a screenshot for www.example.com
-```
-
-You can describe the interaction that you want to have with the webpage before taking a screenshot in JavaScript.
-
-```rst
-.. screenshot:: http://www.example.com
-
-  document.querySelector('button').click();
-```
-
-## Pro tips
-`sphinxcontrib-screenshot` supports URLs with the HTTP and HTTPS protocols.
-To take screenshots of local files and build the document while running a local server for them, you can use the NPM library [concurrently](https://www.npmjs.com/package/concurrently) in the following way:
-
-### Build the document
-```bash
-  npx --yes concurrently -k --success=first "make html" "python3 -m http.server 3000 --directory=examples"
-```
-
-### Watch and build the document
-```bash
-  npx --yes concurrently -k "make livehtml" "python3 -m http.server 3000 --directory=examples"
+  :browser: chromium
+  :viewport-width: 1280
+  :viewport-height: 960
+  :color-scheme: dark
 ```
 
+Read more in the [documentation](https://sphinxcontrib-screenshot.readthedocs.io).
 
 ## Notes
 

sphinxcontrib_screenshot-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+sphinxcontrib/screenshot.py,sha256=03cVsF1d9zuWMsVBwtZU_EQ_GMMsYyPa2a3vBmzC4f8,11342
+sphinxcontrib_screenshot-0.2.0.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+sphinxcontrib_screenshot-0.2.0.dist-info/METADATA,sha256=pwaSBQlzvflzW2BSv7ByJ8GvbwDrYF0xn8bftw3dPC0,2868
+sphinxcontrib_screenshot-0.2.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+sphinxcontrib_screenshot-0.2.0.dist-info/top_level.txt,sha256=VJrV3_vaiKQVgVpR0I1iecxoO0drzGu-M0j40PVP2QQ,14
+sphinxcontrib_screenshot-0.2.0.dist-info/RECORD,,

{sphinxcontrib_screenshot-0.1.3.dist-info → sphinxcontrib_screenshot-0.2.0.dist-info}/WHEEL

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

sphinxcontrib_screenshot-0.1.3.dist-info/RECORD

@@ -1,6 +0,0 @@
-sphinxcontrib/screenshot.py,sha256=rTcbf2bx5DiRIGKcA8dL7jbi-GwfrW7-aXU83M5vAlY,6829
-sphinxcontrib_screenshot-0.1.3.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-sphinxcontrib_screenshot-0.1.3.dist-info/METADATA,sha256=T6kkviJZwZe0ZtYllM4YwhlI9qiKtoTbnI6OAcxlvII,3652
-sphinxcontrib_screenshot-0.1.3.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-sphinxcontrib_screenshot-0.1.3.dist-info/top_level.txt,sha256=VJrV3_vaiKQVgVpR0I1iecxoO0drzGu-M0j40PVP2QQ,14
-sphinxcontrib_screenshot-0.1.3.dist-info/RECORD,,