matplotlib._api
Helper functions for managing the Matplotlib API.
This documentation is only relevant for Matplotlib developers, not for users.
-
matplotlib._api.check_getitem(_mapping, **kwargs)
[source] -
kwargs must consist of a single key, value pair. If key is in _mapping, return
_mapping[value]
; else, raise an appropriate ValueError.Examples
>>> _api.check_getitem({"foo": "bar"}, arg=arg)
-
matplotlib._api.check_in_list(_values, *, _print_supported_values=True, **kwargs)
[source] -
For each key, value pair in kwargs, check that value is in _values.
Parameters: -
_valuesiterable
-
Sequence of values to check on.
-
_print_supported_valuesbool, default: True
-
Whether to print _values when raising ValueError.
-
**kwargsdict
-
key, value pairs as keyword arguments to find in _values.
Raises: - ValueError
-
If any value in kwargs is not found in _values.
Examples
>>> _api.check_in_list(["foo", "bar"], arg=arg, other_arg=other_arg)
-
-
matplotlib._api.check_isinstance(_types, **kwargs)
[source] -
For each key, value pair in kwargs, check that value is an instance of one of _types; if not, raise an appropriate TypeError.
As a special case, a
None
entry in _types is treated as NoneType.Examples
>>> _api.check_isinstance((SomeClass, None), arg=arg)
-
matplotlib._api.check_shape(_shape, **kwargs)
[source] -
For each key, value pair in kwargs, check that value has the shape _shape, if not, raise an appropriate ValueError.
None in the shape is treated as a "free" size that can have any length. e.g. (None, 2) -> (N, 2)
The values checked must be numpy arrays.
Examples
To check for (N, 2) shaped arrays
>>> _api.check_shape((None, 2), arg=arg, other_arg=other_arg)
-
class matplotlib._api.classproperty(fget, fset=None, fdel=None, doc=None)
[source] -
Bases:
object
Like
property
, but also triggers on access via the class, and it is the class that's passed as argument.Examples
class C: @classproperty def foo(cls): return cls.__name__ assert C.foo == "C"
-
property fget
-
-
matplotlib._api.warn_external(message, category=None)
[source] -
warnings.warn
wrapper that sets stacklevel to "outside Matplotlib".The original emitter of the warning can be obtained by patching this function back to
warnings.warn
, i.e._api.warn_external = warnings.warn
(orfunctools.partial(warnings.warn, stacklevel=2)
, etc.).
Helper functions for deprecating parts of the Matplotlib API.
This documentation is only relevant for Matplotlib developers, not for users.
-
exception matplotlib._api.deprecation.MatplotlibDeprecationWarning
[source] -
Bases:
UserWarning
A class for issuing deprecation warnings for Matplotlib users.
In light of the fact that Python builtin DeprecationWarnings are ignored by default as of Python 2.7 (see link below), this class was put in to allow for the signaling of deprecation, but via UserWarnings which are not ignored by default.
https://docs.python.org/dev/whatsnew/2.7.html#the-future-for-python-2-x
-
matplotlib._api.deprecation.delete_parameter(since, name, func=None, **kwargs)
[source] -
Decorator indicating that parameter name of func is being deprecated.
The actual implementation of func should keep the name parameter in its signature, or accept a
**kwargs
argument (through which name would be passed).Parameters that come after the deprecated parameter effectively become keyword-only (as they cannot be passed positionally without triggering the DeprecationWarning on the deprecated parameter), and should be marked as such after the deprecation period has passed and the deprecated parameter is removed.
Parameters other than since, name, and func are keyword-only and forwarded to
warn_deprecated
.Examples
@_api.delete_parameter("3.1", "unused") def func(used_arg, other_arg, unused, more_args): ...
-
matplotlib._api.deprecation.deprecate_method_override(method, obj, *, allow_empty=False, **kwargs)
[source] -
Return
obj.method
with a deprecation if it was overridden, else None.Parameters: - method
-
An unbound method, i.e. an expression of the form
Class.method_name
. Remember that within the body of a method, one can always use__class__
to refer to the class that is currently being defined. - obj
-
Either an object of the class where method is defined, or a subclass of that class.
-
allow_emptybool, default: False
-
Whether to allow overrides by "empty" methods without emitting a warning.
- **kwargs
-
Additional parameters passed to
warn_deprecated
to generate the deprecation warning; must at least include the "since" key.
-
class matplotlib._api.deprecation.deprecate_privatize_attribute(*args, **kwargs)
[source] -
Bases:
object
Helper to deprecate public access to an attribute.
This helper should only be used at class scope, as follows:
class Foo: attr = _deprecate_privatize_attribute(*args, **kwargs)
where all parameters are forwarded to
deprecated
. This form makesattr
a property which forwards access toself._attr
(same name but with a leading underscore), with a deprecation warning. Note that the attribute name is derived from the name this helper is assigned to.
-
matplotlib._api.deprecation.deprecated(since, *, message='', name='', alternative='', pending=False, obj_type=None, addendum='', removal='')
[source] -
Decorator to mark a function, a class, or a property as deprecated.
When deprecating a classmethod, a staticmethod, or a property, the
@deprecated
decorator should go under@classmethod
and@staticmethod
(i.e.,deprecated
should directly decorate the underlying callable), but over@property
.When deprecating a class
C
intended to be used as a base class in a multiple inheritance hierarchy,C
must define an__init__
method (ifC
instead inherited its__init__
from its own base class, then@deprecated
would mess up__init__
inheritance when installing its own (deprecation-emitting)C.__init__
).Parameters: -
sincestr
-
The release at which this API became deprecated.
-
messagestr, optional
-
Override the default deprecation message. The
%(since)s
,%(name)s
,%(alternative)s
,%(obj_type)s
,%(addendum)s
, and%(removal)s
format specifiers will be replaced by the values of the respective arguments passed to this function. -
namestr, optional
-
The name used in the deprecation message; if not provided, the name is automatically determined from the deprecated object.
-
alternativestr, optional
-
An alternative API that the user may use in place of the deprecated API. The deprecation warning will tell the user about this alternative if provided.
-
pendingbool, optional
-
If True, uses a PendingDeprecationWarning instead of a DeprecationWarning. Cannot be used together with removal.
-
obj_typestr, optional
-
The object type being deprecated; by default, 'class' if decorating a class, 'attribute' if decorating a property, 'function' otherwise.
-
addendumstr, optional
-
Additional text appended directly to the final message.
-
removalstr, optional
-
The expected removal version. With the default (an empty string), a removal version is automatically computed from since. Set to other Falsy values to not schedule a removal date. Cannot be used together with pending.
Examples
Basic example:
@deprecated('1.4.0') def the_function_to_deprecate(): pass
-
-
matplotlib._api.deprecation.make_keyword_only(since, name, func=None)
[source] -
Decorator indicating that passing parameter name (or any of the following ones) positionally to func is being deprecated.
-
matplotlib._api.deprecation.mplDeprecation
-
alias of
matplotlib._api.deprecation.MatplotlibDeprecationWarning
-
matplotlib._api.deprecation.rename_parameter(since, old, new, func=None)
[source] -
Decorator indicating that parameter old of func is renamed to new.
The actual implementation of func should use new, not old. If old is passed to func, a DeprecationWarning is emitted, and its value is used, even if new is also passed by keyword (this is to simplify pyplot wrapper functions, which always pass new explicitly to the Axes method). If new is also passed but positionally, a TypeError will be raised by the underlying function during argument binding.
Examples
@_api.rename_parameter("3.1", "bad_name", "good_name") def func(good_name): ...
-
matplotlib._api.deprecation.suppress_matplotlib_deprecation_warning()
[source]
-
matplotlib._api.deprecation.warn_deprecated(since, *, message='', name='', alternative='', pending=False, obj_type='', addendum='', removal='')
[source] -
Display a standardized deprecation.
Parameters: -
sincestr
-
The release at which this API became deprecated.
-
messagestr, optional
-
Override the default deprecation message. The
%(since)s
,%(name)s
,%(alternative)s
,%(obj_type)s
,%(addendum)s
, and%(removal)s
format specifiers will be replaced by the values of the respective arguments passed to this function. -
namestr, optional
-
The name of the deprecated object.
-
alternativestr, optional
-
An alternative API that the user may use in place of the deprecated API. The deprecation warning will tell the user about this alternative if provided.
-
pendingbool, optional
-
If True, uses a PendingDeprecationWarning instead of a DeprecationWarning. Cannot be used together with removal.
-
obj_typestr, optional
-
The object type being deprecated.
-
addendumstr, optional
-
Additional text appended directly to the final message.
-
removalstr, optional
-
The expected removal version. With the default (an empty string), a removal version is automatically computed from since. Set to other Falsy values to not schedule a removal date. Cannot be used together with pending.
Examples
Basic example:
# To warn of the deprecation of "matplotlib.name_of_module" warn_deprecated('1.4.0', name='matplotlib.name_of_module', obj_type='module')
-
© 2012–2021 Matplotlib Development Team. All rights reserved.
Licensed under the Matplotlib License Agreement.
https://matplotlib.org/3.4.1/api/_api_api.html