clementine

API Reference

Table of Contents

clementine

env

Environment utilities.

clementine.env.ensure_is_available 

ensure_is_available(package, message=None)

Raises a ModuleNotFoundError if a package is not importable.

Parameters:

  • package (str) –

    The name of the package to verify.

  • message (Optional[str], default: None ) –

    The error message to display.

clementine.env.info 

info(packages=None)

Returns package installation and environment information.

Parameters:

  • packages (Optional[list[str]], default: None ) –

    The names of the packages whose metadata should be included.

clementine.env.is_available 

is_available(package)

Returns True if a package is installed or is a built-in.

Parameters:

  • package (str) –

    The name of the package to verify.

clementine.env.is_notebook 

is_notebook()

Returns True if the current environment is a Jupyter notebook.

importing

Importing utilities.

clementine.importing.MissingModulePlaceholder 

MissingModulePlaceholder(name, message=None)

A placeholder for a module that is not installed. This allows us to defer raising an error until the module is actually used.

Example usage:

from clementine import importing

try:
    import spacy
except ImportError:
    spacy = importing.MissingModulePlaceholder("spacy")

Parameters:

  • name (str) –

    The name of the package.

  • message (Optional[str], default: None ) –

    An error message.

clementine.importing.maybe_import_module 

maybe_import_module(name, message=None)

Tries to import a module by name and return it. If the module can't be imported, a placeholder object is returned instead.

Example usage:

from clementine import importing

spacy = importing.maybe_import_module("spacy")

Parameters:

  • name (str) –

    The name of the module to import.

  • message (Optional[str], default: None ) –

    An error message to pass to the placeholder object.

screenshot

Screenshot utilities.

clementine.screenshot.async_screenshot async 

async_screenshot(
    url, *, output_dir=None, filename=None, full_page=False, **kwargs
)

Asynchronously take screenshots of a webpage in light and dark mode.

clementine.screenshot.screenshot 

screenshot(url, *, output_dir=None, filename=None, full_page=False, **kwargs)

Take screenshots of a webpage in light and dark mode.

Use screenshot.async_screenshot() in asynchronous contexts, such as in a Jupyter notebook. Use screenshot.screenshot() in synchronous contexts, such as in a synchronous Python script.

Prerequisites:

  1. Install the Playwright Python package: pip install playwright.
  2. Install the Playwright browser dependencies: playwright install webkit.

Example usage in a Python script:

from clementine import screenshot

paths = screenshot.screenshot('https://example.com')

Example usage in a Jupyter notebook or other asynchronous context:

from clementine import screenshot
from IPython.display import display, Image

paths = await screenshot.async_screenshot('https://example.com')
for path in paths:
    display(Image(path, width=600))

Parameters:

  • url (str) –

    The URL to take screenshots of. The URL must include the scheme, e.g. https:// or file:///.

  • output_dir (Optional[str], default: None ) –

    The directory to save the screenshots to. Defaults to 'screenshots' in the current working directory.

  • filename (Optional[str], default: None ) –

    The base filename to use for the screenshots. Defaults to 'screenshot'. The screenshots will be saved as screenshot-light.png and screenshot-dark.png, for example.

  • full_page (bool, default: False ) –

    Whether to take a screenshot of the full page. Defaults to False.

  • **kwargs (Optional[dict[str, Any]], default: {} ) –

    Extra arguments to playwright.async_api.Page.screenshot. See playwright's documentation for all possible arguments: https://playwright.dev/docs/api/class-page#page-screenshot

Raises:

  • ImportError –

    If the Playwright Python package is not installed.

  • Error –

    If the browser cannot be launched or an invalid url is provided.

  • RuntimeError –

    If called in an asynchronous context.

Returns:

  • list[str] –

    A list of the paths to the screenshots.