`matplotlib._api`#

管理 Matplotlib API 的辅助函数。

此文档仅与 Matplotlib 开发者相关，不适用于用户。

警告

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

matplotlib._api.caching_module_getattr(cls)[source]#

用于将模块级 __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)[source]#

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

示例

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

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

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

参数:

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

引发:

ValueError: 如果在 kwargs 中未找到任何 value 对应的 values。

示例

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

matplotlib._api.check_isinstance(types, /, **kwargs)[source]#

对于 kwargs 中的每个 key, value 对，检查 value 是否是 types 中的一个实例；如果不是，则引发适当的 TypeError。

作为特例，types 中的 None 条目被视为 NoneType。

示例

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

matplotlib._api.check_shape(shape, /, **kwargs)[source]#

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

形状中的 None 被视为“自由”大小，可以具有任意长度。例如 (None, 2) -> (N, 2)

检查的值必须是 numpy 数组。

示例

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

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

类 matplotlib._api.classproperty(fget, fset=None, fdel=None, doc=None)[source]#

基类: object

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

示例

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

assert C.foo == "C"

属性 fget#

matplotlib._api.define_aliases(alias_d, cls=None)[source]#

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

用法示例：

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

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

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

matplotlib._api.kwarg_error(name, kw)[source]#

生成一个 TypeError，由带有错误关键字参数的函数调用引发。

参数:

name字符串: 调用函数的名称。
kw字符串或可迭代对象[字符串]: 无效关键字参数名称，或生成无效关键字参数的可迭代对象（例如，一个 kwargs 字典）。

matplotlib._api.nargs_error(name, takes, given)[source]#: 生成一个 TypeError，由带有错误参数数量的函数调用引发。

matplotlib._api.recursive_subclasses(cls)[source]#: 生成 cls 以及 cls 的直接和间接子类。

matplotlib._api.select_matching_signature(funcs, *args, **kwargs)[source]#

选择并调用接受 *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)[source]#

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

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

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

此文档仅与 Matplotlib 开发者相关，不适用于用户。

警告

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

异常 matplotlib._api.deprecation.MatplotlibDeprecationWarning[source]#

基类： DeprecationWarning

用于向 Matplotlib 用户发布弃用警告的类。

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

指示 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)[source]#

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

参数:

method: 一个未绑定方法，即形如 Class.method_name 的表达式。请记住，在方法体内部，始终可以使用 __class__ 来引用当前正在定义的类。
obj: 定义 method 的类的一个对象，或者是该类的一个子类。
allow_empty布尔值，默认值：False: 是否允许“空”方法进行重写而不发出警告。
**kwargs: 传递给 warn_deprecated 用于生成弃用警告的附加参数；至少必须包含“since”键。

类 matplotlib._api.deprecation.deprecate_privatize_attribute(*args, **kwargs)[source]#

基类: 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='')[source]#

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

当弃用类方法、静态方法或属性时，@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)[source]#

指示将参数 name（或任何后续参数）以位置参数形式传递给 func 的装饰器已被弃用。

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

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

指示 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()[source]#

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

显示标准化的弃用警告。

参数:

sincestr: 此 API 被弃用的版本。
messagestr, optional: 覆盖默认的弃用消息。%(since)s、%(name)s、%(alternative)s、%(obj_type)s、%(addendum)s 和 %(removal)s 格式说明符将被替换为此函数传递的相应参数的值。
namestr, 可选: 被弃用对象的名称。
alternativestr, optional: 用户可以用来替代被弃用 API 的备选 API。如果提供了此备选方案，弃用警告将告知用户。
pendingbool, optional: 如果为 True，则使用 PendingDeprecationWarning 而不是 DeprecationWarning。不能与 removal 同时使用。
obj_typestr, optional: 被弃用对象的类型。
addendumstr, optional: 直接附加到最终消息的附加文本。
removalstr, optional: 预期的移除版本。如果使用默认值（空字符串），则会从 since 自动计算移除版本。设置为其他 Falsy 值则不安排移除日期。不能与 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`#