Feature: Add container to encapsulate external axes (#422)

* Fix references in documentation for clarity

Fix two unidenfined references in why.rst.
1. ug_apply_norm is a typo I think.
2. ug_mplrc. I'm not sure what it should be. Only by guess.

* keep apply_norm

* Add container class to wrap external axes objects

* remove v1

* fix test_geographic_multiple_projections

* fixes

* add container tests

* fix merge issue

* correct rebase

* fix mpl39 issue

* fix double draw in repl

* Improve external axes container layout for native appearance

- Increase default shrink factor from 0.75 to 0.95 to make external axes (e.g., ternary plots) larger and more prominent
- Change positioning from centered to top-aligned with left offset for better alignment with adjacent Cartesian subplots
- Top alignment ensures abc labels and titles align properly across different projection types
- Add 5% left offset to better utilize available horizontal space
- Update both _shrink_external_for_labels and _ensure_external_fits_within_container methods for consistency

This makes ternary and other external axes integrate seamlessly with standard matplotlib subplots, appearing native rather than artificially constrained.

* Handle non-numeric padding conversion

* adjust test

* Add coverage for external axes container

* Expand external container test coverage

* this works

* Adjust mpltern default shrink

* Add mpltern container shrink tests

* Document external axes containers

* adding more tests

* tests

* Fix merge

---------

Co-authored-by: Gepcel <gepcelway@gmail.com>
Co-authored-by: Matthew R. Becker <beckermr@users.noreply.github.com>

Author: 3 people

.gitignore

@@ -22,6 +22,7 @@ docs/_build
 docs/_static/ultraplotrc
 docs/_static/rctable.rst
 docs/_static/*
+*.html
 docs/gallery/
 docs/sg_execution_times.rst
 docs/whats_new.rst
@@ -36,7 +37,8 @@ sources
 *.pyc
 .*.pyc
 __pycache__
-test.py
+*.ipynb
+
 
 # OS files
 .DS_Store

docs/usage.rst

@@ -158,6 +158,48 @@ plotting packages.
 Since these features are optional,
 UltraPlot can be used without installing any of these packages.
 
+External axes containers (mpltern, others)
+------------------------------------------
+
+UltraPlot can wrap third-party Matplotlib projections (e.g., ``mpltern``'s
+``"ternary"`` projection) in a lightweight container. The container keeps
+UltraPlot's figure/labeling behaviors while delegating plotting calls to the
+external axes.
+
+Basic usage mirrors standard subplots:
+
+.. code-block:: python
+
+   import mpltern
+   import ultraplot as uplt
+
+   fig, axs = uplt.subplots(ncols=2, projection="ternary")
+   axs.format(title="Ternary example", abc=True, abcloc="left")
+   axs[0].plot([0.1, 0.7, 0.2], [0.2, 0.2, 0.6], [0.7, 0.1, 0.2])
+   axs[1].scatter([0.2, 0.3], [0.5, 0.4], [0.3, 0.3])
+
+Controlling the external content size
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use ``external_shrink_factor`` (or the rc setting ``external.shrink``) to
+shrink the *external* axes inside the container, creating margin space for
+titles and annotations without resizing the subplot itself:
+
+.. code-block:: python
+
+   uplt.rc["external.shrink"] = 0.8
+   fig, axs = uplt.subplots(projection="ternary")
+   axs.format(external_shrink_factor=0.7)
+
+Notes and performance
+~~~~~~~~~~~~~~~~~~~~~
+
+* Titles and a-b-c labels are rendered by the container, not the external axes,
+  so they behave like normal UltraPlot subplots.
+* For mpltern with ``external_shrink_factor < 1``, UltraPlot skips the costly
+  tight-bbox fitting pass and relies on the shrink factor for layout. This
+  keeps rendering fast and stable.
+
 .. _usage_features:
 
 Additional features

pyproject.toml

@@ -51,7 +51,9 @@ include-package-data = true
 write_to = "ultraplot/_version.py"
 write_to_template = "__version__ = '{version}'\n"
 
+
+[tool.ruff]
+ignore = ["I001", "I002", "I003", "I004"]
+
 [tool.basedpyright]
-exclude = [
-    "**/*.ipynb"
-]
+exclude = ["**/*.ipynb"]

ultraplot/axes/__init__.py

@@ -7,8 +7,12 @@
 from ..internals import context
 from .base import Axes  # noqa: F401
 from .cartesian import CartesianAxes
-from .geo import GeoAxes  # noqa: F401
-from .geo import _BasemapAxes, _CartopyAxes
+from .container import ExternalAxesContainer  # noqa: F401
+from .geo import (
+    GeoAxes,  # noqa: F401
+    _BasemapAxes,
+    _CartopyAxes,
+)
 from .plot import PlotAxes  # noqa: F401
 from .polar import PolarAxes
 from .shared import _SharedAxes  # noqa: F401
@@ -22,6 +26,7 @@
     "PolarAxes",
     "GeoAxes",
     "ThreeAxes",
+    "ExternalAxesContainer",
 ]
 
 # Register projections with package prefix to avoid conflicts

ultraplot/axes/base.py

@@ -967,7 +967,18 @@ def _add_inset_axes(
         zoom = ax._inset_zoom = _not_none(zoom, zoom_default)
         if zoom:
             zoom_kw = zoom_kw or {}
-            ax.indicate_inset_zoom(**zoom_kw)
+            # Check if the inset axes is an Ultraplot axes class.
+            # Ultraplot axes have a custom indicate_inset_zoom that can be
+            # called on the inset itself (uses self._inset_parent internally).
+            # Non-Ultraplot axes (e.g., raw matplotlib/cartopy) require calling
+            # matplotlib's indicate_inset_zoom on the parent with the inset as first argument.
+            if isinstance(ax, Axes):
+                # Ultraplot axes: call on inset (uses self._inset_parent internally)
+                ax.indicate_inset_zoom(**zoom_kw)
+            else:
+                # Non-Ultraplot axes: call matplotlib's parent class method
+                # with inset as first argument (matplotlib API)
+                maxes.Axes.indicate_inset_zoom(self, ax, **zoom_kw)
         return ax
 
     def _add_queued_guides(self):
@@ -2588,7 +2599,20 @@ def _range_subplotspec(self, s):
         if not isinstance(self, maxes.SubplotBase):
             raise RuntimeError("Axes must be a subplot.")
         ss = self.get_subplotspec().get_topmost_subplotspec()
-        row1, row2, col1, col2 = ss._get_rows_columns()
+
+        # Check if this is an ultraplot SubplotSpec with _get_rows_columns method
+        if not hasattr(ss, "_get_rows_columns"):
+            # Fall back to standard matplotlib SubplotSpec attributes
+            # This can happen when axes are created directly without ultraplot's gridspec
+            if hasattr(ss, "rowspan") and hasattr(ss, "colspan"):
+                row1, row2 = ss.rowspan.start, ss.rowspan.stop - 1
+                col1, col2 = ss.colspan.start, ss.colspan.stop - 1
+            else:
+                # Unable to determine range, return default
+                row1, row2, col1, col2 = 0, 0, 0, 0
+        else:
+            row1, row2, col1, col2 = ss._get_rows_columns()
+
         if s == "x":
             return (col1, col2)
         else: