Initial configuration commit

typings/matplotlib/_constrained_layout.pyi

@@ -0,0 +1,233 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+"""
+Adjust subplot layouts so that there are no overlapping axes or axes
+decorations.  All axes decorations are dealt with (labels, ticks, titles,
+ticklabels) and some dependent artists are also dealt with (colorbar,
+suptitle).
+
+Layout is done via `~matplotlib.gridspec`, with one constraint per gridspec,
+so it is possible to have overlapping axes if the gridspecs overlap (i.e.
+using `~matplotlib.gridspec.GridSpecFromSubplotSpec`).  Axes placed using
+``figure.subplots()`` or ``figure.add_subplots()`` will participate in the
+layout.  Axes manually placed via ``figure.add_axes()`` will not.
+
+See Tutorial: :ref:`constrainedlayout_guide`
+
+General idea:
+-------------
+
+First, a figure has a gridspec that divides the figure into nrows and ncols,
+with heights and widths set by ``height_ratios`` and ``width_ratios``,
+often just set to 1 for an equal grid.
+
+Subplotspecs that are derived from this gridspec can contain either a
+``SubPanel``, a ``GridSpecFromSubplotSpec``, or an ``Axes``.  The ``SubPanel``
+and ``GridSpecFromSubplotSpec`` are dealt with recursively and each contain an
+analogous layout.
+
+Each ``GridSpec`` has a ``_layoutgrid`` attached to it.  The ``_layoutgrid``
+has the same logical layout as the ``GridSpec``.   Each row of the grid spec
+has a top and bottom "margin" and each column has a left and right "margin".
+The "inner" height of each row is constrained to be the same (or as modified
+by ``height_ratio``), and the "inner" width of each column is
+constrained to be the same (as modified by ``width_ratio``), where "inner"
+is the width or height of each column/row minus the size of the margins.
+
+Then the size of the margins for each row and column are determined as the
+max width of the decorators on each axes that has decorators in that margin.
+For instance, a normal axes would have a left margin that includes the
+left ticklabels, and the ylabel if it exists.  The right margin may include a
+colorbar, the bottom margin the xaxis decorations, and the top margin the
+title.
+
+With these constraints, the solver then finds appropriate bounds for the
+columns and rows.  It's possible that the margins take up the whole figure,
+in which case the algorithm is not applied and a warning is raised.
+
+See the tutorial :ref:`constrainedlayout_guide`
+for more discussion of the algorithm with examples.
+"""
+_log = ...
+def do_constrained_layout(fig, h_pad, w_pad, hspace=..., wspace=..., rect=..., compress=...): # -> dict[Unknown, Unknown] | None:
+    """
+    Do the constrained_layout.  Called at draw time in
+     ``figure.constrained_layout()``
+
+    Parameters
+    ----------
+    fig : `~matplotlib.figure.Figure`
+        `.Figure` instance to do the layout in.
+
+    h_pad, w_pad : float
+      Padding around the axes elements in figure-normalized units.
+
+    hspace, wspace : float
+       Fraction of the figure to dedicate to space between the
+       axes.  These are evenly spread between the gaps between the axes.
+       A value of 0.2 for a three-column layout would have a space
+       of 0.1 of the figure width between each column.
+       If h/wspace < h/w_pad, then the pads are used instead.
+
+    rect : tuple of 4 floats
+        Rectangle in figure coordinates to perform constrained layout in
+        [left, bottom, width, height], each from 0-1.
+
+    compress : bool
+        Whether to shift Axes so that white space in between them is
+        removed. This is useful for simple grids of fixed-aspect Axes (e.g.
+        a grid of images).
+
+    Returns
+    -------
+    layoutgrid : private debugging structure
+    """
+    ...
+
+def make_layoutgrids(fig, layoutgrids, rect=...): # -> dict[Unknown, Unknown]:
+    """
+    Make the layoutgrid tree.
+
+    (Sub)Figures get a layoutgrid so we can have figure margins.
+
+    Gridspecs that are attached to axes get a layoutgrid so axes
+    can have margins.
+    """
+    ...
+
+def make_layoutgrids_gs(layoutgrids, gs):
+    """
+    Make the layoutgrid for a gridspec (and anything nested in the gridspec)
+    """
+    ...
+
+def check_no_collapsed_axes(layoutgrids, fig): # -> bool:
+    """
+    Check that no axes have collapsed to zero size.
+    """
+    ...
+
+def compress_fixed_aspect(layoutgrids, fig):
+    ...
+
+def get_margin_from_padding(obj, *, w_pad=..., h_pad=..., hspace=..., wspace=...): # -> dict[str, int]:
+    ...
+
+def make_layout_margins(layoutgrids, fig, renderer, *, w_pad=..., h_pad=..., hspace=..., wspace=...):
+    """
+    For each axes, make a margin between the *pos* layoutbox and the
+    *axes* layoutbox be a minimum size that can accommodate the
+    decorations on the axis.
+
+    Then make room for colorbars.
+
+    Parameters
+    ----------
+    layoutgrids : dict
+    fig : `~matplotlib.figure.Figure`
+        `.Figure` instance to do the layout in.
+    renderer : `~matplotlib.backend_bases.RendererBase` subclass.
+        The renderer to use.
+    w_pad, h_pad : float, default: 0
+        Width and height padding (in fraction of figure).
+    hspace, wspace : float, default: 0
+        Width and height padding as fraction of figure size divided by
+        number of columns or rows.
+    """
+    ...
+
+def make_margin_suptitles(layoutgrids, fig, renderer, *, w_pad=..., h_pad=...): # -> None:
+    ...
+
+def match_submerged_margins(layoutgrids, fig): # -> None:
+    """
+    Make the margins that are submerged inside an Axes the same size.
+
+    This allows axes that span two columns (or rows) that are offset
+    from one another to have the same size.
+
+    This gives the proper layout for something like::
+        fig = plt.figure(constrained_layout=True)
+        axs = fig.subplot_mosaic("AAAB\nCCDD")
+
+    Without this routine, the axes D will be wider than C, because the
+    margin width between the two columns in C has no width by default,
+    whereas the margins between the two columns of D are set by the
+    width of the margin between A and B. However, obviously the user would
+    like C and D to be the same size, so we need to add constraints to these
+    "submerged" margins.
+
+    This routine makes all the interior margins the same, and the spacing
+    between the three columns in A and the two column in C are all set to the
+    margins between the two columns of D.
+
+    See test_constrained_layout::test_constrained_layout12 for an example.
+    """
+    ...
+
+def get_cb_parent_spans(cbax): # -> tuple[range, range]:
+    """
+    Figure out which subplotspecs this colorbar belongs to.
+
+    Parameters
+    ----------
+    cbax : `~matplotlib.axes.Axes`
+        Axes for the colorbar.
+    """
+    ...
+
+def get_pos_and_bbox(ax, renderer): # -> tuple[Unknown, Unknown]:
+    """
+    Get the position and the bbox for the axes.
+
+    Parameters
+    ----------
+    ax : `~matplotlib.axes.Axes`
+    renderer : `~matplotlib.backend_bases.RendererBase` subclass.
+
+    Returns
+    -------
+    pos : `~matplotlib.transforms.Bbox`
+        Position in figure coordinates.
+    bbox : `~matplotlib.transforms.Bbox`
+        Tight bounding box in figure coordinates.
+    """
+    ...
+
+def reposition_axes(layoutgrids, fig, renderer, *, w_pad=..., h_pad=..., hspace=..., wspace=...): # -> None:
+    """
+    Reposition all the axes based on the new inner bounding box.
+    """
+    ...
+
+def reposition_colorbar(layoutgrids, cbax, renderer, *, offset=...): # -> None:
+    """
+    Place the colorbar in its new place.
+
+    Parameters
+    ----------
+    layoutgrids : dict
+    cbax : `~matplotlib.axes.Axes`
+        Axes for the colorbar.
+    renderer : `~matplotlib.backend_bases.RendererBase` subclass.
+        The renderer to use.
+    offset : array-like
+        Offset the colorbar needs to be pushed to in order to
+        account for multiple colorbars.
+    """
+    ...
+
+def reset_margins(layoutgrids, fig): # -> None:
+    """
+    Reset the margins in the layoutboxes of *fig*.
+
+    Margins are usually set as a minimum, so if the figure gets smaller
+    the minimum needs to be zero in order for it to grow again.
+    """
+    ...
+
+def colorbar_get_pad(layoutgrids, cax):
+    ...
+