ultraplot 2.2.0__tar.gz → 2.3.0__tar.gz

{ultraplot-2.2.0 → 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.2.0 → ultraplot-2.3.0}/.github/workflows/publish-pypi.yml

@@ -130,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.2.0 → 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.2.0/ultraplot.egg-info → ultraplot-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ultraplot
-Version: 2.2.0
+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>

{ultraplot-2.2.0 → 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.2.0 → 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.2.0 → 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.
+"""

ultraplot-2.3.0/docs/examples/legends_colorbars/03_semantic_legends.py

@@ -0,0 +1,233 @@
+"""
+Semantic legends
+================
+
+Build legends from semantic mappings rather than existing artists.
+
+Why UltraPlot here?
+-------------------
+UltraPlot adds semantic legend helpers on both axes and figures:
+``entrylegend``, ``catlegend``, ``sizelegend``, ``numlegend``, and ``geolegend``.
+These are useful when you want legend meaning decoupled from plotted handles, or
+when you want a standalone semantic key that describes an encoding directly.
+
+Key functions: :py:meth:`ultraplot.axes.Axes.entrylegend`, :py:meth:`ultraplot.axes.Axes.catlegend`, :py:meth:`ultraplot.axes.Axes.sizelegend`, :py:meth:`ultraplot.axes.Axes.numlegend`, :py:meth:`ultraplot.axes.Axes.geolegend`, :py:meth:`ultraplot.figure.Figure.entrylegend`, :py:meth:`ultraplot.figure.Figure.catlegend`, :py:meth:`ultraplot.figure.Figure.sizelegend`, :py:meth:`ultraplot.figure.Figure.numlegend`, :py:meth:`ultraplot.figure.Figure.geolegend`.
+
+See also
+--------
+* :doc:`Colorbars and legends </colorbars_legends>`
+"""
+
+# %%
+# Semantic Legend with custom markers and advanced styles
+import matplotlib.transforms as mtransforms
+import numpy as np
+from matplotlib.markers import CapStyle, JoinStyle, MarkerStyle
+from matplotlib.path import Path
+
+import ultraplot as uplt
+
+star = Path.unit_regular_star(6)
+circle = Path.unit_circle()
+star_path = Path.unit_regular_star(5)
+cut_star = Path(
+    vertices=np.concatenate([circle.vertices, star.vertices[::-1, ...]]),
+    codes=np.concatenate([circle.codes, star.codes]),
+)
+
+fig, ax = uplt.subplots()
+
+# upper left legend with custom mark
+ax.catlegend(
+    ["star", "cus_star"],
+    marker=[star_path, cut_star],
+    markersize=10,
+    add=True,
+    loc="ul",
+    title="Paths",
+    ncols=1,
+)
+
+# upper right legend with advanced CapStyle and JoinStyle
+ax.catlegend(
+    ["butt / round", "round / miter", "projecting / bevel"],
+    marker="1",
+    markersize=10,
+    markeredgecolor=list("gbr"),
+    markeredgewidth=4,
+    markerfacecoloralt="none",
+    marker_capstyle=[
+        CapStyle.butt,
+        CapStyle.round,
+        CapStyle.projecting,
+    ],
+    marker_joinstyle=[
+        JoinStyle.round,
+        JoinStyle.miter,
+        JoinStyle.bevel,
+    ],
+    marker_transform=[mtransforms.Affine2D().rotate_deg(x) for x in [0, 30, 60]],
+    title="Cap & Join Style",
+    add=True,
+    loc="ur",
+    ncols=1,
+)
+
+# center geolegend with different styles
+ax.geolegend(
+    ["rect", "tri", "hex", "AU"],
+    facecolor=["tab:red", "r", "k", "tab:blue"],
+    ec=["k", "g", "orange", "bright pink"],
+    loc="c",
+    title="geolegend",
+    ew=[0.5, 2, 1, 0.5],
+    markersize=10,
+    ncols=4,
+    handletextpad=0.1,
+    columnspacing=0.7,
+)
+
+# lower left legend with TeX symbols and rotation transform
+ax.catlegend(
+    ["\\infty", "\\sum", "\\int"],
+    marker=[r"$\infty$", r"$\sum$", r"$\int$"],
+    s=[6, 18, 9],  # ms/markersize=[6,8,10]
+    title="TeX symbols\nwith rotation",
+    marker_transform=[mtransforms.Affine2D().rotate_deg(x) for x in [30, 90, 45]],
+    add=True,
+    loc="ll",
+    ncols=1,
+)
+
+# lower right legend with different fill style
+ax.catlegend(
+    ["top", "bottom", "left", "right"],
+    marker="o",
+    markersize=10,
+    mfc=["r", "g", "b", "c"],
+    markerfacecoloralt="lightsteelblue",
+    markeredgecolor=["k", "r", "y", "b"],
+    fillstyle=["top", "bottom", "left", "right"],
+    title="Half filled",
+    add=True,
+    loc="lr",
+    ncols=1,
+)
+ax.axis("off")
+fig.show()
+
+
+# %%
+import cartopy.crs as ccrs
+import shapely.geometry as sg
+
+import ultraplot as uplt
+
+fig, ax = uplt.subplots(refwidth=5.0)
+ax.format(title="Semantic legend helpers")
+
+ax.entrylegend(
+    [
+        {
+            "label": "Observed samples",
+            "line": False,
+            "marker": "o",
+            "markersize": 8,
+            "markerfacecolor": "blue7",
+            "markeredgecolor": "black",
+        },
+        {
+            "label": "Model fit",
+            "line": True,
+            "color": "black",
+            "linewidth": 2.5,
+            "linestyle": "--",
+        },
+    ],
+    loc="l",
+    title="Entry styles",
+    frameon=False,
+)
+ax.catlegend(
+    ["A", "B", "C"],
+    colors={"A": "red7", "B": "green7", "C": "blue7"},
+    markers={"A": "o", "B": "s", "C": "^"},
+    loc="top",
+    frameon=False,
+)
+ax.sizelegend(
+    [10, 50, 200],
+    labels=["Small", "Medium", "Large"],
+    loc="upper right",
+    title="Population",
+    ncols=1,
+    frameon=False,
+)
+ax.numlegend(
+    vmin=0,
+    vmax=1,
+    n=5,
+    cmap="viko",
+    fmt="{:.2f}",
+    loc="ll",
+    ncols=1,
+    frameon=False,
+)
+
+poly1 = sg.Polygon([(0, 0), (2, 0), (1.2, 1.4)])
+ax.geolegend(
+    [
+        ("Triangle", "triangle"),
+        ("Triangle-ish", poly1),
+        ("Australia", "country:AU"),
+        ("Netherlands (Mercator)", "country:NLD", "mercator"),
+        (
+            "Netherlands (Lambert)",
+            "country:NLD",
+            {
+                "country_proj": ccrs.LambertConformal(
+                    central_longitude=5,
+                    central_latitude=52,
+                ),
+                "country_reso": "10m",
+                "country_territories": False,
+                "facecolor": "steelblue",
+                "fill": True,
+            },
+        ),
+    ],
+    loc="r",
+    ncols=1,
+    handlesize=2.4,
+    handletextpad=0.35,
+    frameon=False,
+    country_reso="10m",
+)
+ax.axis("off")
+fig.show()
+
+# %%
+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")
+
+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,
+)
+fig.show()

ultraplot-2.3.0/ultraplot/_version.py

@@ -0,0 +1 @@
+__version__ = '2.3.0'