ultraplot 2.1.9__tar.gz → 2.3.0__tar.gz

{ultraplot-2.1.9 → ultraplot-2.3.0}/.github/workflows/main.yml

@@ -9,7 +9,7 @@ jobs:
   run-if-changes:
     runs-on: ubuntu-latest
     outputs:
-      run: ${{ (github.event_name == 'push' && github.ref_name == 'main') && 'true' || steps.filter.outputs.python }}
+      run: ${{ github.event_name == 'push' && 'true' || steps.filter.outputs.python }}
     steps:
       - uses: actions/checkout@v6
       - uses: dorny/paths-filter@v4

{ultraplot-2.1.9 → ultraplot-2.3.0}/.github/workflows/publish-pypi.yml

@@ -3,8 +3,7 @@ name: Publish to PyPI
 on:
   pull_request:
   push:
-    tags:
-      - "v*"
+    tags: ["v*"]
 
 concurrency:
   group: publish-pypi-${{ github.sha }}
@@ -131,55 +130,55 @@ jobs:
       contents: write
     steps:
       - name: Create GitHub release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           generate_release_notes: true
 
-  publish-zenodo:
-    name: Publish Zenodo release
-    needs: publish-github-release
-    runs-on: ubuntu-latest
-    if: github.event_name == 'push'
-    permissions:
-      contents: read
-    env:
-      ZENODO_ACCESS_TOKEN: ${{ secrets.ZENODO_ACCESS_TOKEN }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-python@v6
-        with:
-          python-version: "3.12"
-
-      - name: Install release tooling
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install PyYAML
-        shell: bash
-
-      - name: Download artifacts
-        uses: actions/download-artifact@v8
-        with:
-          name: dist-${{ github.sha }}-${{ github.run_id }}-${{ github.run_number }}
-          path: dist
-
-      - name: Generate release citation metadata
-        run: |
-          python tools/release/sync_citation.py \
-            --tag "${GITHUB_REF_NAME}" \
-            --output "${RUNNER_TEMP}/CITATION.cff"
-        shell: bash
-
-      - name: Check tree stayed clean
-        run: |
-          git diff --quiet || (git status --short && git diff && exit 1)
-        shell: bash
-
-      - name: Publish to Zenodo
-        run: |
-          python tools/release/publish_zenodo.py \
-            --dist-dir dist \
-            --citation-file "${RUNNER_TEMP}/CITATION.cff"
-        shell: bash
+  # publish-zenodo:
+  #   name: Publish Zenodo release
+  #   needs: publish-github-release
+  #   runs-on: ubuntu-latest
+  #   if: github.event_name == 'push'
+  #   permissions:
+  #     contents: read
+  #   env:
+  #     ZENODO_ACCESS_TOKEN: ${{ secrets.ZENODO_ACCESS_TOKEN }}
+  #   steps:
+  #     - uses: actions/checkout@v6
+  #       with:
+  #         fetch-depth: 0
+  #
+  #     - uses: actions/setup-python@v6
+  #       with:
+  #         python-version: "3.12"
+  #
+  #     - name: Install release tooling
+  #       run: |
+  #         python -m pip install --upgrade pip
+  #         python -m pip install PyYAML
+  #       shell: bash
+  #
+  #     - name: Download artifacts
+  #       uses: actions/download-artifact@v8
+  #       with:
+  #         name: dist-${{ github.sha }}-${{ github.run_id }}-${{ github.run_number }}
+  #         path: dist
+  #
+  #     - name: Generate release citation metadata
+  #       run: |
+  #         python tools/release/sync_citation.py \
+  #           --tag "${GITHUB_REF_NAME}" \
+  #           --output "${RUNNER_TEMP}/CITATION.cff"
+  #       shell: bash
+  #
+  #     - name: Check tree stayed clean
+  #       run: |
+  #         git diff --quiet || (git status --short && git diff && exit 1)
+  #       shell: bash
+  #
+  #     - name: Publish to Zenodo
+  #       run: |
+  #         python tools/release/publish_zenodo.py \
+  #           --dist-dir dist \
+  #           --citation-file "${RUNNER_TEMP}/CITATION.cff"
+  #       shell: bash

{ultraplot-2.1.9 → ultraplot-2.3.0}/.pre-commit-config.yaml

@@ -11,6 +11,6 @@ ci:
 
 repos:
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 26.3.1
+    rev: 26.5.1
     hooks:
       - id: black

{ultraplot-2.1.9/ultraplot.egg-info → ultraplot-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ultraplot
-Version: 2.1.9
+Version: 2.3.0
 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>
@@ -29,7 +29,7 @@ Provides-Extra: docs
 Requires-Dist: jupyter; extra == "docs"
 Requires-Dist: jupytext; extra == "docs"
 Requires-Dist: lxml-html-clean; extra == "docs"
-Requires-Dist: m2r2; extra == "docs"
+Requires-Dist: markdown; extra == "docs"
 Requires-Dist: mpltern; extra == "docs"
 Requires-Dist: nbsphinx; extra == "docs"
 Requires-Dist: sphinx; extra == "docs"

ultraplot-2.3.0/docs/_scripts/fetch_releases.py

@@ -0,0 +1,154 @@
+"""
+Dynamically build the "What's new?" page from the GitHub releases feed.
+
+The release notes on GitHub are written in Markdown and frequently mix raw
+HTML (``<details><summary>`` blocks wrapping fenced code samples). The
+previous implementation converted the body to RST via ``m2r2``, which left
+the inner Markdown code fences inside ``.. raw:: html`` directives — Sphinx
+then rendered them as literal text. This module instead converts each
+release body to HTML (so fences become ``<pre><code>`` elements) and emits
+a single ``.. raw:: html`` block per release wrapped in a styling hook
+``div.uplt-whats-new-release-body``.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Iterable
+
+import markdown
+import requests
+
+GITHUB_REPO = "ultraplot/ultraplot"
+OUTPUT_RST = Path("whats_new.rst")
+GITHUB_API_URL = f"https://api.github.com/repos/{GITHUB_REPO}/releases"
+
+# Markdown extensions: fenced code (for ```python blocks), tables, attribute
+# lists for class hooks, and md_in_html so block-level HTML such as
+# ``<details>`` correctly contains parsed Markdown children.
+_MD_EXTENSIONS = ("fenced_code", "tables", "attr_list", "md_in_html")
+
+# Strip the trailing "by @user in PR_URL" attribution that GitHub auto-adds
+# to release notes. Keep the PR link in parentheses so credit/traceability
+# remains while removing the contributor handles from rendered output.
+# GitHub author handles can include ``[bot]`` suffixes (``@dependabot[bot]``,
+# ``@pre-commit-ci[bot]``); ``\w`` alone misses the brackets.
+_PR_ATTRIBUTION = re.compile(
+    r" by @[\w.\-]+(?:\[bot\])? in (https://github\.com/[^\s]+)"
+)
+
+# Match an ATX heading line, tolerating up-to-3 leading spaces. Authors
+# occasionally indent whole sections by two spaces in the GitHub release
+# editor (e.g. v2.0.1's "### Layout, Rendering, and Geo Improvements"),
+# which python-markdown then parses as a paragraph rather than a heading.
+# We capture the ``#`` run so we can both strip the indent and downgrade
+# one level — the page already provides the H1 ("What's new?") and each
+# release contributes a per-release RST H2, so body headings start at H2.
+_ATX_HEADING = re.compile(r"^[ ]{0,3}(#{1,5})(?=\s)", flags=re.MULTILINE)
+
+
+def _strip_pr_attribution(text: str) -> str:
+    return _PR_ATTRIBUTION.sub(r" (\1)", text)
+
+
+def _downgrade_headings(text: str) -> str:
+    """Demote every Markdown ATX heading by one level (``#`` → ``##``, etc.)."""
+    return _ATX_HEADING.sub(lambda m: "#" + m.group(1), text)
+
+
+def _normalize_unicode(text: str) -> str:
+    return text.replace("→", "->")
+
+
+def _indent_html(html: str, indent: str = "   ") -> str:
+    """Indent every line of ``html`` by ``indent`` for inclusion under ``.. raw:: html``."""
+    return "\n".join(indent + line if line else line for line in html.splitlines())
+
+
+def format_release_body(text: str) -> str:
+    """
+    Convert a GitHub release body (Markdown + embedded HTML) into an RST
+    ``.. raw:: html`` block wrapped in ``div.uplt-whats-new-release-body``.
+
+    Parameters
+    ----------
+    text : str
+        Raw Markdown release body as returned by the GitHub releases API.
+
+    Returns
+    -------
+    str
+        Indented RST snippet ready to be appended to ``whats_new.rst``.
+    """
+    cleaned = _downgrade_headings(
+        _normalize_unicode(_strip_pr_attribution(text or ""))
+    ).strip()
+    html_body = markdown.markdown(cleaned, extensions=list(_MD_EXTENSIONS))
+    wrapped = f'<div class="uplt-whats-new-release-body">\n{html_body}\n</div>'
+    return ".. raw:: html\n\n" + _indent_html(wrapped) + "\n"
+
+
+def _format_release_title(release: dict) -> str:
+    """
+    Build the per-release section title in ``"<tag>: <name>"`` form,
+    de-duplicating the tag if it is already a prefix of the release name.
+    """
+    tag = release["tag_name"].lower()
+    title = (release.get("name") or "").strip()
+    if title.lower().startswith(tag):
+        title = title[len(tag) :].lstrip(" :-—–")
+    return f"{tag}: {title}" if title else tag
+
+
+def fetch_all_releases() -> list[dict]:
+    """Fetch every GitHub release across paginated responses."""
+    releases: list[dict] = []
+    page = 1
+    while True:
+        response = requests.get(GITHUB_API_URL, params={"per_page": 30, "page": page})
+        if response.status_code != 200:
+            print(f"Error fetching releases: {response.status_code}")
+            break
+        page_data = response.json()
+        if not page_data:
+            break
+        releases.extend(page_data)
+        page += 1
+    return releases
+
+
+def _render_releases(releases: Iterable[dict]) -> str:
+    """Render an iterable of release dicts to the full ``whats_new.rst`` body."""
+    header = "What's new?"
+    out = f".. _whats_new:\n\n{header}\n{'=' * len(header)}\n\n"
+    for release in releases:
+        title = _format_release_title(release)
+        date = release["published_at"][:10]
+        heading = f"{title} ({date})"
+        out += f"{heading}\n{'-' * len(heading)}\n\n"
+        out += format_release_body(release.get("body") or "") + "\n"
+    return out
+
+
+def fetch_releases() -> str:
+    """Fetch the latest releases from GitHub and format them as RST."""
+    releases = fetch_all_releases()
+    if not releases:
+        print("Error fetching releases!")
+        return ""
+    return _render_releases(releases)
+
+
+def write_rst() -> None:
+    """Write fetched releases to ``whats_new.rst``."""
+    content = fetch_releases()
+    if content:
+        OUTPUT_RST.write_text(content, encoding="utf-8")
+        print(f"Updated {OUTPUT_RST}")
+    else:
+        print("No updates to write.")
+
+
+if __name__ == "__main__":
+    write_rst()

{ultraplot-2.1.9 → ultraplot-2.3.0}/docs/_static/custom.css

@@ -1212,3 +1212,41 @@ body.wy-body-for-nav
     border-radius: 0.2rem;
     background: var(--uplt-color-sidebar-bg);
 }
+
+/* What's-new release bodies generated by docs/_scripts/fetch_releases.py.
+   Each release is emitted inside a <div class="uplt-whats-new-release-body">
+   so we have a single styling hook for spacing, code-block padding, and the
+   <details> snippet affordance. */
+.uplt-whats-new-release-body {
+    margin-top: 0.5rem;
+    margin-bottom: 1.5rem;
+}
+
+.uplt-whats-new-release-body h2,
+.uplt-whats-new-release-body h3,
+.uplt-whats-new-release-body h4 {
+    margin-top: 1.25rem;
+    margin-bottom: 0.5rem;
+}
+
+.uplt-whats-new-release-body details {
+    margin: 0.5rem 0 1rem;
+    padding: 0.25rem 0.75rem;
+    border: 1px solid var(--uplt-color-sidebar-bg, #e5e7eb);
+    border-radius: 0.35rem;
+    background: var(--uplt-color-sidebar-bg, #f9fafb);
+}
+
+.uplt-whats-new-release-body details > summary {
+    cursor: pointer;
+    font-weight: 600;
+}
+
+.uplt-whats-new-release-body pre {
+    overflow-x: auto;
+}
+
+.uplt-whats-new-release-body img {
+    max-width: 100%;
+    height: auto;
+}

{ultraplot-2.1.9 → ultraplot-2.3.0}/docs/_static/custom.js

@@ -329,7 +329,134 @@ function initShibuyaRightToc() {
   syncRightTocCodeButtons(localtoc);
 }
 
+const upltApiSearchGenericTerms = new Set([
+  "api",
+  "apis",
+  "attribute",
+  "attributes",
+  "class",
+  "classes",
+  "doc",
+  "docs",
+  "documentation",
+  "function",
+  "functions",
+  "method",
+  "methods",
+  "object",
+  "objects",
+  "reference",
+  "references",
+]);
+
+function normalizeApiSearchTerm(term) {
+  return String(term || "")
+    .toLowerCase()
+    .replace(/\(\)$/, "")
+    .trim();
+}
+
+function isGenericApiSearchTerm(term) {
+  return upltApiSearchGenericTerms.has(normalizeApiSearchTerm(term));
+}
+
+function getApiSearchTerms(terms) {
+  if (terms instanceof Set) {
+    return Array.from(terms);
+  }
+  return Array.from(terms || []);
+}
+
+function apiSearchResultMatchesQueryTerm(title, anchor, terms) {
+  const haystack = `${title || ""} ${anchor || ""}`.toLowerCase();
+  const leaf = haystack.split("#").pop().split(".").pop();
+  return getApiSearchTerms(terms).some((term) => {
+    const normalized = normalizeApiSearchTerm(term);
+    if (!normalized || isGenericApiSearchTerm(normalized)) return false;
+    return (
+      leaf === normalized ||
+      leaf.includes(normalized) ||
+      haystack.includes("." + normalized)
+    );
+  });
+}
+
+function initApiSearchScoring() {
+  if (typeof Search === "undefined" || typeof Scorer === "undefined") return;
+  if (Search.upltApiSearchScoring === "1") return;
+
+  const previousParseQuery = Search._parseQuery;
+  if (typeof previousParseQuery === "function") {
+    Search._parseQuery = function (query) {
+      const parsed = previousParseQuery.call(this, query);
+      const queryTerms = new Set(
+        getApiSearchTerms(parsed && parsed[4])
+          .map(normalizeApiSearchTerm)
+          .filter(Boolean),
+      );
+      Search.upltQueryTerms = queryTerms;
+      Search.upltApiLikeQuery =
+        /[.()]/.test(query || "") ||
+        getApiSearchTerms(queryTerms).some(isGenericApiSearchTerm);
+      return parsed;
+    };
+  }
+
+  const previousObjectSearch = Search.performObjectSearch;
+  if (typeof previousObjectSearch === "function") {
+    Search.performObjectSearch = function (object, objectTerms) {
+      const normalizedObject = normalizeApiSearchTerm(object);
+      const filteredTerms = new Set(
+        getApiSearchTerms(objectTerms)
+          .map(normalizeApiSearchTerm)
+          .filter((term) => term && !isGenericApiSearchTerm(term)),
+      );
+      if (normalizedObject && !isGenericApiSearchTerm(normalizedObject)) {
+        filteredTerms.add(normalizedObject);
+      }
+      return previousObjectSearch.call(this, object, filteredTerms);
+    };
+  }
+
+  const previousScore = Scorer.score;
+  Scorer.score = function (result) {
+    let score =
+      typeof previousScore === "function" ? previousScore(result) : result[4];
+    if (!Number.isFinite(score)) {
+      score = Number.isFinite(result[4]) ? result[4] : 0;
+    }
+
+    const [docname, title, anchor, descr, _baseScore, _filename, kind] = result;
+    const isApiReference = String(docname || "").startsWith("api/");
+    const isApiLikeQuery = !!Search.upltApiLikeQuery;
+    const queryTerms = Search.upltQueryTerms || new Set();
+
+    if (isApiReference && kind === "object") {
+      score += 24;
+      if (isApiLikeQuery) score += 16;
+      if (apiSearchResultMatchesQueryTerm(title, anchor, queryTerms)) {
+        score += 12;
+      }
+      if (
+        queryTerms.has("function") &&
+        String(descr || "").toLowerCase().includes("python function")
+      ) {
+        score += 4;
+      }
+    } else if (isApiReference && isApiLikeQuery) {
+      score += kind === "title" || kind === "index" ? 12 : 8;
+    } else if (!isApiReference && isApiLikeQuery) {
+      score -= 4;
+    }
+
+    return score;
+  };
+
+  Search.upltApiSearchScoring = "1";
+}
+
 document.addEventListener("DOMContentLoaded", function () {
+  initApiSearchScoring();
   initScrollChromeFade();
 
   if (document.querySelector(".sphx-glr-thumbcontainer")) {

{ultraplot-2.1.9 → ultraplot-2.3.0}/docs/colorbars_legends.py

@@ -477,13 +477,19 @@ axs.format(xlabel="xlabel", ylabel="ylabel", suptitle="Legend formatting demo")
 #
 # Legends usually annotate artists already drawn on an axes, but sometimes you need
 # standalone semantic keys (categories, size scales, color levels, or geometry types).
-# UltraPlot provides helper methods that build these entries directly:
+# UltraPlot provides helper methods that build these entries directly on both
+# axes and figures:
 #
 # * :meth:`~ultraplot.axes.Axes.entrylegend`
 # * :meth:`~ultraplot.axes.Axes.catlegend`
 # * :meth:`~ultraplot.axes.Axes.sizelegend`
 # * :meth:`~ultraplot.axes.Axes.numlegend`
 # * :meth:`~ultraplot.axes.Axes.geolegend`
+# * :meth:`~ultraplot.figure.Figure.entrylegend`
+# * :meth:`~ultraplot.figure.Figure.catlegend`
+# * :meth:`~ultraplot.figure.Figure.sizelegend`
+# * :meth:`~ultraplot.figure.Figure.numlegend`
+# * :meth:`~ultraplot.figure.Figure.geolegend`
 #
 # These helpers are useful whenever the legend should describe an encoding rather than
 # mirror artists that already happen to be drawn. In practice there are two distinct
@@ -513,7 +519,8 @@ axs.format(xlabel="xlabel", ylabel="ylabel", suptitle="Legend formatting demo")
 #
 # The helpers are intentionally composable. Each one accepts ``add=False`` and returns
 # ``(handles, labels)`` so you can merge semantic sections and pass the result through
-# :meth:`~ultraplot.axes.Axes.legend` yourself.
+# :meth:`~ultraplot.axes.Axes.legend` or :meth:`~ultraplot.figure.Figure.legend`
+# yourself.
 #
 # .. code-block:: python
 #
@@ -568,6 +575,27 @@ axs.format(xlabel="xlabel", ylabel="ylabel", suptitle="Legend formatting demo")
 #
 # .. code-block:: python
 #
+#    # Add semantic legends around an entire subplot group.
+#    fig, axs = uplt.subplots(ncols=2)
+#    fig.catlegend(
+#        ["Control", "Treatment"],
+#        colors={"Control": "blue7", "Treatment": "red7"},
+#        markers={"Control": "o", "Treatment": "^"},
+#        ref=axs,
+#        loc="b",
+#        title="Group",
+#    )
+#    fig.sizelegend(
+#        [10, 50, 200],
+#        labels=["Small", "Medium", "Large"],
+#        color="gray6",
+#        ref=axs,
+#        loc="r",
+#        title="Population",
+#    )
+#
+# .. code-block:: python
+#
 #    # Compose multiple semantic helpers into one legend.
 #    size_handles, size_labels = ax.sizelegend(
 #        [10, 50, 200],
@@ -685,6 +713,32 @@ ax.geolegend(
 ax.axis("off")
 
 
+# %%
+fig, axs = uplt.subplots(ncols=2, refwidth=2.8, share=False)
+axs[0].scatter([0, 1, 2], [3, 1, 2], c=[0.2, 0.5, 0.8], s=[40, 120, 260])
+axs[1].scatter([0, 1, 2], [2, 3, 1], c=[0.8, 0.4, 0.1], s=[60, 90, 220])
+axs.format(title="Figure semantic legend helpers", grid=False)
+
+fig.catlegend(
+    ["Control", "Treatment"],
+    colors={"Control": "blue7", "Treatment": "red7"},
+    markers={"Control": "o", "Treatment": "^"},
+    ref=axs,
+    loc="bottom",
+    title="Group",
+    frameon=False,
+)
+fig.sizelegend(
+    [40, 120, 260],
+    labels=["Small", "Medium", "Large"],
+    color="gray6",
+    ref=axs,
+    loc="right",
+    title="Size scale",
+    frameon=False,
+)
+
+
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_guides_decouple:
 #

{ultraplot-2.1.9 → ultraplot-2.3.0}/docs/contributing.rst

@@ -241,6 +241,39 @@ Note that you can create the pull request before you're finished with your
 feature addition or bug fix. The PR will update as you add more commits. UltraPlot
 developers and contributors can then review your code and offer suggestions.
 
+.. _contrib_ai:
+
+AI policy
+=========
+
+UltraPlot welcomes contributions from developers at all skill levels, including
+those who use AI tools as part of their workflow. To keep contributions
+meaningful and to help new contributors genuinely learn the codebase, we ask
+that you follow these guidelines.
+
+**Good first issues must be written by humans.**
+Issues labelled *good first issue* are intentionally kept for people who want
+to get familiar with the backend. These issues should be scoped, described, and
+solved by a human — not generated or resolved wholesale by an AI assistant.
+Working through them yourself is how you build the mental model of the code
+that makes future contributions easier.
+
+**AI-assisted contributions are welcome for other issues**, provided that:
+
+* You understand and can explain every change you submit. Maintainers may ask
+  questions during review; if you cannot answer them the PR will be closed.
+* You disclose AI assistance in the PR description (a one-line note is fine).
+* The code meets the same quality bar as any other contribution — correct,
+  tested, and consistent with the existing style.
+
+**AI must not be used to bulk-generate issues, comments, or spam.**
+Automated issue creation or low-effort AI-generated content will be removed and
+may result in being blocked from the repository.
+
+The spirit of this policy is simple: AI is a tool, not a substitute for
+understanding. We want contributions that improve UltraPlot *and* grow the
+contributor.
+
 .. _contrib_release:
 
 Release procedure

ultraplot-2.3.0/docs/examples/legend_types/01_semantic_legends.py

@@ -0,0 +1,5 @@
+"""
+Semantic legends
+================
+With UltraPlot semantic legends can be expressed in a flexible and cohesive manner with customg glyphs, latex and or spatial locations.
+"""