diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 45e40feeef54..fe771c5cc66f 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -712,40 +712,32 @@ def figure(num=None, # autoincrement if None, else integer from 1-N If False, suppress drawing the figure frame. FigureClass : subclass of `~matplotlib.figure.Figure` - Optionally use a custom `.Figure` instance. + If set, an instance of this subclass will be created, rather than a + plain `.Figure`. clear : bool, default: False If True and the figure already exists, then it is cleared. - tight_layout : bool or dict, default: :rc:`figure.autolayout` - If ``False`` use *subplotpars*. If ``True`` adjust subplot - parameters using `.tight_layout` with default padding. - When providing a dict containing the keys ``pad``, ``w_pad``, - ``h_pad``, and ``rect``, the default `.tight_layout` paddings - will be overridden. + layout : {'constrained', 'tight', `.LayoutEngine`, None}, default: None + The layout mechanism for positioning of plot elements to avoid + overlapping Axes decorations (labels, ticks, etc). Note that layout + managers can measurably slow down figure display. Defaults to *None* + (but see the documentation of the `.Figure` constructor regarding the + interaction with rcParams). - constrained_layout : bool, default: :rc:`figure.constrained_layout.use` - If ``True`` use constrained layout to adjust positioning of plot - elements. Like ``tight_layout``, but designed to be more - flexible. See - :doc:`/tutorials/intermediate/constrainedlayout_guide` - for examples. (Note: does not work with `add_subplot` or - `~.pyplot.subplot2grid`.) - - - **kwargs : optional - See `~.matplotlib.figure.Figure` for other possible arguments. + **kwargs + Additional keyword arguments are passed to the `.Figure` constructor. Returns ------- `~matplotlib.figure.Figure` - The `.Figure` instance returned will also be passed to - new_figure_manager in the backends, which allows to hook custom - `.Figure` classes into the pyplot interface. Additional kwargs will be - passed to the `.Figure` init function. Notes ----- + Newly created figures will be passed to the + `~.backend_template.new_figure_manager` function provided by the current + backend, which will install a canvas and a manager on the figure. + If you are creating many figures, make sure you explicitly call `.pyplot.close` on the figures you are not using, because this will enable pyplot to properly clean up the memory.