playwright-limelight 0.2.0__py3-none-any.whl

limelight/__init__.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from limelight.application import Application, StaticApplication
+from limelight.barriers import (
+    requests_settled,
+    trigger_until_navigation,
+    trigger_until_response,
+    trigger_until_visible,
+)
+from limelight.components import (
+    ELEMENT_WAIT_TIMEOUT_MS,
+    Confirm,
+    Dropdown,
+    Modal,
+    Navigator,
+    SearchAndSelect,
+)
+from limelight.config import DemoConfig
+from limelight.demo import Demo
+from limelight.ledger import Direction, Ledger, LedgerRow, Sentiment
+from limelight.scene import Scene
+from limelight.theme import Theme
+from limelight.world import World
+
+__all__ = [
+    'ELEMENT_WAIT_TIMEOUT_MS',
+    'Application',
+    'Confirm',
+    'Demo',
+    'DemoConfig',
+    'Direction',
+    'Dropdown',
+    'Ledger',
+    'LedgerRow',
+    'Modal',
+    'Navigator',
+    'Scene',
+    'SearchAndSelect',
+    'Sentiment',
+    'StaticApplication',
+    'Theme',
+    'World',
+    'requests_settled',
+    'trigger_until_navigation',
+    'trigger_until_response',
+    'trigger_until_visible',
+]

limelight/application.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from playwright.sync_api import Page
+
+
+@runtime_checkable
+class Application(Protocol):
+    """
+    A protocol for the application a demo records.
+
+    This protocol covers the two things a demo needs from the project under
+    test: a way to sign a user in, and a way to turn a route into a URL.
+    """
+
+    def login(self, page: Page, user: object) -> None:
+        """
+        A method that signs a user into the application.
+
+        :param page: The page the demo drives.
+        :param user: The user to sign in as.
+        """
+
+        ...
+
+    def url(self, route: str, **url_kwargs: object) -> str:
+        """
+        A method that resolves a route into an absolute URL.
+
+        :param route: The route to resolve.
+        :param url_kwargs: The arguments filled into the route.
+        :return: The absolute URL to navigate to.
+        """
+
+        ...
+
+
+class StaticApplication:
+    """
+    An application backed by a fixed base URL.
+
+    This class serves any site that is already running, so a demo can record
+    against a deployed environment without a Django project behind it.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        login: Callable[[Page, object], None] | None = None,
+    ) -> None:
+        """
+        The constructor for the StaticApplication class.
+
+        :param base_url: The origin every route is resolved against.
+        :param login: The callable that signs a user in, or None for a site that needs no login.
+        :raises ValueError: If the base URL is empty.
+        """
+
+        base_url_clean = base_url.strip().rstrip('/')
+
+        if not base_url_clean:
+            message = f'base_url must not be empty (got "{base_url}")'
+            raise ValueError(message)
+
+        self.base_url = base_url_clean
+        self._login = login
+
+    def login(self, page: Page, user: object) -> None:
+        """
+        A method that signs a user in through the configured callable.
+
+        :param page: The page the demo drives.
+        :param user: The user to sign in as.
+        """
+
+        if self._login is not None:
+            self._login(page, user)
+
+    def url(self, route: str, **url_kwargs: object) -> str:
+        """
+        A method that joins a route onto the base URL.
+
+        :param route: The route to resolve, with or without a leading slash.
+        :param url_kwargs: The arguments filled into the route.
+        :return: The absolute URL to navigate to.
+        :raises ValueError: If the route is empty.
+        """
+
+        if not route.strip():
+            message = f'route must not be empty (got "{route}")'
+            raise ValueError(message)
+
+        path = route.format(**url_kwargs)
+
+        if not path.startswith('/'):
+            path = f'/{path}'
+
+        return f'{self.base_url}{path}'

limelight/artifacts.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+
+DIRECTORY_ROOT = '.demos'
+
+CHAPTERS_FILE_NAME = 'chapters.txt'
+GIF_FILE_NAME = 'video.gif'
+RENDER_FILE_NAME = 'render.mp4'
+SUBTITLES_FILE_NAME = 'subtitles.vtt'
+TRANSCRIPT_FILE_NAME = 'transcript.json'
+VIDEO_FILE_NAME = 'video.mp4'
+VOICEOVER_FILE_NAME = 'voiceover.wav'
+WALKTHROUGH_FILE_NAME = 'walkthrough.md'

limelight/barriers.py

@@ -0,0 +1,364 @@
+from __future__ import annotations
+
+import time
+
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+from playwright.sync_api import TimeoutError as PlaywrightTimeoutError, expect
+
+if TYPE_CHECKING:
+    import re
+
+    from collections.abc import Callable, Iterator
+    from playwright.sync_api import Locator, Page, Request, Response
+
+
+ATTEMPT_COUNT_DEFAULT = 3
+BARRIER_TIMEOUT_MS_DEFAULT = 5000
+SETTLE_INTERVAL_MS_DEFAULT = 100
+SETTLE_TIMEOUT_MS_DEFAULT = 15_000
+WAIT_ATTEMPT_COUNT_MAX = 40
+WAIT_INTERVAL_MS_DEFAULT = 250
+
+
+class _RequestTally:
+    """
+    A running count of the requests a URL fragment names.
+
+    The count rises when such a request starts and falls when it finishes or
+    fails, so a block that fires several requests is settled only once the last
+    of them is answered.
+    """
+
+    def __init__(self, url_fragment: str) -> None:
+        """
+        The constructor for the _RequestTally class.
+
+        :param url_fragment: The text a tallied request URL contains.
+        """
+
+        self.count = 0
+        self.url_fragment = url_fragment
+
+    @property
+    def is_quiet(self) -> bool:
+        """
+        A property that reports whether every tallied request has been answered.
+
+        :return: True if nothing is in flight, False otherwise.
+        """
+
+        return self.count <= 0
+
+    def settled(self, request: Request) -> None:
+        """
+        A method that drops a request from the tally.
+
+        :param request: The request that finished or failed.
+        """
+
+        if self.url_fragment in request.url:
+            self.count -= 1
+
+    def started(self, request: Request) -> None:
+        """
+        A method that adds a request to the tally.
+
+        :param request: The request that started.
+        """
+
+        if self.url_fragment in request.url:
+            self.count += 1
+
+
+def _attempt_count_validate(attempt_count: int) -> None:
+    """
+    A function that rejects an attempt count below one.
+
+    :param attempt_count: The number of times a barrier retries its trigger.
+    :raises ValueError: If the attempt count is not positive.
+    """
+
+    if attempt_count < 1:
+        message = f'attempt_count must be positive: {attempt_count}'
+        raise ValueError(message)
+
+
+def _method_predicate(method: str) -> Callable[[Response], bool]:
+    """
+    A function that builds a response predicate from an HTTP method.
+
+    :param method: The method the request behind the response was made with.
+    :return: The predicate that matches such a response.
+    """
+
+    wanted = method.upper()
+
+    def matches(response: Response) -> bool:
+        """
+        A function that reports whether a response answers that method.
+
+        :param response: The response to test.
+        :return: True if the request used the method, False otherwise.
+        """
+
+        return response.request.method.upper() == wanted
+
+    return matches
+
+
+def _url_fragment_predicate(url_fragment: str) -> Callable[[Response], bool]:
+    """
+    A function that builds a response predicate from a substring of a URL.
+
+    :param url_fragment: The text the response URL must contain.
+    :return: The predicate that matches such a response.
+    """
+
+    def matches(response: Response) -> bool:
+        """
+        A function that reports whether a response URL carries the fragment.
+
+        :param response: The response to test.
+        :return: True if the URL contains the fragment, False otherwise.
+        """
+
+        return url_fragment in response.url
+
+    return matches
+
+
+@contextmanager
+def requests_settled(
+    page: Page,
+    *,
+    url_fragment: str,
+    timeout_ms: int = SETTLE_TIMEOUT_MS_DEFAULT,
+    interval_ms: int = SETTLE_INTERVAL_MS_DEFAULT,
+) -> Iterator[None]:
+    """
+    A context manager that holds the block open until its background requests finish.
+
+    The requests a fragment names are tallied while the block runs, and the exit
+    waits for the tally to fall back to zero. A page that answers a click with a
+    request rather than a navigation settles on the request itself this way,
+    rather than on a fixed sleep or on network silence the page never reaches.
+
+    :param page: The page whose requests are tallied.
+    :param url_fragment: The text a tallied request URL contains.
+    :param timeout_ms: The time the exit waits for the tally to clear.
+    :param interval_ms: The time waited between reads of the tally.
+    :raises ValueError: If the fragment is empty, or a duration is not positive.
+    :raises AssertionError: If the requests never finish.
+    """
+
+    if not url_fragment.strip():
+        message = f'url_fragment must not be empty (got "{url_fragment}")'
+        raise ValueError(message)
+
+    if timeout_ms < 1:
+        message = f'timeout_ms must be positive: {timeout_ms}'
+        raise ValueError(message)
+
+    if interval_ms < 1:
+        message = f'interval_ms must be positive: {interval_ms}'
+        raise ValueError(message)
+
+    pending = _RequestTally(url_fragment)
+
+    page.on('request', pending.started)
+    page.on('requestfinished', pending.settled)
+    page.on('requestfailed', pending.settled)
+
+    try:
+        yield
+
+        deadline = time.monotonic() + timeout_ms / 1000
+
+        while not pending.is_quiet:
+            if time.monotonic() >= deadline:
+                message = (
+                    f'the requests to "{url_fragment}" never settled '
+                    f'within {timeout_ms}ms'
+                )
+
+                raise AssertionError(message)
+
+            page.wait_for_timeout(interval_ms)
+    finally:
+        page.remove_listener('request', pending.started)
+        page.remove_listener('requestfinished', pending.settled)
+        page.remove_listener('requestfailed', pending.settled)
+
+
+def trigger_until_navigation(
+    page: Page,
+    trigger: Callable[[], None],
+    *,
+    url_pattern: str | re.Pattern[str] | None = None,
+    attempt_count: int = ATTEMPT_COUNT_DEFAULT,
+    timeout_ms: int = BARRIER_TIMEOUT_MS_DEFAULT,
+) -> None:
+    """
+    A function that repeats a trigger until the page navigates.
+
+    The trigger is retried because a click can land before the handler that
+    listens for it is bound, and a lost click leaves the page where it was with
+    no error to catch. The final attempt re-raises, so a page that never
+    navigates fails rather than passing silently.
+
+    :param page: The page expected to navigate.
+    :param trigger: The action that causes the navigation.
+    :param url_pattern: The URL the navigation must match, or None for any.
+    :param attempt_count: The number of times the trigger is retried.
+    :param timeout_ms: The time each attempt waits for the navigation.
+    :raises ValueError: If the attempt count is not positive.
+    :raises PlaywrightTimeoutError: If the last attempt sees no navigation.
+    """
+
+    _attempt_count_validate(attempt_count)
+
+    for attempt in range(attempt_count):
+        try:
+            with page.expect_navigation(url=url_pattern, timeout=timeout_ms):
+                trigger()
+        except PlaywrightTimeoutError:
+            if attempt == attempt_count - 1:
+                raise
+        else:
+            return
+
+
+def trigger_until_response(
+    page: Page,
+    trigger: Callable[[], None],
+    *,
+    url_fragment: str = '',
+    method: str = '',
+    predicate: Callable[[Response], bool] | None = None,
+    attempt_count: int = ATTEMPT_COUNT_DEFAULT,
+    timeout_ms: int = BARRIER_TIMEOUT_MS_DEFAULT,
+) -> None:
+    """
+    A function that repeats a trigger until a matching response arrives.
+
+    The response is matched by a substring of its URL, by the method its request
+    was made with, or by a predicate, exactly one at a time, so no two matchers
+    can disagree about which response ends the wait.
+
+    :param page: The page expected to receive the response.
+    :param trigger: The action that causes the request.
+    :param url_fragment: The text the response URL must contain.
+    :param method: The HTTP method the request behind the response was made with.
+    :param predicate: The test a response must pass.
+    :param attempt_count: The number of times the trigger is retried.
+    :param timeout_ms: The time each attempt waits for the response.
+    :raises ValueError: If the attempt count is not positive, or if the matchers are
+        not given exactly one at a time.
+    :raises PlaywrightTimeoutError: If the last attempt sees no matching response.
+    """
+
+    _attempt_count_validate(attempt_count)
+
+    matcher_count = sum((bool(url_fragment), bool(method), predicate is not None))
+
+    if matcher_count != 1:
+        message = (
+            'trigger_until_response takes exactly one of url_fragment, method and predicate'
+        )
+
+        raise ValueError(message)
+
+    if predicate is not None:
+        matches = predicate
+    elif method:
+        matches = _method_predicate(method)
+    else:
+        matches = _url_fragment_predicate(url_fragment)
+
+    for attempt in range(attempt_count):
+        try:
+            with page.expect_response(matches, timeout=timeout_ms):
+                trigger()
+        except PlaywrightTimeoutError:
+            if attempt == attempt_count - 1:
+                raise
+        else:
+            return
+
+
+def trigger_until_visible(
+    trigger: Callable[[], None],
+    locator: Locator,
+    *,
+    attempt_count: int = ATTEMPT_COUNT_DEFAULT,
+    timeout_ms: int = BARRIER_TIMEOUT_MS_DEFAULT,
+) -> None:
+    """
+    A function that repeats a trigger until an element becomes visible.
+
+    :param trigger: The action that reveals the element.
+    :param locator: The locator for the element that must appear.
+    :param attempt_count: The number of times the trigger is retried.
+    :param timeout_ms: The time each attempt waits for the element.
+    :raises ValueError: If the attempt count is not positive.
+    :raises AssertionError: If the element is still hidden after the last attempt.
+    """
+
+    _attempt_count_validate(attempt_count)
+
+    for attempt in range(attempt_count):
+        trigger()
+
+        try:
+            expect(locator).to_be_visible(timeout=timeout_ms)
+        except AssertionError:
+            if attempt == attempt_count - 1:
+                raise
+        else:
+            return
+
+
+def wait_until(
+    predicate: Callable[[], bool],
+    hold: Callable[[int], None],
+    *,
+    attempt_count_max: int = WAIT_ATTEMPT_COUNT_MAX,
+    description: str = '',
+    interval_ms: int = WAIT_INTERVAL_MS_DEFAULT,
+) -> None:
+    """
+    A function that polls a condition until it holds or the attempts run out.
+
+    The wait is handed a hold callable rather than sleeping itself, so a demo
+    that drives the clock can advance its own timeline between polls instead of
+    burning real seconds.
+
+    :param predicate: The condition polled between holds.
+    :param hold: The callable that waits for the given number of milliseconds.
+    :param attempt_count_max: The number of times the condition is polled.
+    :param description: What the condition is waiting for, named in the failure.
+    :param interval_ms: The time held between polls.
+    :raises ValueError: If the attempt count or the interval is not positive.
+    :raises AssertionError: If the condition never holds.
+    """
+
+    if attempt_count_max < 1:
+        message = f'attempt_count_max must be positive: {attempt_count_max}'
+        raise ValueError(message)
+
+    if interval_ms < 1:
+        message = f'interval_ms must be positive: {interval_ms}'
+        raise ValueError(message)
+
+    for _ in range(attempt_count_max):
+        if predicate():
+            return
+
+        hold(interval_ms)
+
+    subject = description or 'condition'
+
+    message = f'{subject} did not hold after {attempt_count_max * interval_ms}ms'
+    raise AssertionError(message)

limelight/capture/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

limelight/capture/browser.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import socket
+
+from urllib.parse import urlsplit
+
+
+ENDPOINT_HOST = '127.0.0.1'
+
+LAUNCH_ARGUMENTS_FRAME_CONTROL = (
+    '--disable-checker-imaging',
+    '--disable-image-animation-resync',
+    '--disable-threaded-animation',
+    '--disable-threaded-scrolling',
+    '--enable-begin-frame-control',
+    '--hide-scrollbars',
+    '--run-all-compositor-stages-before-draw',
+)
+
+
+def endpoint_free() -> str:
+    """
+    A function that reserves a free local port for the debugging endpoint.
+
+    The socket is bound and closed rather than held, so the port is only known
+    to be free at the moment it is picked: Chrome has to be launched onto it
+    before something else takes it.
+
+    :return: The URL of the debugging endpoint.
+    """
+
+    with socket.socket() as listener:
+        listener.bind((ENDPOINT_HOST, 0))
+
+        port = listener.getsockname()[1]
+
+    return f'http://{ENDPOINT_HOST}:{port}'
+
+
+def endpoint_port(endpoint: str) -> int:
+    """
+    A function that reads the port out of a debugging endpoint URL.
+
+    :param endpoint: The URL of the debugging endpoint.
+    :return: The port the endpoint listens on.
+    :raises ValueError: If the endpoint carries no port.
+    """
+
+    port = urlsplit(endpoint).port
+
+    if port is None:
+        message = f'the endpoint carries no port: {endpoint}'
+        raise ValueError(message)
+
+    return port
+
+
+def launch_arguments_frame_control(endpoint: str, *, device_scale_factor: int = 1) -> list[str]:
+    """
+    A function that builds the Chrome arguments for frame-by-frame capture.
+
+    The switches hand the compositor to the driver: animation and scrolling are
+    pulled off their own threads, every compositor stage runs before a draw, and
+    begin-frame control lets the renderer produce one frame per request rather
+    than on a wall clock, so a slow screenshot cannot skew the timeline.
+
+    :param endpoint: The URL of the debugging endpoint Chrome listens on.
+    :param device_scale_factor: The pixel ratio the page is rendered at.
+    :return: The command-line arguments to launch Chrome with.
+    :raises ValueError: If the device scale factor is not positive.
+    """
+
+    if device_scale_factor < 1:
+        message = f'device_scale_factor must be positive: {device_scale_factor}'
+        raise ValueError(message)
+
+    return [
+        *LAUNCH_ARGUMENTS_FRAME_CONTROL,
+        f'--force-device-scale-factor={device_scale_factor}',
+        f'--remote-debugging-port={endpoint_port(endpoint)}',
+    ]

limelight/capture/camera.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import re
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from playwright.sync_api import Page
+
+
+SCREENSHOT_NAME_INVALID_PATTERN = re.compile(r'[^A-Za-z0-9._-]+')
+
+
+class Camera:
+    """
+    A screenshot recorder for a demo run.
+
+    This class numbers each screenshot as it is taken, so the files sort in the
+    order the demo produced them rather than by name.
+    """
+
+    def __init__(self, page: Page, directory: Path) -> None:
+        """
+        The constructor for the Camera class.
+
+        :param page: The page the screenshots are taken from.
+        :param directory: The directory the screenshots are written to.
+        :raises ValueError: If the directory is empty or the current directory.
+        """
+
+        directory_text = str(directory).strip()
+
+        if directory_text in ('', '.'):
+            message = f'directory must be a real path (got "{directory}")'
+            raise ValueError(message)
+
+        self._directory = directory
+        self._page = page
+        self._sequence = 0
+
+    def screenshot(self, name: str) -> Path:
+        """
+        A method that captures the current page to a numbered PNG file.
+
+        :param name: The label for the shot, with unusable characters replaced by a dash.
+        :return: The path the screenshot was written to.
+        :raises ValueError: If the name carries no characters usable in a file name.
+        """
+
+        name_clean = SCREENSHOT_NAME_INVALID_PATTERN.sub('-', name).strip('-.')
+
+        if not name_clean:
+            message = f'screenshot name carries no filename characters: "{name}"'
+            raise ValueError(message)
+
+        self._sequence += 1
+
+        path = self._directory / f'{self._sequence:02d}-{name_clean}.png'
+
+        self._directory.mkdir(parents=True, exist_ok=True)
+        self._page.screenshot(path=str(path))
+
+        return path
+
+    def switch_page(self, page: Page) -> None:
+        """
+        A method that points the camera at a different page.
+
+        :param page: The page later screenshots are taken from.
+        """
+
+        self._page = page