@@ -1882,6 +1882,11 @@ def apply_aspect(self, position=None):
18821882 Parameters
18831883 ----------
18841884 position : None or .Bbox
1885+
1886+ .. note::
1887+ This parameter exists for historic reasons and is considered
1888+ internal. End users should not use it.
1889+
18851890 If not ``None``, this defines the position of the
18861891 Axes within the figure as a Bbox. See `~.Axes.get_position`
18871892 for further details.
@@ -1892,6 +1897,10 @@ def apply_aspect(self, position=None):
18921897 to call it yourself if you need to update the Axes position and/or
18931898 view limits before the Figure is drawn.
18941899
1900+ An alternative with a broader scope is `.Figure.draw_without_rendering`,
1901+ which updates all stale components of a figure, not only the positioning /
1902+ view limits of a single Axes.
1903+
18951904 See Also
18961905 --------
18971906 matplotlib.axes.Axes.set_aspect
@@ -1900,6 +1909,24 @@ def apply_aspect(self, position=None):
19001909 Set how the Axes adjusts to achieve the required aspect ratio.
19011910 matplotlib.axes.Axes.set_anchor
19021911 Set the position in case of extra space.
1912+ matplotlib.figure.Figure.draw_without_rendering
1913+ Update all stale components of a figure.
1914+
1915+ Examples
1916+ --------
1917+ A typical usage example would be the following. `~.Axes.imshow` sets the
1918+ aspect to 1, but adapting the Axes position and extent to reflect this is
1919+ deferred until rendering for performance reasons. If you want to know the
1920+ Axes size before, you need to call `.apply_aspect` to get the correct
1921+ values.
1922+
1923+ >>> fig, ax = plt.subplots()
1924+ >>> ax.imshow(np.zeros((3, 3)))
1925+ >>> ax.bbox.width, ax.bbox.height
1926+ (496.0, 369.59999999999997)
1927+ >>> ax.apply_aspect()
1928+ >>> ax.bbox.width, ax.bbox.height
1929+ (369.59999999999997, 369.59999999999997)
19031930 """
19041931if position is None :
19051932position = self .get_position (original = True )