ultraplot 2.4.0__tar.gz → 2.5.0__tar.gz

{ultraplot-2.4.0 → ultraplot-2.5.0}/.github/workflows/publish-pypi.yml

@@ -121,6 +121,11 @@ jobs:
           verbose: true
           skip-existing: true
 
+  # NOTE: Publishing this release is what triggers the Zenodo archive. Zenodo's
+  # GitHub integration webhooks the 'release: published' event and mints a new
+  # version under the concept DOI in CITATION.cff -- no job, token, or API call
+  # of ours is involved. The integration only sees releases published *after* it
+  # was enabled, so it never backfills.
   publish-github-release:
     name: Publish GitHub release
     needs: publish-pypi
@@ -133,52 +138,3 @@ jobs:
         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@v7
-  #       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.5.0/.zenodo.json

@@ -0,0 +1,30 @@
+{
+  "upload_type": "software",
+  "title": "UltraPlot",
+  "description": "A succinct matplotlib wrapper for making beautiful, publication-quality graphics.",
+  "creators": [
+    {
+      "name": "van Elteren, Casper",
+      "orcid": "0000-0001-9862-8936"
+    },
+    {
+      "name": "Becker, Matthew R.",
+      "orcid": "0000-0001-7774-2246"
+    }
+  ],
+  "license": "mit",
+  "access_right": "open",
+  "keywords": [
+    "plotting",
+    "matplotlib",
+    "scientific visualization",
+    "wrapper"
+  ],
+  "related_identifiers": [
+    {
+      "identifier": "https://github.com/Ultraplot/UltraPlot",
+      "relation": "isSupplementTo",
+      "scheme": "url"
+    }
+  ]
+}

{ultraplot-2.4.0 → ultraplot-2.5.0}/CITATION.cff

@@ -8,8 +8,12 @@ authors:
   - family-names: "Becker"
     given-names: "Matthew R."
     orcid: "https://orcid.org/0000-0001-7774-2246"
-date-released: "2026-03-30"
-version: "2.1.5"
+# NOTE: Deliberately no 'version' or 'date-released'. The package version comes
+# from the git tag via setuptools_scm, and Zenodo's GitHub integration takes the
+# version and publication date from the release itself. Pinning them here means
+# hand-editing this file on every release, which is how it drifted to 2.1.5 while
+# the project shipped 2.4.0. The DOI below is the *concept* DOI: it is stable
+# across releases and always resolves to the latest version.
 doi: "10.5281/zenodo.15733564"
 repository-code: "https://github.com/Ultraplot/UltraPlot"
 license: "MIT"

{ultraplot-2.4.0/ultraplot.egg-info → ultraplot-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ultraplot
-Version: 2.4.0
+Version: 2.5.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.4.0 → ultraplot-2.5.0}/docs/api.rst

@@ -133,6 +133,16 @@ Demo functions
    :toctree: api
 
 
+Text alignment
+==============
+
+.. automodule:: ultraplot.textalign
+   :no-private-members:
+
+.. automodsumm:: ultraplot.textalign
+   :toctree: api
+
+
 Miscellaneous functions
 =======================
 

{ultraplot-2.4.0 → ultraplot-2.5.0}/docs/fonts.py

@@ -100,6 +100,88 @@ fig, axs = uplt.show_fonts(family="tex-gyre")
 # :rcraw:`mathtext.fontset` back to one of matplotlib's math-specialized font sets
 # (e.g., ``'stixsans'`` or ``'dejavusans'``).
 #
+# In short, math fonts can be tailored to taste at three levels, depending on
+# how much of the "LaTeX look" you want:
+#
+# #. **Match the document font** (the default). With the ``'custom'`` font set,
+#    math follows the active text font -- including fonts assigned to
+#    individual text objects, as demonstrated below.
+# #. **Computer Modern symbols**. Keep the active font for letters and numbers
+#    but render ``\mathcal`` and big operators with authentic Computer Modern
+#    glyphs by setting :rcraw:`mathtext.cm_symbols` to ``True``
+#    (see :ref:`below <ug_fonts_cm>`).
+# #. **Full LaTeX**. Set matplotlib's :rcraw:`text.usetex` to ``True`` to
+#    delegate all text rendering to an external LaTeX installation. This gives
+#    complete LaTeX typesetting but is much slower and requires TeX on your
+#    system -- with the previous two options it is rarely necessary.
+#
+# The example below demonstrates the first level: the same expression rendered
+# with different fonts assigned per text object.
+
+# %%
+import ultraplot as uplt
+
+expr = (
+    r"$\mathcal{ABCXYZ}\quad"
+    r"\sum_{i=0}^{n}\quad"
+    r"\prod_{j=1}^{m}\quad"
+    r"\int_a^b\quad"
+    r"\oint_C$"
+)
+
+fig, axs = uplt.subplots(nrows=3, refwidth=6, refheight=1.1, share=False, span=False)
+for ax, font in zip(axs, ("TeX Gyre Heros", "Fira Math", "DejaVu Sans")):
+    ax.text(0.02, 0.5, expr, transform="axes", va="center", fontsize=24, fontname=font)
+    ax.format(title=font, titleloc="left")
+axs.format(xlocator="null", ylocator="null", xspineloc="none", yspineloc="none")
+
+# %% [raw] raw_mimetype="text/restructuredtext"
+#
+# .. _ug_fonts_cm:
+#
+# Computer Modern symbols
+# ^^^^^^^^^^^^^^^^^^^^^^^
+#
+# If you want to retain the active alphabet and number fonts while using
+# Computer Modern for selected LaTeX-style symbols, set :rcraw:`mathtext.cm_symbols`
+# to ``True``. This routes ``\mathcal`` through ``cmsy10`` and big operators like
+# ``\sum``, ``\prod``, ``\int``, ``\oint``, ``\bigcup``, and ``\bigoplus`` through
+# ``cmex10``. This does not affect ordinary letters and numbers, and it does not
+# provide a Computer Modern ``\mathfrak`` font because matplotlib's bundled
+# mathtext fonts do not include one. Note that math text is parsed when the
+# figure is *drawn*, so the setting must be active at draw time -- assign it
+# globally rather than wrapping plotting commands in a context block.
+
+# %%
+fig, ax = uplt.subplots(refwidth=6, refheight=1.1)
+ax.text(0.02, 0.5, expr, transform="axes", va="center", fontsize=24)
+ax.format(
+    title="Default custom math text",
+    titleloc="left",
+    xlocator="null",
+    ylocator="null",
+    xspineloc="none",
+    yspineloc="none",
+)
+
+# %%
+uplt.rc["mathtext.cm_symbols"] = True
+fig, ax = uplt.subplots(refwidth=6, refheight=1.1)
+ax.text(0.02, 0.5, expr, transform="axes", va="center", fontsize=24)
+ax.format(
+    title="Computer Modern math symbols",
+    titleloc="left",
+    xlocator="null",
+    ylocator="null",
+    xspineloc="none",
+    yspineloc="none",
+)
+
+# %%
+uplt.rc["mathtext.cm_symbols"] = False  # restore the default
+
+# %% [raw] raw_mimetype="text/restructuredtext"
+#
 # A table of math text containing the sans-serif fonts packaged with UltraPlot is shown
 # below. The dummy glyph "¤" is shown where a given math character is unavailable
 # for a particular font (in practice, the fallback font :rc:`mathtext.fallback` is used

{ultraplot-2.4.0 → ultraplot-2.5.0}/docs/insets_panels.py

@@ -88,8 +88,8 @@ fig.format(
 )
 
 # %%
-import ultraplot as uplt
 import numpy as np
+import ultraplot as uplt
 
 state = np.random.RandomState(51423)
 data = (state.rand(20, 20) - 0.48).cumsum(axis=1).cumsum(axis=0)
@@ -192,3 +192,74 @@ ix = ax.inset(
 )
 ix.format(xlim=(2, 4), ylim=(2, 4), color="red8", linewidth=1.5, ticklabelweight="bold")
 ix.pcolormesh(data, cmap="Grays", levels=N, inbounds=False)
+
+# %% [raw] raw_mimetype="text/restructuredtext"
+# Hawkeye map insets
+# ~~~~~~~~~~~~~~~~~~
+#
+# :class:`~ultraplot.axes.GeoAxes` adds :meth:`~ultraplot.axes.GeoAxes.hawkeye`
+# for geographic callout maps. The inset is anchored at ``xy`` in a parent coordinate
+# system, and its ``size`` is a fraction of the parent axes. Supply ``extent`` to set
+# the inset map scope and draw a matching indicator and optional connectors on the
+# parent map. Hawkeyes are excluded from automatic layout, so they can extend beyond
+# the parent axes without reserving subplot space.
+#
+# Rectangular hawkeyes preserve both the requested extent and projection scale. A
+# circular frame cannot simultaneously preserve projection scale and display an exact
+# non-square extent. Circular hawkeyes therefore expand the shorter projected dimension
+# to retain the projection; use a square extent when the exact circular map scope is
+# important, or pass ``aspect='auto'`` to fit the exact extent with distortion.
+#
+# The following dependency-free example shows a Singapore city locator on a world map.
+# The returned inset is an ordinary geographic axes, so optional geospatial libraries
+# can draw external data inside it. For example, `OSMnx <https://osmnx.readthedocs.io/>`__
+# can provide street geometry when it is installed separately:
+#
+# .. code-block:: python
+#
+#    import osmnx as ox
+#    from cartopy import crs as ccrs
+#
+#    network = ox.graph_from_point((1.3521, 103.8198), dist=8_000, network_type="drive")
+#    streets = ox.graph_to_gdfs(network, nodes=False)
+#    streets.plot(ax=inax, color="0.3", linewidth=0.4, transform=ccrs.PlateCarree())
+#
+# The data download and OpenStreetMap attribution are the responsibility of the
+# application using that optional integration.
+
+# %%
+singapore = (103.8198, 1.3521)
+fig, ax = uplt.subplots(proj="robin", refwidth=4)
+ax.format(land=True, landcolor="gray8", oceancolor="blue9")
+ax.plot(
+    *singapore,
+    marker="o",
+    color="red",
+    markeredgecolor="white",
+    markeredgewidth=0.8,
+    ms=5,
+    transform="cyl",
+)
+ax.text(106, 4, "Singapore", color="red", size=7, transform="map")
+inax = ax.hawkeye(
+    (0.97, 0.97),
+    size=0.23,
+    anchor="ur",
+    proj="merc",
+    extent=(103.76, 103.90, 1.27, 1.41),
+    shape="circle",
+    target="circle",
+    connector="line",
+    color="red",
+    indicator_kw={"linewidth": 1.5},
+)
+inax.format(land=True, landcolor="gray9", oceancolor="blue9")
+inax.plot(
+    *singapore,
+    marker="o",
+    color="red",
+    markeredgecolor="white",
+    markeredgewidth=0.8,
+    ms=5,
+    transform="cyl",
+)

{ultraplot-2.4.0 → ultraplot-2.5.0}/docs/projections.py

@@ -516,6 +516,60 @@ fig.format(
 )
 
 
+# %% [raw] raw_mimetype="text/restructuredtext"
+# .. _ug_geo_layout:
+#
+# Geographic axes in mixed subplot layouts
+# -----------------------------------------
+#
+# Geographic axes preserve the aspect ratio required by their projection. This is
+# important for interpreting distances and shapes correctly, but it creates a layout
+# choice when a map shares a GridSpec with Cartesian axes or maps that have a different
+# natural aspect ratio. A fixed-aspect map cannot both fill a differently shaped subplot
+# slot *and* preserve its projection geometry.
+#
+# By default, UltraPlot preserves the map aspect. If the slot is a different shape, the
+# visible map is centered inside it. This keeps the map accurate, but decorations attached
+# to the visible map boundary can stop lining up with decorations on neighboring subplots.
+# For example, the following uses ``abcanchor='slot'`` to attach the map's a-b-c label to
+# its unadjusted GridSpec slot instead. The map itself remains aspect-faithful.
+
+# %%
+import ultraplot as uplt
+
+layout = [[1, 1, 1, 2, 2, 2], [3, 3, 4, 4, 5, 5]]
+fig, axs = uplt.subplots(layout, refwidth=2.4, proj={4: "cyl"}, share=False)
+axs[3].format(
+    lonlim=(0, 1),
+    latlim=(0, 1),
+    abcanchor="slot",  # align its a-b-c label with the Cartesian subplot slots
+)
+fig.format(abc="A.", abcloc="left")
+
+
+# %% [raw] raw_mimetype="text/restructuredtext"
+# ``abcanchor`` has two modes:
+#
+# * ``'axes'`` (the default) attaches the label to the visible map boundary. This is
+#   usually best when the map is the visual focus.
+# * ``'slot'`` attaches it to the original GridSpec slot. This is useful when labels
+#   should form a regular grid across mixed subplot types.
+#
+# There are two other deliberate trade-offs, depending on what the figure needs:
+#
+# * Use ``aspect='auto'`` with :meth:`~ultraplot.axes.GeoAxes.format` to stretch a map
+#   to fill its slot. This preserves the GridSpec geometry but distorts the projection,
+#   so it is generally unsuitable when geographic shape or scale matters.
+# * Make the map the layout reference with ``ref=4`` in the above call to
+#   :func:`~ultraplot.ui.subplots`. UltraPlot then resizes the overall figure so that
+#   the map fills its slot while retaining its aspect. This is useful when the map,
+#   rather than the Cartesian axes, should determine the figure geometry.
+#
+# If none of these trade-offs is appropriate, change the map extent so that its natural
+# aspect better matches the intended GridSpec slot. That preserves projection geometry,
+# but necessarily changes the plotted geographic domain.
+
+
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_zoom:
 #

{ultraplot-2.4.0 → ultraplot-2.5.0}/docs/subplots.py

@@ -395,6 +395,14 @@ for (name1, equal), (name2, group) in zip(equals, groups):
 #    Explicit sharing levels still force sharing attempts and may warn when
 #    incompatible axes are encountered.
 #
+# When figure-level row or column labels and a shared spanning axis label use
+# the same side, the row or column labels are placed nearer the axes and the
+# spanning label is placed outside them. Control this gap with the
+# :rc:`leftlabel.sharedpad`, :rc:`rightlabel.sharedpad`,
+# :rc:`bottomlabel.sharedpad`, and :rc:`toplabel.sharedpad` settings. These
+# can also be passed to ``format`` without periods; for example,
+# ``fig.format(leftlabelsharedpad='2em')``.
+#
 # The below examples demonstrate the effect of various axis and label sharing
 # settings on the appearance of several subplot grids.
 

{ultraplot-2.4.0 → ultraplot-2.5.0}/pyproject.toml

@@ -66,6 +66,7 @@ exclude = ["**/*.ipynb"]
 
 [tool.pytest.ini_options]
 filterwarnings = [
+    "ignore:'parseString' deprecated - use 'parse_string':DeprecationWarning:matplotlib._fontconfig_pattern",
     "ignore:'resetCache' deprecated - use 'reset_cache':DeprecationWarning:matplotlib._fontconfig_pattern",
 ]
 mpl-default-style = { axes.prop_cycle = "cycler('color', ['#4c72b0ff', '#55a868ff', '#c44e52ff', '#8172b2ff', '#ccb974ff', '#64b5cdff'])" }

{ultraplot-2.4.0 → ultraplot-2.5.0}/ultraplot/__init__.py

@@ -101,6 +101,7 @@ if TYPE_CHECKING:
     from .scale import SineLatitudeScale as SineLatitudeScale
     from .scale import SymmetricalLogScale as SymmetricalLogScale
     from .text import CurvedText as CurvedText
+    from .textalign import align_text as align_text
     from .ultralayout import ColorbarLayoutSolver as ColorbarLayoutSolver
     from .ultralayout import compute_ultra_positions as compute_ultra_positions
     from .ultralayout import get_grid_positions_ultra as get_grid_positions_ultra