API 指南#
API 的一致性和稳定性非常重要；因此，只有在增加的好处值得调整现有代码的努力时，才会进行 API 更改（例如签名更改、行为更改、移除）。
因为我们是一个可视化库，我们的主要输出是用户看到的最终可视化结果；因此，图形的外观是API的一部分，任何变化，无论是语义上的还是 美学上的 ，都是向后不兼容的API变化。
添加新的API和功能#
每个未明确标记为私有（即以单下划线开头）的新函数、参数和属性都将成为 Matplotlib 的公共 API 的一部分。如上所述，更改现有 API 是繁琐的。因此，在添加新 API 时要特别小心：
通过在前面加上下划线，将标记辅助函数和内部属性标记为私有。
仔细考虑为你的函数和变量取个好名字。
尝试采用 Matplotlib API 现有部分的样式和命名约定。
尽可能多地使用仅关键字参数。另请参阅 API 演进的正确方式 -- 兼容地添加参数。
弃用 API#
在 Matplotlib 中进行的 API 更改必须遵循以下弃用流程，除非开发团队认为在极少数情况下有必要。通常，API 弃用分为两个阶段：
介绍: 警告用户 API 将 发生变化
过期: API 如 介绍期内所述进行了更改
这确保了在更改生效之前通知用户，从而防止代码意外中断。
规则#
引入弃用#
创建 弃用通知
如果可能，当使用已弃用的API时，发出一个
MatplotlibDeprecationWarning。为此有许多辅助工具：使用
_api.warn_deprecated()进行一般的弃用警告使用装饰器
@_api.deprecated来弃用类、函数、方法或属性使用
@_api.deprecate_privatize_attribute来标注属性的弃用，同时保留内部的私有版本。要警告函数签名的变化，请使用装饰器
@_api.delete_parameter、@_api.rename_parameter和@_api.make_keyword_only
所有这些辅助工具都接受一个名为 since 的第一个参数，该参数应设置为下一个点发布版本，例如“3.x”。
你可以在 alternative 中使用标准的 rst 交叉引用。
对关联的
.pyi文件中的类型提示进行适当修改。一般指导原则是匹配运行时报告的行为。标记为
@_api.deprecated或@_api.deprecate_privatize_attribute的项目通常在过期期间内保留，因此在引入时不需要进行更改。使用
@_api.rename_parameter或@_api.make_keyword_only装饰的项目在运行时报告 新*（弃用后）的签名，因此 *应该 在引入时更新。使用
@_api.delete_parameter装饰的项目应为已删除的参数包含一个默认值提示，即使它之前没有默认值（例如param: <type> = ...）。
过期弃用#
创建 弃用公告 。对于内容，您通常可以复制弃用通知并稍作调整。
修改代码功能并移除所有相关的弃用警告。
对关联的
.pyi文件中的类型提示进行适当修改。标记为
@_api.deprecated或@_api.deprecate_privatize_attribute的项目将在到期时被移除。使用
@_api.rename_parameter或@_api.make_keyword_only装饰的项目在引入时已经更新，现在不需要更改。使用
@_api.delete_parameter装饰的项目需要更新到最终签名，方式与.py文件签名更新相同。在
ci/mypy-stubtest-allowlist.txt中的任何条目，如果指示了弃用版本，应进行双重检查。虽然在大多数情况下这是不必要的，但有些项目从一开始就没有类型提示，而是被添加到了这个文件中。对于那些不在存根文件中的已移除项目，只需从允许列表中删除即可。
宣布新的和弃用的API#
当以向后不兼容的方式添加或更改API时，请添加适当的 版本控制指令 并在发布说明中记录它，并将条目添加到适当的文件夹中：
版本控制指令 |
公告文件夹 |
|
|---|---|---|
新功能 |
|
|
API 变更 |
|
|
在弃用API时，请按照 弃用指南 中的描述添加通知，并在此处总结：
通常，介绍通知可以重新用于过期通知，因为它们预计会描述相同的API变更和移除。
版本控制指令#
在进行向后不兼容的更改时，请在文档字符串中添加版本控制指令。指令应放置在描述块的末尾。例如:
class Foo:
"""
This is the summary.
Followed by a longer description block.
Consisting of multiple lines and paragraphs.
.. versionadded:: 3.5
Parameters
----------
a : int
The first parameter.
b: bool, default: False
This was added later.
.. versionadded:: 3.6
"""
def set_b(b):
"""
Set b.
.. versionadded:: 3.6
Parameters
----------
b: bool
对于类和函数，指令应放在 参数 部分之前。对于参数，指令应放在参数描述的末尾。微版本号被省略，且指令不应添加到整个模块中。
发行说明#
对于更新日志和新增内容，请避免在章节标题中使用交叉引用，因为这会导致目录中的链接变得混乱。相反，请确保在描述性文本中包含交叉引用。
API 变更说明#
未来版本的API变更说明收集在 doc/api/next_api_changes/ 中。它们被分为四个子目录：
弃用：未来变更的公告。通常，这些变更会引发一个弃用警告，使用此API的用户应更改其代码以保持与未来Matplotlib版本的兼容性。如果可能，请说明应使用什么替代方案。
移除: 被移除的API部分。如果可能，说明应该使用什么替代。
行为变化：保持有效但会产生不同结果的API。
开发变更：对构建过程、依赖项等的更改。
请将新条目放在这些目录中，并使用名为 99999-ABC.rst 的新文件，其中 99999 是 PR 编号，ABC 是作者的姓名首字母。通常，每个更改都会有自己的文件，但在适当的情况下，您也可以修改现有文件。总体目标是提供一个易于理解的更改文档。
一个典型的条目可能看起来像这样:
Locators
~~~~~~~~
The unused `Locator.autoscale()` method is deprecated (pass the axis
limits to `Locator.view_limits()` instead).
请避免在章节标题中使用引用，因为这会导致目录中的链接变得混乱。相反，请确保在描述性文本中包含引用。
新功能说明#
请将 whats_new.rst 的新部分放置在 doc/users/next_whats_new/ 目录中。
在添加条目时，请查看当前已有的文件，看看是否可以扩展其中的任何一个。如果你创建一个文件，如果你添加了一个全新的功能，可以命名为 cool_new_feature.rst，或者对于现有功能的扩展，可以命名为 updated_feature.rst。
包含以下形式的内容:
Section title for feature
-------------------------
A bunch of text about how awesome the new feature is and examples of how
to use it.
A sub-section
~~~~~~~~~~~~~
请避免在章节标题中使用引用，因为这会导致目录中的链接变得混乱。相反，请确保在描述性文本中包含引用。