def use(backend, *, force=True): """ Select the backend used for rendering and GUI integration. Parameters ---------- backend : str The backend to switch to. This can either be one of the standard backend names, which are case-insensitive: - interactive backends: GTK3Agg, GTK3Cairo, MacOSX, nbAgg, Qt4Agg, Qt4Cairo, Qt5Agg, Qt5Cairo, TkAgg, TkCairo, WebAgg, WX, WXAgg, WXCairo - non-interactive backends: agg, cairo, pdf, pgf, ps, svg, template or a string of the form: ``module://my.module.name``. force : bool, default: True If True (the default), raise an `ImportError` if the backend cannot be set up (either because it fails to import, or because an incompatible GUI interactive framework is already running); if False, ignore the failure. See Also -------- :ref:`backends` matplotlib.get_backend """ name = validate_backend(backend) # we need to use the base-class method here to avoid (prematurely) # resolving the "auto" backend setting if dict.__getitem__(rcParams, 'backend') == name: # Nothing to do if the requested backend is already set pass else: # if pyplot is not already imported, do not import it. Doing # so may trigger a `plt.switch_backend` to the _default_ backend # before we get a chance to change to the one the user just requested plt = sys.modules.get('matplotlib.pyplot') # if pyplot is imported, then try to change backends if plt is not None: try: # we need this import check here to re-raise if the # user does not have the libraries to support their # chosen backend installed. plt.switch_backend(name) except ImportError: if force: raise # if we have not imported pyplot, then we can set the rcParam # value which will be respected when the user finally imports # pyplot else: rcParams['backend'] = backend # if the user has asked for a given backend, do not helpfully # fallback rcParams['backend_fallback'] = False
def use(arg, warn=True): """ Set the matplotlib backend to one of the known backends. The argument is case-insensitive. .. note:: This function must be called *before* importing pyplot for the first time; or, if you are not using pyplot, it must be called before importing matplotlib.backends. If warn is True, a warning is issued if you try and call this after pylab or pyplot have been loaded. In certain black magic use cases, e.g. :func:`pyplot.switch_backends`, we are doing the reloading necessary to make the backend switch work (in some cases, e.g. pure image backends) so one can set warn=False to supporess the warnings. To find out which backend is currently set, see :func:`matplotlib.get_backend`. """ if 'matplotlib.backends' in sys.modules: if warn: warnings.warn(_use_error_msg) return if arg.startswith('module://'): name = arg else: # Lowercase only non-module backend names (modules are case-sensitive) arg = arg.lower() name = validate_backend(arg) rcParams['backend'] = name
def use(backend, warn=False, force=True): """ Select the backend used for rendering and GUI integration. Parameters ---------- backend : str The backend to switch to. This can either be one of the standard backend names, which are case-insensitive: - interactive backends: GTK3Agg, GTK3Cairo, MacOSX, nbAgg, Qt4Agg, Qt4Cairo, Qt5Agg, Qt5Cairo, TkAgg, TkCairo, WebAgg, WX, WXAgg, WXCairo - non-interactive backends: agg, cairo, pdf, pgf, ps, svg, template or a string of the form: ``module://my.module.name``. warn : bool, default: False If True and not *force*, emit a warning if a failure-to-switch `ImportError` has been suppressed. This parameter is deprecated. force : bool, default: True If True (the default), raise an `ImportError` if the backend cannot be set up (either because it fails to import, or because an incompatible GUI interactive framework is already running); if False, ignore the failure. See Also -------- :ref:`backends` matplotlib.get_backend """ name = validate_backend(backend) if dict.__getitem__(rcParams, 'backend') == name: # Nothing to do if the requested backend is already set pass else: # Update both rcParams and rcDefaults so restoring the defaults later # with rcdefaults won't change the backend. This is a bit of overkill # as 'backend' is already in style.core.STYLE_BLACKLIST, but better to # be safe. rcParams['backend'] = rcParamsDefault['backend'] = name try: from matplotlib import pyplot as plt plt.switch_backend(name) except ImportError as exc: if force: raise if warn: cbook._warn_external( f"Failed to switch backend to {backend}: {exc}")
def use(arg, warn=True, force=False): """ Set the matplotlib backend to one of the known backends. The argument is case-insensitive. *warn* specifies whether a warning should be issued if a backend has already been set up. *force* is an **experimental** flag that tells matplotlib to attempt to initialize a new backend by reloading the backend module. .. note:: This function must be called *before* importing pyplot for the first time; or, if you are not using pyplot, it must be called before importing matplotlib.backends. If warn is True, a warning is issued if you try and call this after pylab or pyplot have been loaded. In certain black magic use cases, e.g. :func:`pyplot.switch_backend`, we are doing the reloading necessary to make the backend switch work (in some cases, e.g., pure image backends) so one can set warn=False to suppress the warnings. To find out which backend is currently set, see :func:`matplotlib.get_backend`. """ # Lets determine the proper backend name first if arg.startswith('module://'): name = arg else: # Lowercase only non-module backend names (modules are case-sensitive) arg = arg.lower() name = validate_backend(arg) # Check if we've already set up a backend if 'matplotlib.backends' in sys.modules: # Warn only if called with a different name if (rcParams['backend'] != name) and warn: warnings.warn(_use_error_msg) # Unless we've been told to force it, just return if not force: return need_reload = True else: need_reload = False # Store the backend name rcParams['backend'] = name # If needed we reload here because a lot of setup code is triggered on # module import. See backends/__init__.py for more detail. if need_reload: reload(sys.modules['matplotlib.backends'])
def use(arg, warn=True): """ Set the matplotlib backend to one of the known backends. The argument is case-insensitive. For the Cairo backend, the argument can have an extension to indicate the type of output. Example: use('cairo.pdf') will specify a default of pdf output generated by Cairo. .. note:: This function must be called *before* importing pyplot for the first time; or, if you are not using pyplot, it must be called before importing matplotlib.backends. If warn is True, a warning is issued if you try and call this after pylab or pyplot have been loaded. In certain black magic use cases, e.g. :func:`pyplot.switch_backends`, we are doing the reloading necessary to make the backend switch work (in some cases, e.g. pure image backends) so one can set warn=False to supporess the warnings. To find out which backend is currently set, see :func:`matplotlib.get_backend`. """ if 'matplotlib.backends' in sys.modules: if warn: warnings.warn(_use_error_msg) return if arg.startswith('module://'): name = arg else: # Lowercase only non-module backend names (modules are case-sensitive) arg = arg.lower() be_parts = arg.split('.') name = validate_backend(be_parts[0]) if len(be_parts) > 1: if name == 'cairo': rcParams['cairo.format'] = validate_cairo_format(be_parts[1]) else: raise ValueError('Only cairo backend has a format option') rcParams['backend'] = name
def use(backend, *, force=True): """ Select the backend used for rendering and GUI integration. Parameters ---------- backend : str The backend to switch to. This can either be one of the standard backend names, which are case-insensitive: - interactive backends: GTK3Agg, GTK3Cairo, MacOSX, nbAgg, Qt4Agg, Qt4Cairo, Qt5Agg, Qt5Cairo, TkAgg, TkCairo, WebAgg, WX, WXAgg, WXCairo - non-interactive backends: agg, cairo, pdf, pgf, ps, svg, template or a string of the form: ``module://my.module.name``. force : bool, default: True If True (the default), raise an `ImportError` if the backend cannot be set up (either because it fails to import, or because an incompatible GUI interactive framework is already running); if False, ignore the failure. See Also -------- :ref:`backends` matplotlib.get_backend """ name = validate_backend(backend) if dict.__getitem__(rcParams, 'backend') == name: # Nothing to do if the requested backend is already set pass else: try: from matplotlib import pyplot as plt plt.switch_backend(name) except ImportError: if force: raise