[Feature] Add container to encapsulate external axes

.gitignore

@@ -22,6 +22,7 @@ docs/_build
 docs/_static/ultraplotrc
 docs/_static/rctable.rst
 docs/_static/*
+*.html
 
 # Development subfolders
 dev
@@ -33,6 +34,8 @@ sources
 *.pyc
 .*.pyc
 __pycache__
+*.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

@@ -50,3 +50,10 @@ include-package-data = true
 [tool.setuptools_scm]
 write_to = "ultraplot/_version.py"
 write_to_template = "__version__ = '{version}'\n"
+
+
+[tool.ruff]
+ignore = ["I001", "I002", "I003", "I004"]
+
+[tool.basedpyright]
+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

@@ -963,7 +963,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):
@@ -2662,7 +2673,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: