API 指南#

API 的一致性和稳定性非常重要;因此,只有在增加的益处值得修改现有代码的努力时,才会进行 API 更改(例如,签名更改,行为更改,删除).

因为我们是一个可视化库,所以我们的主要输出是用户看到的最终可视化结果;因此,图形的外观是 API 的一部分,任何更改,无论是语义上的还是美学上的,都是向后不兼容的 API 更改.

添加新的 API 和功能#

每个未明确标记为私有的(即,以下划线开头的)新函数,参数和属性都将成为 Matplotlib 公共 API 的一部分.如上所述,更改现有 API 非常麻烦.因此,在添加新 API 时要特别小心:

  • 通过在helper函数和内部属性前加下划线,将其标记为私有.

  • 仔细考虑你的函数和变量的好名字.

  • 尝试采用 Matplotlib API 现有部分的模式和命名约定.

  • 考虑尽可能多地使用仅关键字参数.另请参阅 API Evolution the Right Way -- Add Parameters Compatibly .

添加或更改颜色映射,颜色序列和样式#

视觉更改被认为是 API 的中断.因此,我们通常不修改现有的颜色映射,颜色序列或样式.

我们对添加新的颜色映射和样式设置了很高的门槛,以防止过度增长.虽然决定是具体情况具体分析,但评估标准包括:

  • 新颖性:它是否支持新的用例?例如,现有映射,序列和样式的细微变化可能不会被接受.

  • 可用性和可访问性:序列的颜色是否足够区分?是否考虑了色盲?

  • 广泛使用的证据:例如学术论文,行业博客和白皮书,或包含在其他可视化库或领域特定工具中

  • 开放许可:colormap,序列和样式必须具有 BSD 兼容许可(参见 贡献代码的许可证 )

弃用 API#

Matplotlib 中的 API 更改必须按照下面的弃用流程执行,除非开发团队认为在极少数情况下有必要.通常 API 弃用分两个阶段进行:

  • 引入:警告用户 API 将会更改

  • 过期:API 按照引入阶段的描述进行更改

这确保了用户在更改生效前收到通知,从而防止代码出现意外中断.

规则#

  • 弃用目标是下一个 meso release (例如 3.x)

  • 已弃用的 API 通常在引入弃用后的两个小版本中删除(过期).核心开发人员可以根据具体情况强制执行更长的弃用期,以便有更多的时间进行过渡

  • 旧的 API 在弃用期间必须保持完全可用

  • 如果存在已弃用 API 的替代方案,则应在弃用期间提供

  • 如有疑问,关于 API 更改的决定最终由 API consistency lead 开发人员做出.

引入弃用#

  1. 创建 deprecation notice

  2. 如果可能,在使用已弃用的 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 交叉引用.

  3. 对相关 .pyi 文件中的类型提示进行适当的更改. 一般准则是匹配运行时报告的行为.

    • 标有 @_api.deprecated 或 @_api.deprecate_privatize_attribute 的项目通常在过期期间保留,因此在引入时不需要进行任何更改.

    • 用 @_api.rename_parameter 或 @_api.make_keyword_only 装饰的项目在运行时报告新的(弃用后的)签名,因此应在引入时更新.

    • 用 @_api.delete_parameter 装饰的项目应包含已删除参数的默认值提示,即使之前没有(例如 param: <type> = ... ).

过期弃用#

  1. 创建 deprecation announcement . 对于内容,您通常可以复制弃用通知并稍作调整.

  2. 更改代码功能并删除任何相关的弃用警告.

  3. 对相关 .pyi 文件中的类型提示进行适当的更改.

    • 标有 @_api.deprecated 或 @_api.deprecate_privatize_attribute 的项目将在过期时删除.

    • 用 @_api.rename_parameter 或 @_api.make_keyword_only 装饰的项目已在引入时更新,现在无需更改.

    • 用 @_api.delete_parameter 装饰的项目需要更新到最终签名,方式与 .py 文件签名更新的方式相同.

    • ci/mypy-stubtest-allowlist.txt 中指示弃用版本的任何条目都应仔细检查. 在大多数情况下,这是不需要的,尽管有些项目从一开始就没有类型提示,而是被添加到此文件中. 对于 stub 文件中没有的已删除项目,只需要从允许列表中删除.

宣布新的和已弃用的 API#

当以向后不兼容的方式添加或更改 API 时,请添加适当的 versioning directive 并记录它以供发布说明,并将条目添加到相应的文件夹:

版本控制指令

公告文件夹

新功能

.. versionadded:: 3.N

doc/users/next_whats_new/

API 变更

.. versionchanged:: 3.N

doc/api/next_api_changes/[kind]

当弃用 API 时,请按照 deprecation guidelines 中所述添加通知,并在此处进行总结:

阶段

公告文件夹

introduce deprecation

doc/api/next_api_changes/deprecation

expire deprecation

doc/api/next_api_changes/[kind]

通常,引入通知可以重新用于过期通知,因为它们应该描述相同的 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

对于类和函数,指令应放置在 Parameters 部分之前.对于参数,该指令应放在参数描述的末尾.省略微版本发布,不应将指令添加到整个模块.

发行说明#

对于变更说明和新功能,请避免在节标题中使用交叉引用,因为它会导致目录中的链接混乱.相反,请确保在描述性文本中包含交叉引用.

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
~~~~~~~~~~~~~

请避免在节标题中使用引用,因为它会导致目录中的链接混乱.相反,请确保在描述性文本中包含引用.

On this page