`matplotlib._api`#

用于管理 Matplotlib API 的辅助函数。

本文档仅适用于 Matplotlib 开发者，不适用于用户。

警告

此模块及其子模块仅供内部使用。请勿在您的代码中使用它们。我们可能会随时更改API，恕不另行通知。

matplotlib._api.caching_module_getattr(cls)[源代码][源代码]#

用于实现模块级 __getattr__ 的辅助装饰器作为类。

这个装饰器必须在模块的顶层使用，如下所示:

@caching_module_getattr
class __getattr__:  # The class *must* be named ``__getattr__``.
    @property  # Only properties are taken into account.
    def name(self): ...

__getattr__ 类将被 __getattr__ 函数替换，以便在模块上访问 name 时解析相应的属性（该属性可能被装饰，例如使用 _api.deprecated 来弃用模块全局变量）。所有属性都是隐式缓存的。此外，如果没有具有给定名称的属性，则会生成并引发合适的 AttributeError。

matplotlib._api.check_getitem(mapping, /, **kwargs)[源代码][源代码]#

kwargs 必须由一个 键, 值 对组成。如果键在映射中，返回 映射[值]；否则，引发一个适当的 ValueError。

示例

>>> _api.check_getitem({"foo": "bar"}, arg=arg)

matplotlib._api.check_in_list(values, /, *, _print_supported_values=True, **kwargs)[源代码][源代码]#

对于 kwargs 中的每个 键, 值 对，检查值是否在值中；如果不存在，则引发适当的 ValueError。

参数:

值可迭代对象: 要检查的值序列。
_print_supported_valuesbool, 默认值: True: 在引发 ValueError 时是否打印值。
**kwargsdict: key, value 对作为关键字参数在 values 中查找。

引发:

ValueError: 如果在 kwargs 中的任何值未在值中找到。

示例

>>> _api.check_in_list(["foo", "bar"], arg=arg, other_arg=other_arg)

matplotlib._api.check_isinstance(types, /, **kwargs)[源代码][源代码]#

对于 kwargs 中的每个 键, 值 对，检查值是否是类型之一的实例；如果不是，则引发适当的 TypeError。

作为一种特殊情况，types 中的 None 条目被视为 NoneType。

示例

>>> _api.check_isinstance((SomeClass, None), arg=arg)

matplotlib._api.check_shape(shape, /, **kwargs)[源代码][源代码]#

对于 kwargs 中的每个 键, 值 对，检查值是否具有形状；如果不是，则引发适当的 ValueError。

None 在形状中被视为一个“自由”尺寸，可以有任意长度。例如，(None, 2) -> (N, 2)

被检查的值必须是 numpy 数组。

示例

检查 (N, 2) 形状的数组

>>> _api.check_shape((None, 2), arg=arg, other_arg=other_arg)

class matplotlib._api.classproperty(fget, fset=None, fdel=None, doc=None)[源代码][源代码]#

基类：object

类似于 property，但也会在通过类访问时触发，并且传递的参数是类。

示例

class C:
    @classproperty
    def foo(cls):
        return cls.__name__

assert C.foo == "C"

property fget#: !! 由 numpydoc 处理 !!

matplotlib._api.define_aliases(alias_d, cls=None)[源代码][源代码]#

用于定义属性别名的类装饰器。

使用方法如下

@_api.define_aliases({"property": ["alias", ...], ...})
class C: ...

对于每个属性，如果在类中定义了相应的 get_property，则会定义一个名为 get_alias 的别名；对于设置器也会执行相同的操作。如果获取器和设置器都不存在，则会引发异常。

别名映射存储为类上的 _alias_map 属性，并可由 normalize_kwargs 使用（假设优先级较高的别名最后出现）。

matplotlib._api.kwarg_error(name, kw)[源代码][源代码]#

生成一个 TypeError，以便在函数调用时使用错误的 kwarg 引发。

参数:

名称str: 调用函数的名称。
kwstr 或 Iterable[str]: 无效的关键字参数名称，或一个产生无效关键字参数的可迭代对象（例如，一个 kwargs 字典）。

matplotlib._api.nargs_error(name, takes, given)[源代码][源代码]#: 生成一个 TypeError，以便在函数调用时引发错误的参数数量。

matplotlib._api.recursive_subclasses(cls)[源代码][源代码]#: 生成 cls 及其直接和间接子类。

matplotlib._api.select_matching_signature(funcs, *args, **kwargs)[源代码][源代码]#

选择并调用接受 *args, **kwargs 的函数。

funcs 是一个函数列表，这些函数不应引发任何异常（除非传递的参数与其签名不匹配时引发 TypeError）。

select_matching_signature 尝试用 *args, **kwargs 调用 funcs 中的每个函数（按给定的顺序）。调用失败并引发 TypeError 的函数将被静默跳过。一旦调用成功，select_matching_signature 将返回其返回值。如果没有函数接受 *args, **kwargs，则重新引发最后一个失败调用引发的 TypeError。

调用者通常应确保任何 *args, **kwargs 只能绑定一个 func （以避免任何歧义），尽管 select_matching_signature 不会对此进行检查。

注释

select_matching_signature 旨在帮助实现重载签名的函数。通常，应避免使用此类函数，除非出于向后兼容的考虑。典型的使用模式是

def my_func(*args, **kwargs):
    params = select_matching_signature(
        [lambda old1, old2: locals(), lambda new: locals()],
        *args, **kwargs)
    if "old1" in params:
        warn_deprecated(...)
        old1, old2 = params.values()  # note that locals() is ordered.
    else:
        new, = params.values()
    # do things with params

这允许 my_func 可以被调用时使用两个参数（old1 和 old2）或者一个参数（new）。注意新的签名放在最后，这样如果调用者传递的参数与任何签名不匹配，他们会得到一个对应于新签名的 TypeError。

matplotlib._api.warn_external(message, category=None)[源代码][源代码]#

warnings.warn 包装器，将 stacklevel 设置为“Matplotlib 外部”。

可以通过将此函数重新修补回 warnings.warn 来获取警告的原始发出者，即 _api.warn_external = warnings.warn （或 functools.partial(warnings.warn, stacklevel=2) 等）。

用于弃用 Matplotlib API 部分的辅助函数。

本文档仅适用于 Matplotlib 开发者，不适用于用户。

警告

此模块仅供内部使用。请勿在您的代码中使用它。我们可能会随时更改API，恕不另行通知。

exception matplotlib._api.deprecation.MatplotlibDeprecationWarning[源代码][源代码]#

基类：DeprecationWarning

一个用于向 Matplotlib 用户发出弃用警告的类。

matplotlib._api.deprecation.delete_parameter(since, name, func=None, **kwargs)[源代码][源代码]#

指示 func 的参数 name 已被弃用的装饰器。

func 的实际实现应在签名中保留 name 参数，或者接受一个 **kwargs 参数（通过该参数传递 name）。

在弃用参数之后的参数实际上变成了仅关键字参数（因为如果不通过位置传递它们，就会在弃用参数上触发DeprecationWarning），并且在弃用期过后，当弃用参数被移除时，应该将它们标记为仅关键字参数。

除了 since、name 和 func 之外的参数是仅关键字的，并转发到 warn_deprecated。

示例

@_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)[源代码][源代码]#

如果 obj.method 被重写，则返回带有弃用警告的 obj.method，否则返回 None。

参数:

方法: 一个未绑定的方法，即形式为 Class.method_name 的表达式。记住，在方法体内，总是可以使用 __class__ 来引用当前正在定义的类。
obj: 类中定义 method 的对象，或该类的子类。
allow_emptybool, 默认: False: 是否允许通过“空”方法进行覆盖而不发出警告。
**kwargs: 传递给 warn_deprecated 以生成弃用警告的附加参数；必须至少包含 "since" 键。

class matplotlib._api.deprecation.deprecate_privatize_attribute(*args, **kwargs)[源代码][源代码]#

基类：object

帮助弃用对属性的公共访问（或方法）。

此助手应仅在类作用域中使用，如下所示:

class Foo:
    attr = _deprecate_privatize_attribute(*args, **kwargs)

其中所有参数都被转发到 deprecated。这种形式使得 attr 成为一个属性，它将读取和写入访问转发到 ``self._attr``（名称相同但带有前导下划线），并带有弃用警告。请注意，属性名称是从 分配给此辅助工具的名称 派生的。此辅助工具也适用于弃用方法。

matplotlib._api.deprecation.deprecated(since, *, message='', name='', alternative='', pending=False, obj_type=None, addendum='', removal='')[源代码][源代码]#

用于将函数、类或属性标记为已弃用的装饰器。

当弃用一个类方法、静态方法或属性时，@deprecated 装饰器应该放在 @classmethod 和 @staticmethod 下面*（即，`deprecated` 应该直接装饰底层可调用对象），但 *上面 @property。

当弃用一个旨在在多重继承层次结构中用作基类的类 C 时，C 必须定义一个 __init__ 方法（如果 C 从其自身的基类继承了 __init__ ，那么 @deprecated 在安装其自己的（发出弃用警告的）``C.__init__`` 时会搞乱 __init__ 继承）。

参数与 warn_deprecated 相同，除了 obj_type 默认在装饰类时为 'class'，在装饰属性时为 'attribute'，其他情况下为 'function'。

示例

@deprecated('1.4.0')
def the_function_to_deprecate():
    pass

matplotlib._api.deprecation.make_keyword_only(since, name, func=None)[源代码][源代码]#

指示传递参数 name*（或以下任何一个）按位置给 *func 已被弃用的装饰器。

当用于具有 pyplot 包装器的方法时，这应该是最外层的装饰器，以便 boilerplate.py 可以访问原始签名。

matplotlib._api.deprecation.rename_parameter(since, old, new, func=None)[源代码][源代码]#

指示函数 func 的参数 old 被重命名为 new 的装饰器。

实际实现 func 时应使用 new，而不是 old。如果将 old 传递给 func，则会发出 DeprecationWarning，并且即使也通过关键字传递了 new，也会使用其值（这是为了简化 pyplot 包装函数，这些函数总是将 new 显式传递给 Axes 方法）。如果也传递了 new 但位置不正确，则在参数绑定期间底层函数将引发 TypeError。

示例

@_api.rename_parameter("3.1", "bad_name", "good_name")
def func(good_name): ...

matplotlib._api.deprecation.suppress_matplotlib_deprecation_warning()[源代码][源代码]#

matplotlib._api.deprecation.warn_deprecated(since, *, message='', name='', alternative='', pending=False, obj_type='', addendum='', removal='')[源代码][源代码]#

显示一个标准化的弃用。

参数:

自str: 此API被弃用的版本。
消息str, 可选: 覆盖默认的弃用消息。%(since)s、%(name)s、%(alternative)s、%(obj_type)s、%(addendum)s 和 %(removal)s 格式说明符将被替换为传递给此函数的相应参数的值。
名称str, 可选: 已弃用对象的名称。
替代方案str, 可选: 用户可以使用的一个替代API，以替代已弃用的API。如果提供了此替代方案，弃用警告将告知用户。
待定布尔值，可选: 如果为 True，则使用 PendingDeprecationWarning 而不是 DeprecationWarning。不能与 removal 一起使用。
obj_typestr, 可选: 即将被弃用的对象类型。
附录str, 可选: 附加文本直接追加到最终消息中。
移除str, 可选: 预期的移除版本。默认（空字符串）情况下，移除版本会根据 since 自动计算。设置为其他假值以不安排移除日期。不能与 pending 一起使用。

示例

# To warn of the deprecation of "matplotlib.name_of_module"
warn_deprecated('1.4.0', name='matplotlib.name_of_module',
                obj_type='module')

matplotlib._api#

`matplotlib._api`#