ENH: Support units when specifying the figsize

Reviving the spirit of matplotlib#12402 and matplotlib#12415, because both had significant user votes on GitHub.

This PR is intentionally minimal to only expand the `figsize` parameter when creating a figure. This should be the most relevant use case. Later changing the figure size or reading it is probably less necessary. The minimal approach removes the need to track and return sizes. It is just an enhanced specification capability which directly parses to the internally used inch unit.

Author: timhoffm

lib/matplotlib/figure.py

@@ -2419,6 +2419,47 @@ def draw(self, renderer):
             self.stale = False
 
 
+def _parse_figsize(figsize, dpi):
+    """
+    Convert a figsize expression to (width, height) in inches.
+
+    Parameters
+    ----------
+    figsize : (float, float) or (float, float, str)
+        This can be
+
+        - a tuple ``(width, height, unit)``, where *unit* is one of "inch", "cm",
+          "px".
+        - a tuple ``(x, y)``, which is interpreted as ``(x, y, "inch")``.
+
+    dpi : float
+        The dots-per-inch; used for converting 'px' to 'inch'.
+    """
+    num_parts = len(figsize)
+    if num_parts == 2:
+        return figsize
+    elif num_parts == 3:
+        x, y, unit = figsize
+        if unit == 'inch':
+            pass
+        elif unit == 'cm':
+            x /= 2.54
+            y /= 2.54
+        elif unit == 'px':
+            x /= dpi
+            y /= dpi
+        else:
+            raise ValueError(
+                "The unit part of 'figsize' must be one of 'inch', 'cm', 'px', but "
+                f"found {unit!r}"
+            )
+        return x, y
+    else:
+        raise ValueError(
+            "Invalid figsize format, expected (x, y) or (x, y, unit) but got "
+            f"{figsize!r}"
+        )
+
 @_docstring.interpd
 class Figure(FigureBase):
     """
@@ -2476,8 +2517,12 @@ def __init__(self,
         """
         Parameters
         ----------
-        figsize : 2-tuple of floats, default: :rc:`figure.figsize`
-            Figure dimension ``(width, height)`` in inches.
+        figsize : (float, float) or (float, float, str), default: :rc:`figure.figsize`
+            The figure dimensions. This can be
+
+            - a tuple ``(width, height, unit)``, where *unit* is one of "inch", "cm",
+              "px".
+            - a tuple ``(x, y)``, which is interpreted as ``(x, y, "inch")``.
 
         dpi : float, default: :rc:`figure.dpi`
             Dots per inch.
@@ -2613,6 +2658,8 @@ def __init__(self,
         edgecolor = mpl._val_or_rc(edgecolor, 'figure.edgecolor')
         frameon = mpl._val_or_rc(frameon, 'figure.frameon')
 
+        figsize = _parse_figsize(figsize, dpi)
+
         if not np.isfinite(figsize).all() or (np.array(figsize) < 0).any():
             raise ValueError('figure size must be positive finite not '
                              f'{figsize}')

lib/matplotlib/figure.pyi

@@ -305,6 +305,11 @@ class SubFigure(FigureBase):
     def axes(self) -> list[Axes]: ...  # type: ignore[override]
     def get_axes(self) -> list[Axes]: ...
 
+def _parse_figsize(
+    figsize: tuple[float, float] | tuple[float, float, Literal["inch", "cm", "px"]],
+    dpi: float
+) -> tuple[float, float] = ...
+
 class Figure(FigureBase):
     @property
     def figure(self) -> Figure: ...
@@ -318,7 +323,7 @@ class Figure(FigureBase):
     subplotpars: SubplotParams
     def __init__(
         self,
-        figsize: tuple[float, float] | None = ...,
+        figsize: tuple[float, float] | tuple[float, float, str] | None = ...,
         dpi: float | None = ...,
         *,
         facecolor: ColorType | None = ...,

lib/matplotlib/pyplot.py

@@ -876,7 +876,7 @@ def figure(
     # autoincrement if None, else integer from 1-N
     num: int | str | Figure | SubFigure | None = None,
     # defaults to rc figure.figsize
-    figsize: tuple[float, float] | None = None,
+    figsize: tuple[float, float] | tuple[float, float, Literal["inch", "cm", "px"]] | None = None,
     # defaults to rc figure.dpi
     dpi: float | None = None,
     *,
@@ -909,8 +909,12 @@ def figure(
         window title is set to this value.  If num is a ``SubFigure``, its
         parent ``Figure`` is activated.
 
-    figsize : (float, float), default: :rc:`figure.figsize`
-        Width, height in inches.
+    figsize : (float, float) or (float, float, str), default: :rc:`figure.figsize`
+        The figure dimensions. This can be
+
+        - a tuple ``(width, height, unit)``, where *unit* is one of "inch", "cm",
+          "px".
+        - a tuple ``(x, y)``, which is interpreted as ``(x, y, "inch")``.
 
     dpi : float, default: :rc:`figure.dpi`
         The resolution of the figure in dots-per-inch.

lib/matplotlib/tests/test_figure.py

@@ -16,14 +16,23 @@
 from matplotlib.testing.decorators import image_comparison, check_figures_equal
 from matplotlib.axes import Axes
 from matplotlib.backend_bases import KeyEvent, MouseEvent
-from matplotlib.figure import Figure, FigureBase
+from matplotlib.figure import _parse_figsize, Figure, FigureBase
 from matplotlib.layout_engine import (ConstrainedLayoutEngine,
                                       TightLayoutEngine,
                                       PlaceHolderLayoutEngine)
 from matplotlib.ticker import AutoMinorLocator, FixedFormatter, ScalarFormatter
 import matplotlib.pyplot as plt
 import matplotlib.dates as mdates
 
+@pytest.mark.parametrize("input, output", [
+    ((6, 4), (6, 4)),
+    ((6, 4, "inch"), (6, 4)),
+    ((5.08, 2.54, "cm"), (2, 1)),
+    ((600, 400, "px"), (6, 4)),
+])
+def test__parse_figsize(input, output):
+    assert _parse_figsize(input, dpi=100) == output
+
 
 @image_comparison(['figure_align_labels'], extensions=['png', 'svg'],
                   tol=0 if platform.machine() == 'x86_64' else 0.01)