ultraplot 2.7.1__tar.gz → 2.7.4__tar.gz

{ultraplot-2.7.1 → ultraplot-2.7.4}/.github/workflows/build-ultraplot.yml

@@ -299,7 +299,7 @@ jobs:
                 --mpl \
                 --mpl-baseline-path=./ultraplot/tests/baseline \
                 --mpl-results-path=./results/ \
-                --mpl-generate-summary=html \
+                --mpl-generate-summary=json \
                 --mpl-default-style="./ultraplot.yml" \
                 --junitxml=./results/junit.xml \
                 "${FILTERED_NODEIDS[@]}"
@@ -333,7 +333,7 @@ jobs:
               --mpl \
               --mpl-baseline-path=./ultraplot/tests/baseline \
               --mpl-results-path=./results/ \
-              --mpl-generate-summary=html \
+              --mpl-generate-summary=json \
               --mpl-default-style="./ultraplot.yml" \
               --junitxml=./results/junit.xml \
               ultraplot/tests
@@ -360,11 +360,20 @@ jobs:
             exit "$status"
           fi
 
-      # Return the html output of the comparison even if failed
+      # Validate the standalone report rendering on each CI environment.
+      - name: Test failed-comparison report generator
+        if: always() && steps.baseline-support.outputs.baseline-supported == 'true'
+        run: python -m unittest discover -s tools/ci -p 'test_collect_failed_comparisons.py'
+
+      # JSON mode does not save images for passing comparisons.
+      - name: Collect failed image comparisons
+        if: always() && steps.baseline-support.outputs.baseline-supported == 'true'
+        run: python tools/ci/collect_failed_comparisons.py --results results --output failed-comparisons
+
       - name: Upload comparison failures
         if: always()
         uses: actions/upload-artifact@v7
         with:
           name: failed-comparisons-${{ inputs.python-version }}-${{ inputs.matplotlib-version }}-${{ github.sha }}
-          path: results/*
+          path: failed-comparisons/
           if-no-files-found: ignore

{ultraplot-2.7.1 → ultraplot-2.7.4}/.gitignore

@@ -64,3 +64,13 @@ ultraplot/_version.py
 
 # Nox build directories
 .nox/*
+
+# Generated docs and draw.io assets. The edited diagram remains a repository asset.
+tools/cheatsheet/assets/
+docs/_static/plot_types/
+tools/cheatsheet/ultraplot_cheatsheet.png
+tools/cheatsheet/ultraplot_cheatsheet-code.png
+tools/cheatsheet/ultraplot_cheatsheet-reference.png
+tools/cheatsheet/ultraplot_cheatsheet-beginner.png
+tools/cheatsheet/ultraplot_cheatsheet-intermediate.png
+tools/cheatsheet/ultraplot_cheatsheet-advanced.png

{ultraplot-2.7.1 → ultraplot-2.7.4}/.pre-commit-config.yaml

@@ -11,12 +11,12 @@ ci:
 
 repos:
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 26.5.1
+    rev: 26.10.1
     hooks:
       - id: black
 
   - repo: https://github.com/tombi-toml/tombi-pre-commit
-    rev: v1.5.2
+    rev: v1.9.8
     hooks:
       - id: tombi-format
         args: ["--offline"]

{ultraplot-2.7.1 → ultraplot-2.7.4}/.readthedocs.yml

@@ -5,6 +5,8 @@ version: 2
 # Set the OS and build tools
 build:
   os: ubuntu-22.04
+  apt_packages:
+    - xvfb
   tools:
     python: "mambaforge-latest"
 

ultraplot-2.7.4/MANIFEST.in

@@ -0,0 +1,2 @@
+# Cheatsheet sources and exports are repository assets, not pip distribution files.
+prune tools/cheatsheet

{ultraplot-2.7.1/ultraplot.egg-info → ultraplot-2.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ultraplot
-Version: 2.7.1
+Version: 2.7.4
 Summary: A succinct matplotlib wrapper for making beautiful, publication-quality graphics.
 Author-email: Casper van Elteren <caspervanelteren@gmail.com>, Luke Davis <lukelbd@gmail.com>
 Maintainer-email: Casper van Elteren <caspervanelteren@gmail.com>, "Matthew R. Becker" <becker.mr@gmail.com>
@@ -49,7 +49,7 @@ Requires-Dist: mcp<3,>=2.1; extra == "mcp"
 Provides-Extra: stats
 Requires-Dist: scipy; extra == "stats"
 Provides-Extra: typing
-Requires-Dist: basedpyright==1.40.1; extra == "typing"
+Requires-Dist: basedpyright==1.40.2; extra == "typing"
 Dynamic: license-file
 
 .. image:: https://raw.githubusercontent.com/Ultraplot/ultraplot/refs/heads/main/UltraPlotLogo.svg
@@ -158,20 +158,6 @@ UltraPlot is published on `PyPi <https://pypi.org/project/ultraplot/>`__ and
    pip install ultraplot
    conda install -c conda-forge ultraplot
 
-pyCirclize-based plots require the optional ``circos`` extra:
-
-.. code-block:: bash
-
-   pip install 'ultraplot[circos]'
-
-The ``docs`` extra also includes pyCirclize for building the documentation.
-
-To install the ``circos``, ``docs``, and ``stats`` dependency groups together:
-
-.. code-block:: bash
-
-   pip install 'ultraplot[all]'
-
 Likewise, an existing installation of UltraPlot can be upgraded
 to the latest version with:
 
@@ -192,102 +178,8 @@ UltraPlot includes a Model Context Protocol (MCP) server that lets AI assistants
 search documentation and examples, inspect the live Python API, and read source
 code and release notes.
 
-Run directly with uvx
----------------------
-
-With `uv <https://docs.astral.sh/uv/getting-started/installation/>`__ installed,
-your MCP client can launch the server with ``uvx``. uv installs the package and
-its dependencies in an isolated environment automatically, so you do not need
-to create a virtual environment or install UltraPlot separately.
-
-For a PyPI release containing the MCP server, the launch command is:
-
-.. code-block:: bash
-
-   uvx --from 'ultraplot[mcp]' ultraplot-mcp
-
-For clients that use an ``mcpServers`` configuration, add:
-
-.. code-block:: json
-
-   {
-     "mcpServers": {
-       "ultraplot": {
-         "command": "uvx",
-         "args": ["--from", "ultraplot[mcp]", "ultraplot-mcp"]
-       }
-     }
-   }
-
-The client starts the server when needed and communicates with it over stdio.
-Other clients may use a different configuration format; use the same command
-and arguments. ``uvx`` is equivalent to ``uv tool run``.
-
-Until the MCP server is released on PyPI, run it directly from the feature
-branch instead:
-
-.. code-block:: bash
-
-   uvx --from 'ultraplot[mcp] @ git+https://github.com/ultraplot/ultraplot.git@feat/mcp' ultraplot-mcp
-
-For this development version, replace ``ultraplot[mcp]`` in the client
-configuration with
-``ultraplot[mcp] @ git+https://github.com/ultraplot/ultraplot.git@feat/mcp``.
-
-Install persistently with uv
-----------------------------
-
-Alternatively, keep the executable on your ``PATH`` by installing it as a uv
-tool. For a PyPI release containing the MCP server:
-
-.. code-block:: bash
-
-   uv tool install 'ultraplot[mcp]'
-   ultraplot-mcp --help
-
-Before that release, install from the feature branch:
-
-.. code-block:: bash
-
-   uv tool install 'ultraplot[mcp] @ git+https://github.com/ultraplot/ultraplot.git@feat/mcp'
-
-Then configure your client to launch ``ultraplot-mcp`` with no arguments.
-If uv reports that its executable directory is missing from ``PATH``, run
-``uv tool update-shell`` and restart your shell.
-
-Install from a checkout
------------------------
-
-From a checkout containing the MCP implementation, install the optional ``mcp``
-extra in the Python environment you want the server to use:
-
-.. code-block:: bash
-
-   pip install -e '.[mcp]'
-
-Connect an MCP client
----------------------
-
-After installing persistently with uv or pip, register the server with an
-installed Codex CLI:
-
-.. code-block:: bash
-
-   ultraplot-mcp install codex
-
-Restart Codex after registration. Try asking it to search the UltraPlot
-examples for shared colorbars or inspect ``ultraplot.subplots``.
-
-For other MCP clients, configure a stdio server with ``ultraplot-mcp`` as the
-command and no arguments. Use the executable's absolute path if the client does
-not inherit your Python environment's ``PATH``. Running ``ultraplot-mcp`` starts
-the server; ``ultraplot-mcp --help`` lists the available commands.
-
-Documentation tools read the checkout's ``docs`` directory. Direct uvx and uv
-tool installations require a separate documentation checkout for these tools.
-If documentation lives elsewhere, set ``ULTRAPLOT_MCP_DOCS`` to its absolute path in the MCP
-client's server environment. Documentation is not currently bundled in the
-Python package; API and source inspection use the installed UltraPlot version.
+See the `MCP installation guide <https://ultraplot.readthedocs.io/en/latest/mcp.html>`__
+for installation instructions, client configuration, and documentation setup.
 
 Citing UltraPlot
 ================

{ultraplot-2.7.1 → ultraplot-2.7.4}/README.rst

@@ -104,20 +104,6 @@ UltraPlot is published on `PyPi <https://pypi.org/project/ultraplot/>`__ and
    pip install ultraplot
    conda install -c conda-forge ultraplot
 
-pyCirclize-based plots require the optional ``circos`` extra:
-
-.. code-block:: bash
-
-   pip install 'ultraplot[circos]'
-
-The ``docs`` extra also includes pyCirclize for building the documentation.
-
-To install the ``circos``, ``docs``, and ``stats`` dependency groups together:
-
-.. code-block:: bash
-
-   pip install 'ultraplot[all]'
-
 Likewise, an existing installation of UltraPlot can be upgraded
 to the latest version with:
 
@@ -138,102 +124,8 @@ UltraPlot includes a Model Context Protocol (MCP) server that lets AI assistants
 search documentation and examples, inspect the live Python API, and read source
 code and release notes.
 
-Run directly with uvx
----------------------
-
-With `uv <https://docs.astral.sh/uv/getting-started/installation/>`__ installed,
-your MCP client can launch the server with ``uvx``. uv installs the package and
-its dependencies in an isolated environment automatically, so you do not need
-to create a virtual environment or install UltraPlot separately.
-
-For a PyPI release containing the MCP server, the launch command is:
-
-.. code-block:: bash
-
-   uvx --from 'ultraplot[mcp]' ultraplot-mcp
-
-For clients that use an ``mcpServers`` configuration, add:
-
-.. code-block:: json
-
-   {
-     "mcpServers": {
-       "ultraplot": {
-         "command": "uvx",
-         "args": ["--from", "ultraplot[mcp]", "ultraplot-mcp"]
-       }
-     }
-   }
-
-The client starts the server when needed and communicates with it over stdio.
-Other clients may use a different configuration format; use the same command
-and arguments. ``uvx`` is equivalent to ``uv tool run``.
-
-Until the MCP server is released on PyPI, run it directly from the feature
-branch instead:
-
-.. code-block:: bash
-
-   uvx --from 'ultraplot[mcp] @ git+https://github.com/ultraplot/ultraplot.git@feat/mcp' ultraplot-mcp
-
-For this development version, replace ``ultraplot[mcp]`` in the client
-configuration with
-``ultraplot[mcp] @ git+https://github.com/ultraplot/ultraplot.git@feat/mcp``.
-
-Install persistently with uv
-----------------------------
-
-Alternatively, keep the executable on your ``PATH`` by installing it as a uv
-tool. For a PyPI release containing the MCP server:
-
-.. code-block:: bash
-
-   uv tool install 'ultraplot[mcp]'
-   ultraplot-mcp --help
-
-Before that release, install from the feature branch:
-
-.. code-block:: bash
-
-   uv tool install 'ultraplot[mcp] @ git+https://github.com/ultraplot/ultraplot.git@feat/mcp'
-
-Then configure your client to launch ``ultraplot-mcp`` with no arguments.
-If uv reports that its executable directory is missing from ``PATH``, run
-``uv tool update-shell`` and restart your shell.
-
-Install from a checkout
------------------------
-
-From a checkout containing the MCP implementation, install the optional ``mcp``
-extra in the Python environment you want the server to use:
-
-.. code-block:: bash
-
-   pip install -e '.[mcp]'
-
-Connect an MCP client
----------------------
-
-After installing persistently with uv or pip, register the server with an
-installed Codex CLI:
-
-.. code-block:: bash
-
-   ultraplot-mcp install codex
-
-Restart Codex after registration. Try asking it to search the UltraPlot
-examples for shared colorbars or inspect ``ultraplot.subplots``.
-
-For other MCP clients, configure a stdio server with ``ultraplot-mcp`` as the
-command and no arguments. Use the executable's absolute path if the client does
-not inherit your Python environment's ``PATH``. Running ``ultraplot-mcp`` starts
-the server; ``ultraplot-mcp --help`` lists the available commands.
-
-Documentation tools read the checkout's ``docs`` directory. Direct uvx and uv
-tool installations require a separate documentation checkout for these tools.
-If documentation lives elsewhere, set ``ULTRAPLOT_MCP_DOCS`` to its absolute path in the MCP
-client's server environment. Documentation is not currently bundled in the
-Python package; API and source inspection use the installed UltraPlot version.
+See the `MCP installation guide <https://ultraplot.readthedocs.io/en/latest/mcp.html>`__
+for installation instructions, client configuration, and documentation setup.
 
 Citing UltraPlot
 ================

ultraplot-2.7.4/docs/_ext/drawio-lazy.js

@@ -0,0 +1,94 @@
+/* Fetch SVG-heavy draw.io pages only when they approach the viewport. */
+(() => {
+  "use strict";
+  let viewerPromise;
+  function viewer() {
+    if (window.GraphViewer && window.DOMPurify && window.pako) return Promise.resolve();
+    if (!viewerPromise) {
+      viewerPromise = new Promise((resolve, reject) => {
+        const script = document.createElement("script");
+        // The standalone viewer bundles DOMPurify, pako and Spinner as UMD
+        // libraries but consumes their browser globals. Sphinx's RequireJS
+        // otherwise captures them as anonymous AMD modules instead.
+        const define = window.define;
+        const amd = define && define.amd;
+        if (amd) define.amd = undefined;
+        const restoreAMD = () => {
+          if (amd) define.amd = amd;
+        };
+        script.src = "https://viewer.diagrams.net/js/viewer-static.min.js";
+        script.onload = () => {
+          restoreAMD();
+          if (window.GraphViewer && window.DOMPurify && window.pako) resolve();
+          else reject(new Error("Viewer dependencies unavailable"));
+        };
+        script.onerror = () => {
+          restoreAMD();
+          script.remove();
+          reject(new Error("Viewer download failed"));
+        };
+        document.head.appendChild(script);
+      }).catch(error => {
+        viewerPromise = undefined;
+        throw error;
+      });
+    }
+    return viewerPromise;
+  }
+
+  async function load(element) {
+    if (element.dataset.loading) return;
+    element.dataset.loading = "true";
+    element.setAttribute("aria-busy", "true");
+    try {
+      const [xml] = await Promise.all([
+        fetch(element.dataset.drawioUrl).then(response => {
+          if (!response.ok) throw new Error(`Diagram download failed (${response.status})`);
+          return response.text();
+        }),
+        viewer(),
+      ]);
+      element.setAttribute("data-mxgraph", JSON.stringify({
+        xml, resize: true, fit: true, nav: false, lightbox: true,
+        toolbar: "zoom lightbox", "toolbar-nohide": true, editable: false,
+      }));
+      element.replaceChildren();
+      window.GraphViewer.createViewerForElement(element);
+      element.removeAttribute("data-mxgraph");
+      element.style.minHeight = "";
+      element.setAttribute("aria-busy", "false");
+    } catch (error) {
+      delete element.dataset.loading;
+      element.setAttribute("aria-busy", "false");
+      const button = document.createElement("button");
+      button.type = "button";
+      button.textContent = "Diagram could not be loaded. Retry";
+      button.addEventListener("click", () => load(element));
+      element.replaceChildren(button);
+      console.warn("Draw.io diagram:", error);
+    }
+  }
+
+  function init() {
+    const elements = document.querySelectorAll(".drawio-lazy");
+    const observer = "IntersectionObserver" in window ? new IntersectionObserver(entries => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          observer.unobserve(entry.target);
+          load(entry.target);
+        }
+      }
+    }, { rootMargin: "300px" }) : null;
+    for (const element of elements) {
+      element.querySelector("a").addEventListener("click", event => {
+        event.preventDefault();
+        if (observer) observer.unobserve(element);
+        load(element);
+      });
+      if (observer) observer.observe(element);
+      else load(element);
+    }
+  }
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", init);
+  else init();
+})();

ultraplot-2.7.4/docs/_ext/drawio.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import html
+from pathlib import Path
+import urllib.parse
+import xml.etree.ElementTree as ET
+import zlib
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from sphinx.util.osutil import relative_uri
+
+
+def _decode_diagram(diagram: ET.Element) -> str:
+    """Return an mxGraphModel XML string from a <diagram> element."""
+
+    # Uncompressed draw.io files can contain mxGraphModel directly.
+    graph = diagram.find("mxGraphModel")
+    if graph is not None:
+        return ET.tostring(graph, encoding="unicode")
+
+    # Normal compressed draw.io representation:
+    # base64 -> raw DEFLATE -> URL decode
+    encoded = (diagram.text or "").strip()
+
+    if not encoded:
+        raise ValueError("Draw.io diagram contains no data")
+
+    compressed = base64.b64decode(encoded)
+    inflated = zlib.decompress(compressed, -15).decode("utf-8")
+
+    return urllib.parse.unquote(inflated)
+
+
+def _get_page(path: Path, selector: str | None) -> str:
+    root = ET.parse(path).getroot()
+    diagrams = root.findall("diagram")
+
+    if not diagrams:
+        raise ValueError(f"No diagrams found in {path}")
+
+    # Default to first page.
+    if selector is None:
+        return _decode_diagram(diagrams[0])
+
+    # Numeric selector = page index.
+    try:
+        index = int(selector)
+    except ValueError:
+        index = None
+
+    if index is not None:
+        try:
+            return _decode_diagram(diagrams[index])
+        except IndexError:
+            raise ValueError(
+                f"Page index {index} does not exist in {path}"
+            ) from None
+
+    # Otherwise treat selector as page name.
+    for diagram in diagrams:
+        if diagram.get("name") == selector:
+            return _decode_diagram(diagram)
+
+    names = [d.get("name", "<unnamed>") for d in diagrams]
+    raise ValueError(
+        f"Page {selector!r} not found in {path}. "
+        f"Available pages: {', '.join(names)}"
+    )
+
+
+class drawio_node(nodes.General, nodes.Element):
+    pass
+
+
+def _visit_drawio_html(self, node):
+    # Write at HTML translation time so cached doctrees also recreate assets
+    # when the output directory is cleaned. Content hashes allow browser caching.
+    xml = node["xml"]
+    digest = hashlib.sha256(xml.encode("utf-8")).hexdigest()
+    asset = f"_drawio/{digest}.xml"
+    path = Path(self.builder.outdir) / asset
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not path.exists():
+        path.write_text(xml, encoding="utf-8")
+    url = relative_uri(self.builder.get_target_uri(self.builder.current_docname), asset)
+    classes = html.escape(" ".join(["drawio-lazy", *node["classes"]]), quote=True)
+    url = html.escape(url, quote=True)
+    self.body.append(
+        f'<div class="{classes}" data-drawio-url="{url}" '
+        'style="min-height:24rem" aria-busy="true">'
+        f'<a href="{url}">Load diagram</a>'
+        '<noscript> (JavaScript is required to view this diagram.)</noscript>'
+        '</div>'
+    )
+    raise nodes.SkipNode
+
+
+def _skip_drawio(self, node):
+    raise nodes.SkipNode
+
+
+class DrawioDirective(Directive):
+    required_arguments = 1
+    has_content = False
+
+    option_spec = {
+        "page": directives.unchanged,
+        "class": directives.class_option,
+    }
+
+    def run(self):
+        env = self.state.document.settings.env
+
+        # Resolve relative to the .rst file containing the directive.
+        source = Path(env.doc2path(env.docname)).resolve()
+        path = (source.parent / self.arguments[0]).resolve()
+
+        if not path.exists():
+            raise self.error(f"Draw.io file not found: {path}")
+
+        # Tell Sphinx that changes to the .drawio file should rebuild this page.
+        env.note_dependency(str(path))
+
+        try:
+            xml = _get_page(path, self.options.get("page"))
+        except (ET.ParseError, ValueError) as exc:
+            raise self.error(str(exc)) from exc
+
+        node = drawio_node()
+        node["xml"] = xml
+        node["classes"] = self.options.get("class", [])
+        return [node]
+
+
+def _copy_loader(app, exception):
+    if exception is None and app.builder.format == "html":
+        target = Path(app.outdir) / "_static" / "drawio-lazy.js"
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(Path(__file__).with_name("drawio-lazy.js").read_bytes())
+
+
+def setup(app):
+    app.add_directive("drawio", DrawioDirective)
+
+    app.add_node(
+        drawio_node,
+        html=(_visit_drawio_html, None),
+        latex=(_skip_drawio, None),
+        text=(_skip_drawio, None),
+    )
+    # Copy our loader without requiring changes to html_static_path.
+    app.connect("build-finished", _copy_loader)
+    app.add_js_file("drawio-lazy.js", loading_method="defer")
+
+    return {
+        "version": "2.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

ultraplot-2.7.4/docs/_scripts/build_plot_types.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""
+Regenerate the visual plot-type index before a documentation build.
+
+Run from ``conf.py`` the same way ``fetch_releases.py`` is: the page and its
+thumbnails are generated artefacts, so a clean checkout builds them rather than
+carrying 60-odd PNGs in the repository. Rendering is skipped when the icons are
+already present, so a local rebuild costs nothing.
+"""
+
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.dirname(os.path.dirname(HERE))
+GENERATOR = os.path.join(ROOT, "tools", "cheatsheet")
+
+sys.path.insert(0, GENERATOR)
+
+
+def main():
+    try:
+        import docs_index
+    except ImportError as error:  # the tools folder is not shipped in sdists
+        print(f"plot-type index skipped: {error}")
+        return
+    try:
+        docs_index.main()
+    except Exception as error:  # never fail the docs build over a thumbnail
+        print(f"plot-type index skipped: {type(error).__name__}: {error}")
+
+
+if __name__ == "__main__":
+    main()