mplbed 0.1.0__py3-none-any.whl

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/_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/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/consts.py

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

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/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/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",
+]

mplbed/integration/_common.py

@@ -0,0 +1,291 @@
+import inspect
+from functools import wraps
+from typing import Any
+
+from frozendict import frozendict
+
+EMPTY_DICT = frozendict()
+
+
+def figure_standalone_docstring_factory(*, response_name, template_comment, is_async, params_extra):
+    async_str = "async " if is_async else ""
+    await_str = "await " if is_async else ""
+    return f"""
+    Create a {response_name} object containing the HTML for the given figure using {template_comment}.
+
+    Example
+    -------
+
+    {async_str}def my_handler(request):
+        fig = Figure()
+        return {await_str}figure_page(fig)
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure or callable
+        A matplotlib Figure object or a callable that returns a Figure object.
+    {params_extra}
+    """
+
+
+def figure_page_docstring_factory(*, response_name, template_comment, is_generic, wraps, params_extra):
+    async_str = "(async) " if is_generic else ""
+    await_str = "(await) " if is_generic else ""
+    generic_note = "All usages are generic with regards to async/sync" if is_generic else ""
+    return f"""
+    Decorator to create a {response_name} object containing the HTML for the given figure using {template_comment}.
+
+    This function can be called in two ways:
+    
+    1. As a decorator for a function taking any number of arguments and
+       returning a matplotlib Figure object, making it appropriate to use as a
+       decorator for view/handler function.
+    2. As a decorator for a function taking no arguments and returning a
+       matplotlib Figure object, making it appropriate to use as a decorator for a
+       figure closure within a view/handler.
+    
+    {generic_note}
+
+    Internally this decorator uses the function {wraps} to generate the HTML and create the {response_name}.
+
+    Example
+    -------
+
+    # Usage 1
+    @figure_page
+    {async_str} def my_handler(request):
+        return Figure()
+    
+    # Usage 2
+    {async_str} def my_handler(request):
+        # ...
+        @figure_page
+        {async_str} def create_figure():
+            return Figure()
+        return {await_str} create_figure()
+
+    Parameters
+    ----------
+    {params_extra}
+    """
+
+
+def _has_parameters(func):
+    return len(inspect.signature(func).parameters) > 0
+
+
+def figure_standalone_factory(
+    name,
+    generate_html,
+    response_factory,
+    *,
+    kwarg_defaults=None,
+    response_factory_kwarg_keys=(),
+    make_async=None,
+    ds_response_name="response",
+    ds_template_comment="a template",
+    ds_params_extra,
+):
+    need_async = inspect.iscoroutinefunction(generate_html) or inspect.iscoroutinefunction(response_factory)
+    if make_async is None:
+        make_async = need_async
+    if need_async and not make_async:
+        raise ValueError(
+            "generate_html or response_factory is async, but make_async is False. "
+            "Set make_async to True to allow async usage."
+        )
+
+    def process_kwargs(kwargs):
+        kwargs = {**(kwarg_defaults or {}), **kwargs}
+        response_factory_kwargs = {}
+        for k in response_factory_kwarg_keys:
+            if k in kwargs:
+                response_factory_kwargs[k] = kwargs.pop(k)
+        return kwargs, response_factory_kwargs
+
+    if make_async:
+
+        async def figure_standalone(fig, **kwargs):
+            generate_html_kwargs, response_factory_kwargs = process_kwargs(kwargs)
+            if inspect.iscoroutinefunction(generate_html):
+                html = await generate_html(fig, **generate_html_kwargs)
+            else:
+                html = generate_html(fig, **generate_html_kwargs)
+            if inspect.iscoroutinefunction(response_factory):
+                return await response_factory(html, **response_factory_kwargs)
+            else:
+                return response_factory(html, **response_factory_kwargs)
+    else:
+
+        def figure_standalone(fig, **kwargs):
+            generate_html_kwargs, response_factory_kwargs = process_kwargs(kwargs)
+            return response_factory(generate_html(fig, **generate_html_kwargs), **response_factory_kwargs)
+
+    figure_standalone.__name__ = name
+    figure_standalone.__doc__ = figure_standalone_docstring_factory(
+        response_name=ds_response_name,
+        template_comment=ds_template_comment,
+        is_async=make_async,
+        params_extra=ds_params_extra,
+    )
+    return figure_standalone
+
+
+def figure_page_factory(
+    name,
+    figure_standalone,
+    *,
+    ds_response_name="response",
+    ds_template_comment="a template",
+    ds_params_extra,
+):
+
+    needs_async = inspect.iscoroutinefunction(figure_standalone)
+
+    def figure_page(inner, **figure_page_kwargs):
+        if inspect.iscoroutinefunction(inner):
+            if _has_parameters(inner):
+                # Async view style figure creating function
+                @wraps(inner)
+                async def async_view_wrapper(*args, **kwargs):
+                    actual_fig = await inner(*args, **kwargs)
+                    figure_standalone_kwargs: dict[str, Any] = kwargs.pop("figure_standalone_kwargs", {})
+                    if needs_async:
+                        return await figure_standalone(
+                            actual_fig,
+                            **{**figure_page_kwargs, **figure_standalone_kwargs},
+                        )
+                    else:
+                        return figure_standalone(
+                            actual_fig,
+                            **{**figure_page_kwargs, **figure_standalone_kwargs},
+                        )
+
+                wrapper = async_view_wrapper
+            else:
+                # Async closure style figure creating function
+                @wraps(inner)
+                async def async_closure_wrapper(*, figure_standalone_kwargs=EMPTY_DICT):
+                    actual_fig = await inner()
+                    if needs_async:
+                        return await figure_standalone(
+                            actual_fig,
+                            **{**figure_page_kwargs, **figure_standalone_kwargs},
+                        )
+                    else:
+                        return figure_standalone(
+                            actual_fig,
+                            **{**figure_page_kwargs, **figure_standalone_kwargs},
+                        )
+
+                wrapper = async_closure_wrapper
+        else:
+            if needs_async:
+                raise ValueError(f"Decorated function must be async for {name} (wrapping {figure_standalone.__name__})")
+            if _has_parameters(inner):
+                # View style figure creating function
+                @wraps(inner)
+                def view_wrapper(*args, **kwargs):
+                    actual_fig = figure_standalone(*args, **kwargs)
+                    figure_standalone_kwargs: dict[str, Any] = kwargs.pop("figure_standalone_kwargs", {})
+                    return figure_page(actual_fig, **{**figure_page_kwargs, **figure_standalone_kwargs})
+
+                wrapper = view_wrapper
+            else:
+                # Closure style figure creating function
+                @wraps(inner)
+                def closure_wrapper(*, figure_standalone_kwargs=EMPTY_DICT):
+                    actual_fig = figure_standalone()
+                    return figure_page(actual_fig, **{**figure_page_kwargs, **figure_standalone_kwargs})
+
+                wrapper = closure_wrapper
+        wrapper.__name__ = name
+        return wrapper
+
+    figure_page.__doc__ = figure_page_docstring_factory(
+        response_name=ds_response_name,
+        template_comment=ds_template_comment,
+        wraps=figure_standalone.__name__,
+        is_generic=not needs_async,
+        params_extra=ds_params_extra,
+    )
+    return figure_page
+
+
+def mk_figure_page_variants(
+    suffix,
+    generate_html,
+    response_factory,
+    *,
+    kwarg_defaults=None,
+    response_factory_kwarg_keys=(),
+    ds_response_name="response",
+    ds_template_comment="a template",
+    ds_params_extra,
+):
+    need_async = inspect.iscoroutinefunction(generate_html) or inspect.iscoroutinefunction(response_factory)
+    results = {}
+    standalone_args = dict(
+        generate_html=generate_html,
+        response_factory=response_factory,
+        kwarg_defaults=kwarg_defaults,
+        response_factory_kwarg_keys=response_factory_kwarg_keys,
+        ds_response_name=ds_response_name,
+        ds_template_comment=ds_template_comment,
+        ds_params_extra=ds_params_extra,
+    )
+    page_args = dict(
+        ds_response_name=ds_response_name,
+        ds_template_comment=ds_template_comment,
+        ds_params_extra=ds_params_extra,
+    )
+    if need_async:
+        figure_standalone = figure_standalone_factory(f"figure_standalone{suffix}", **standalone_args, make_async=True)
+        results[f"figure_standalone{suffix}"] = figure_standalone
+        results[f"figure_page{suffix}"] = figure_page_factory(f"figure_page{suffix}", figure_standalone, **page_args)
+    else:
+        figure_standalone = figure_standalone_factory(
+            f"figure_standalone{suffix}",
+            **standalone_args,
+            make_async=False,
+        )
+        results[f"figure_standalone{suffix}"] = figure_standalone
+        results[f"figure_page{suffix}"] = figure_page_factory(f"figure_page{suffix}", figure_standalone, **page_args)
+        figure_standalone_async = figure_standalone_factory(
+            f"figure_standalone{suffix}_async", **standalone_args, make_async=True
+        )
+        results[f"figure_standalone{suffix}_async"] = figure_standalone_async
+        results[f"figure_page{suffix}_async"] = figure_page_factory(
+            f"figure_page{suffix}_async", figure_standalone_async, **page_args
+        )
+    return results
+
+
+def setup_page_docstring(template_func):
+    from mplbed._doc_helpers import PARAMS_DS, DotAccessDict, fdf
+
+    def decorator(wrapped):
+        wrapped.__doc__ = template_func(
+            DotAccessDict(
+                **PARAMS_DS,
+                do_install_middleware=fdf("""
+            do_install_middleware : bool, optional
+                Whether to install the mplbed middleware on the given app. Default is True.
+            """),
+                do_register_context_processor=fdf("""
+            do_register_context_processor : bool, optional
+                Whether to register the mplbed context processor on the given app. Default is True.
+            """),
+                do_use_mpl_backend=fdf("""
+            do_use_mpl_backend : bool, optional
+                Whether to setup the matplotlib backend for rendering figures. Default is True.
+            """),
+                use_webaggext_backend=fdf("""
+            use_webaggext_backend : bool, optional
+                Whether to use webaggext rather than the basic webagg backend for rendering figures. Default is True.
+            """),
+            )
+        )
+        return wrapped
+
+    return decorator