`matplotlib._api`#

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

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

警告

此模块及其子模块仅供内部使用。不要在您自己的代码中使用它们。我们可能会随时更改 API 而不会发出警告。

matplotlib._api。cache_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必须由单个键值对组成。如果key在 _mapping中，则返回_mapping[value]；否则，引发适当的 ValueError。

例子

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

matplotlib._api。check_in_list ( _values , * , _print_supported_values = True , ** kwargs ) [来源] #

对于kwargs中的每个键值对，检查值是否在_values中。

参数：

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

提高：

值错误: 如果在_values中找不到kwargs中的任何值。

例子

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

matplotlib._api。check_isinstance ( _types , ** kwargs ) [来源] #

对于kwargs中的每个键值对，检查值是否是_types之一的实例；如果没有，请引发适当的 TypeError。

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

例子

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

matplotlib._api。check_shape ( _shape , ** kwargs ) [来源] #

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

形状中的任何一个都不会被视为可以具有任何长度的“自由”尺寸。例如（无，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 ) [来源] #

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

用于

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

对于每一个属性，如果get_property到目前为止在类中定义了对应的，就会定义一个别名named get_alias；二传手也会这样做。如果 getter 和 setter 都不存在，则会引发异常。

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

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

matplotlib._api。select_matching_signature ( funcs , * args , ** kwargs ) [来源] #

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

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

select_matching_signature尝试调用funcs 中的每个函数（按照给出的顺序）。以 a 失败的调用将被静默跳过。一旦调用成功，返回它的返回值。如果没有函数接受，则重新引发上次失败调用的引发。*args, **kwargsTypeErrorselect_matching_signature*args, **kwargsTypeError

调用者通常应确保 any只能绑定一个func（以避免任何歧义），尽管.*args, **kwargsselect_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

这允许使用两个参数（old1和 old2）或单个参数（ new ）调用my_func 。请注意，新签名是最后给出的，因此如果调用者传入的参数与任何签名都不匹配，则调用者会获得与新签名相对应的值。TypeError

matplotlib._api。warn_external ( message , category = None ) [source] #

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

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

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

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

警告

此模块仅供内部使用。不要在您自己的代码中使用它。我们可能会随时更改 API 而不会发出警告。

异常 matplotlib._api.deprecation。MatplotlibDeprecationWarning [来源] #

基地：DeprecationWarning

为 Matplotlib 用户发出弃用警告的类。

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

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

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弃用，否则无。

参数：

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

类 matplotlib._api.deprecation。deprecate_privatize_attribute ( * args , ** kwargs ) [来源] #

基地：object

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

此帮助器应仅在类范围内使用，如下所示：

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

所有参数都转发到deprecated. 此表单创建 attr一个属性，该属性将读取和写入访问权限转发到self._attr （同名但带有前导下划线），并带有弃用警告。请注意，属性名称派生自此助手分配给的名称。这个助手也适用于弃用方法。

matplotlib._api.deprecation。已弃用（因为, * , message = '' , name = '' , alternative = '' , pending = False , obj_type = None , addendum = '' , remove = ''）[来源] #

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

当弃用类方法、静态方法或属性时， @deprecated装饰器应该在 @classmethodand 之下@staticmethod（即，deprecated应该直接装饰底层的可调用对象），但在之上 @property。

当弃用一个C打算用作多继承层次结构中的基类的类时，C 必须定义一个__init__方法（如果C改为__init__从其自己的基类继承它，那么在安装它自己的（deprecation-emitting）时@deprecated会弄乱继承）。__init__C.__init__

参数与 for 相同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] #

指示将参数名称（或以下任何一个）按位置传递给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 ( ) [来源] #

matplotlib._api.deprecation。warn_deprecated ( since , * , message = '' , name = '' , alternative = '' , pending = False , obj_type = '' , addendum = '' , remove = ' ' ) [来源] #

显示标准化的弃用。

参数：

由于str: 弃用此 API 的版本。
消息str，可选: 覆盖默认的弃用消息。, %(since)s, %(name)s, %(alternative)s, %(obj_type)s,%(addendum)s和%(removal)s格式说明符将被传递给此函数的各个参数的值替换。
名称str，可选: 不推荐使用的对象的名称。
替代str，可选: 用户可以使用替代 API 来代替已弃用的 API。如果提供，弃用警告将告诉用户此替代方案。
待处理的布尔值，可选: 如果为 True，则使用 PendingDeprecationWarning 而不是 DeprecationWarning。不能与去除一起使用。
obj_type str，可选: 不推荐使用的对象类型。
附录str，可选: 直接附加到最终消息的附加文本。
删除str，可选: 预期的删除版本。使用默认值（空字符串），将自动从since计算删除版本。设置为其他 Falsy 值以不安排删除日期。不能与挂起一起使用。

例子

# 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`#