mplbed 0.1.0__tar.gz

mplbed-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.3
+Name: mplbed
+Version: 0.1.0
+Summary: Integrate Matplotlib's WebAgg backend with Starlette for real-time plotting in web applications.
+Requires-Dist: frozendict>=2.4.7
+Requires-Dist: matplotlib>=3.10.9
+Requires-Dist: starlette>=1.0.0
+Requires-Dist: tornado>=6.5.5
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# mplbed
+
+```
+|[]mpl
+|======|
+|  bed |
+```
+
+`mplbed` is a library of support code for embedding interactive, server-side matplotlib figures in web applications.
+
+Supporting, in principle any ASGI-compatible Python application, it provides convenient integration for a number of frameworks ones out of the box.
+It aims to have "usually-works" defaults useful for quick demos, while providing a lot of flexibility and options as well as utilities to deal with advanced issues such as style isolation, and connection and resource management to enable some degree of scaling up to use-cases like internal dashboards.
+
+It can be as easy as:
+
+```python
+import mywebframework
+from mplbed import mplbed_mywebframework
+
+@mywebframework.route("/myplot")
+@mplbed_mywebframework.figure_page
+def my_plot_page(request):
+    fig, ax = plt.subplots()
+    ax.plot([1, 2, 3], [4, 5, 6])
+    return fig
+
+app = mywebframework.App(...)
+setup(app)
+```
+
+## Installation
+
+Currently you can install this package from Github:
+
+    $ uv add git+https://github.com/frankier/mplbed
+
+## Documentation
+
+The documentation includes [API docs](https://frankier.github.io/mplbed/api.html) and [examples](https://frankier.github.io/mplbed/examples.html).
+
+## Contributing
+
+Contributions are welcome. Please discuss any larger changes in the issues
+before making a pull request to avoid wasted work. You, the human contributor,
+must personally have reviewed and understood any code submitted.
+
+Set up a dev environment with [uv](https://docs.astral.sh/uv/):
+
+    $ uv sync --all-groups --all-extras
+
+Run the tests (end-to-end tests need Playwright browsers: `uv run playwright install chromium`):
+
+    $ uv run pytest
+
+Lint, format and typecheck:
+
+    $ uv run ruff check ./src
+    $ uv run ruff format ./src
+    $ uv run ty check ./src
+
+Install the [prek](https://prek.j178.dev/) hook to run these automatically on commit:
+
+    $ prek install

mplbed-0.1.0/README.md

@@ -0,0 +1,63 @@
+# mplbed
+
+```
+|[]mpl
+|======|
+|  bed |
+```
+
+`mplbed` is a library of support code for embedding interactive, server-side matplotlib figures in web applications.
+
+Supporting, in principle any ASGI-compatible Python application, it provides convenient integration for a number of frameworks ones out of the box.
+It aims to have "usually-works" defaults useful for quick demos, while providing a lot of flexibility and options as well as utilities to deal with advanced issues such as style isolation, and connection and resource management to enable some degree of scaling up to use-cases like internal dashboards.
+
+It can be as easy as:
+
+```python
+import mywebframework
+from mplbed import mplbed_mywebframework
+
+@mywebframework.route("/myplot")
+@mplbed_mywebframework.figure_page
+def my_plot_page(request):
+    fig, ax = plt.subplots()
+    ax.plot([1, 2, 3], [4, 5, 6])
+    return fig
+
+app = mywebframework.App(...)
+setup(app)
+```
+
+## Installation
+
+Currently you can install this package from Github:
+
+    $ uv add git+https://github.com/frankier/mplbed
+
+## Documentation
+
+The documentation includes [API docs](https://frankier.github.io/mplbed/api.html) and [examples](https://frankier.github.io/mplbed/examples.html).
+
+## Contributing
+
+Contributions are welcome. Please discuss any larger changes in the issues
+before making a pull request to avoid wasted work. You, the human contributor,
+must personally have reviewed and understood any code submitted.
+
+Set up a dev environment with [uv](https://docs.astral.sh/uv/):
+
+    $ uv sync --all-groups --all-extras
+
+Run the tests (end-to-end tests need Playwright browsers: `uv run playwright install chromium`):
+
+    $ uv run pytest
+
+Lint, format and typecheck:
+
+    $ uv run ruff check ./src
+    $ uv run ruff format ./src
+    $ uv run ty check ./src
+
+Install the [prek](https://prek.j178.dev/) hook to run these automatically on commit:
+
+    $ prek install

mplbed-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "mplbed"
+version = "0.1.0"
+description = "Integrate Matplotlib's WebAgg backend with Starlette for real-time plotting in web applications."
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "frozendict>=2.4.7",
+    "matplotlib>=3.10.9",
+    "starlette>=1.0.0",
+    "tornado>=6.5.5",
+]
+
+[dependency-groups]
+demo = [
+  "mne>=1.12.1",
+  "quart",
+  "django",
+  "daphne",
+  "questionary"
+]
+docs = [
+    "sphinx>=8",
+    "myst-parser>=4",
+    "sphinx-autodoc-typehints>=2",
+    "furo>=2024",
+    "quart",
+]
+test = [
+    "pytest>=8",
+    "pytest-playwright>=0.5",
+    "pillow>=10",
+]
+qa = [
+    "ty",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "e2e: end-to-end Playwright tests that drive a real browser",
+]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+    # pyupgrade
+    "UP",
+    # pydocstyle
+    "D",
+]
+
+ignore = [
+    # Package/module-level docstrings
+    "D100",
+    "D104",
+    # Summary line seprate from body
+    "D205"
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+ignore-decorators = ["mplbed._doc_helpers.doc", "mplbed.integration._common.setup_page_docstring"]
+
+[build-system]
+requires = ["uv_build >= 0.11.7, <0.12.0"]
+build-backend = "uv_build"

mplbed-0.1.0/src/mplbed/__init__.py

@@ -0,0 +1,15 @@
+from .asgi import MplbedMiddleware
+from .html import raw as raw_html
+from .html import safe as safe_html
+from .integration import quart as mplbed_quart
+from .integration import starlette as mplbed_starlette
+from .server import mplbed_app_factory
+
+__all__ = [
+    "mplbed_quart",
+    "mplbed_starlette",
+    "mplbed_app_factory",
+    "raw_html",
+    "safe_html",
+    "MplbedMiddleware",
+]

mplbed-0.1.0/src/mplbed/_doc_helpers.py

@@ -0,0 +1,52 @@
+from typing import Any
+
+from .consts import DEFAULT_PREFIX
+
+
+def doc(s):
+    def decorator(func):
+        func.__doc__ = s
+        return func
+
+    return decorator
+
+
+def fdf(s):
+    """_F_ix _D_ocstring _F_ragment for inclusion in a docstring template."""
+    from inspect import cleandoc
+    from textwrap import indent
+
+    return indent(cleandoc(s), "    ").strip()
+
+
+class DotAccessDict(dict[str, Any]):
+    __getattr__ = dict.get
+
+
+PARAMS_DS: Any = DotAccessDict(
+    prefix=fdf(f"""
+    prefix : str, optional
+        The URL prefix for the routes handleded by `mplbed`. Default is '{DEFAULT_PREFIX}'.
+    """),
+    mplbed_starlette_app=lambda name="mplbed_starlette_app": fdf(f"""
+    {name} : Starlette, optional
+        The Starlette app to use for the `mplbed` routes, as returned by `mplbed_starlette_app_factory`.
+        If not provided, a new app will be created using the provided `mplbed_starlette_app_kwargs`.
+    """),
+    mplbed_starlette_app_kwargs=lambda name="mplbed_starlette_app_kwargs": fdf(f"""
+    {name} : dict, optional
+        Keyword arguments to pass to the Mplbed app factory if `mplbed_starlette_app` is not provided.
+    """),
+    manage_routing=fdf("""
+    manage_routing : bool, optional
+        Whether the ASGI middleware should manage routing. Default is True.
+        If you set this to False, you are responsible for routing requests to
+        the Mplbed app under the given `prefix`.
+    """),
+    native_app=fdf("""
+    native_app : Any, optional
+        The native app, e.g. the `Starlette` or `Quart` instance, which will
+        typically be saved in cased it is needed by the specific integration,
+        e.g. for rendering templates.
+    """),
+)

mplbed-0.1.0/src/mplbed/asgi.py

@@ -0,0 +1,121 @@
+from contextvars import ContextVar
+from typing import Any
+
+from starlette.applications import Starlette
+from starlette.routing import Match, Mount
+
+from mplbed._doc_helpers import PARAMS_DS as D
+from mplbed._doc_helpers import doc
+
+_native_app: ContextVar[Any] = ContextVar("_native_app", default=None)
+_prefix_and_app: ContextVar[tuple[str, Starlette] | None] = ContextVar("_prefix_and_app", default=None)
+
+
+class MplbedMiddleware:
+    """
+    ASGI middleware to sets up routing and ensures context the correct context is
+    available so that the integrations work correctly.
+    """
+
+    @doc(
+        f"""
+        Initialize the MplbedMiddleware.
+
+        Parameters
+        ----------
+        default_app : ASGI3Application
+            The default ASGI app to use (i.e. the main app, typically yours).
+        {D.prefix}
+        {D.mplbed_starlette_app("app")}
+        {D.mplbed_starlette_app_kwargs("app_kwargs")}
+        {D.manage_routing}
+        {D.native_app}
+        """
+    )
+    def __init__(
+        self,
+        default_app,
+        *,
+        prefix: str,
+        app=None,
+        app_kwargs=None,
+        manage_routing=True,
+        native_app=None,
+    ):
+        from mplbed.server import mplbed_app_factory
+
+        self.main_app = default_app
+        if app is None and not manage_routing:
+            raise ValueError(
+                "If manage_routing is False, you must construct and provide the app yourself "
+                "(otherwise how do you plan to route to it?)"
+            )
+        if app is not None:
+            self.mplbed_app = app
+        elif app_kwargs is not None:
+            self.mplbed_app = mplbed_app_factory(**app_kwargs)
+        else:
+            self.mplbed_app = mplbed_app_factory()
+        self.prefix = prefix
+        self.manage_routing = manage_routing
+        self.native_app = native_app
+        if manage_routing:
+            self.mount = Mount(prefix, self.mplbed_app)
+
+    async def __call__(self, scope, receive, send):
+        """ASGI entry point for the middleware."""
+        with (
+            _native_app.set(self.native_app),
+            _prefix_and_app.set((self.prefix, self.mplbed_app)),
+        ):
+            if self.manage_routing:
+                assert self.mount
+                match, child_scope = self.mount.matches(scope)
+                if match != Match.NONE:
+                    scope.update(child_scope)
+                    await self.mplbed_app(scope, receive, send)
+                    return
+            await self.main_app(scope, receive, send)
+
+
+def get_native_app():
+    """Get the native app from the current context.
+
+    Returns
+    -------
+    Any
+        The native app, or None if not set.
+
+    """
+    return _native_app.get()
+
+
+def get_asgi_app():
+    """Get the ASGI app from the current context.
+
+    Returns
+    -------
+    ASGI3Application | None
+        The ASGI app, or None if not set.
+
+    """
+    val = _prefix_and_app.get()
+    if val is not None:
+        _, app = val
+        return app
+    return None
+
+
+def url_path_for(name, **path_params):
+    """Get the URL path for a given route name and parameters."""
+    prefix_and_app = path_params.pop("_prefix_and_app", None)
+    if prefix_and_app is None:
+        prefix_and_app = _prefix_and_app.get()
+        if prefix_and_app is None:
+            raise RuntimeError(
+                "Missing current prefix_and_app in context! "
+                "Did you install the MlpbedMiddleware? (_prefix_and_app was not passed)"
+            )
+    prefix, app = prefix_and_app
+    path = app.url_path_for(name, **path_params)
+    return prefix + path

mplbed-0.1.0/src/mplbed/consts.py

@@ -0,0 +1,2 @@
+DEFAULT_PREFIX = "/webagg"
+HEAD_TEMPLATE_VARIABLE_NAME = "mplbed_head"

mplbed-0.1.0/src/mplbed/html/_impl.py

@@ -0,0 +1,149 @@
+from mplbed.asgi import url_path_for
+
+
+def figure_html_from_id(fig_id, *, target="inline", on_close="msg_discrete", prefix_and_app=None):
+    from json import dumps
+
+    ws_uri = url_path_for("websocket", fig_id=fig_id, _prefix_and_app=prefix_and_app)
+    ws_uri_str = dumps(ws_uri)
+    download_fig_uri = url_path_for("download_fig", fig_id=fig_id, fmt="{fmt}", _prefix_and_app=prefix_and_app)
+    download_fig_uri_str = dumps(download_fig_uri)
+    container = ""
+    setup_container = ""
+    if target == "inline":
+        container = "<div></div>"
+        target_js = "document.currentScript.previousElementSibling"
+    elif target == "body":
+        target_js = "document.body"
+    elif target == "modal":
+        container = """
+            <dialog closedby="any" style="padding: 1em; margin: 0 auto;"></dialog>
+            """.strip()
+        target_js = "document.currentScript.previousElementSibling"
+        setup_container = """
+            _mpl_webaggext.mk_modal(document.currentScript.previousElementSibling, fig);
+            """.strip()
+    else:
+        raise ValueError(f"Invalid target: {target}")
+    if on_close == "remove_dialog":
+        on_close = ["remove_parent", "dialog"]
+    on_close_js = dumps(on_close)
+    create_figure = f"""
+    let fig = _mpl_webaggext.new_fig(
+        {target_js},
+        {fig_id},
+        {ws_uri_str},
+        {download_fig_uri_str},
+        {on_close_js}
+    );
+    """.strip()
+    bits = (
+        container,
+        """
+        <script>
+        (function() {
+        """.strip(),
+        create_figure,
+        setup_container,
+        """
+        })();
+        </script>
+        """.strip(),
+    )
+    return "\n".join(bits)
+
+
+def figure_html(figure, *retains, target="inline", on_close="msg_discrete"):
+    from matplotlib.pyplot import _get_backend_mod as get_backend_mod
+
+    from mplbed.server._impl import add_manager
+
+    manager = get_backend_mod().new_figure_manager_given_figure(id(figure), figure)
+    if hasattr(manager, "add_retains"):
+        manager.add_retains(*retains)  # ty: ignore
+    else:
+        if not hasattr(figure, "_retains"):
+            figure._retains = []
+        figure._retains.extend(retains)
+    add_manager(manager)
+    return figure_html_from_id(manager.num, target=target, on_close=on_close)
+
+
+def default_figure_page_template(*, head, fig, title):
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+    {head}
+    <title>{title}</title>
+</head>
+<body>
+    {fig}
+</body>
+</html>
+"""
+
+
+_template_preview = default_figure_page_template(head="{head}", fig="{fig}", title="{title}")
+_indented = "\n".join("    " + line for line in _template_preview.splitlines())
+default_figure_page_template.__doc__ = (
+    "Applies the following template to the given ``head``, ``fig`` and ``title``:\n\n"
+    ".. code-block:: html\n\n" + _indented + "\n"
+)
+del _template_preview, _indented
+
+
+def head_content(*, core=False, prefix_and_app=None):
+    css_files = []
+    if not core:
+        css_files.extend(["page", "boilerplate", "fbm"])
+    css_files.append("mpl")
+    head_bits = []
+    for css_file in css_files:
+        static_url = url_path_for("static", path=f"css/{css_file}.css", _prefix_and_app=prefix_and_app)
+        head_bits.append(
+            f"""
+                <link rel="stylesheet" href="{static_url}" type="text/css">
+            """.strip()
+        )
+    mpl_js_uri = url_path_for("mpl_js", _prefix_and_app=prefix_and_app)
+    head_bits.append(
+        f"""
+        <script src="{mpl_js_uri}"></script>
+    """.strip()
+    )
+    webaggext_js_uri = url_path_for("webaggext_js", _prefix_and_app=prefix_and_app)
+    head_bits.append(
+        f"""
+        <script src="{webaggext_js_uri}"></script>
+    """.strip()
+    )
+    head_bits.append(
+        """
+        <style>
+        .mpl-toolbar {
+            position: relative;
+            padding-bottom: 2em;
+        }
+        .mpl-message {
+            position: absolute;
+            left: 0;
+            bottom: 0;
+            white-space: nowrap;
+            overflow-x: auto;
+            width: 100%;
+        }
+        .mpl-figure-root {
+            display: inline-flex !important;
+            flex-direction: column;
+        }
+        </style>
+    """.strip()
+    )
+    return "\n".join(head_bits)
+
+
+def figure_page_html(fig, *, template=default_figure_page_template):
+    fig_html = figure_html(fig, target="body")
+    head = head_content(core=True)
+    resp_html = template(head=head, title="figure", fig=fig_html)
+    return resp_html

mplbed-0.1.0/src/mplbed/html/raw.py

@@ -0,0 +1,15 @@
+from mplbed.html._impl import (
+    default_figure_page_template,
+    figure_html,
+    figure_html_from_id,
+    figure_page_html,
+    head_content,
+)
+
+__all__ = [
+    "figure_html_from_id",
+    "figure_html",
+    "head_content",
+    "figure_page_html",
+    "default_figure_page_template",
+]

mplbed-0.1.0/src/mplbed/html/safe.py

@@ -0,0 +1,22 @@
+from mplbed.html import _impl
+
+
+def _wrap_markupsafe(func):
+    def wrapper(*args, **kwargs):
+        from markupsafe import Markup
+
+        return Markup(func(*args, **kwargs))
+
+    return wrapper
+
+
+figure_html_from_id = _wrap_markupsafe(_impl.figure_html_from_id)
+head_content = _wrap_markupsafe(_impl.head_content)
+figure_html = _wrap_markupsafe(_impl.figure_html)
+
+
+__all__ = [
+    "figure_html_from_id",
+    "figure_html",
+    "head_content",
+]