Oslo 库中的公共与私有符号

Oslo 团队使用“_”作为私有名称的前缀，来区分 Oslo 库的“公共”部分和“私有”部分。使用私有符号的代码在库发生变化时可能会损坏，因此应该更改代码以避免使用这些符号。

问题描述

Oslo 团队致力于为所有 Oslo 库创建稳定的 API。我们努力遵循良好的 API 定义实践，首先使 API 尽可能小，然后随着时间的推移以向后兼容的方式逐步扩展它们。

在这样做时，我们面临的一个挑战是如何保护消费项目中的实现细节。像 C++ 和 Java 这样的语言具有语言级别的构造，用于在类和模块中隐藏数据和方法。Python 是一种更开放的语言，没有与这些数据隐藏设施平行的功能。相反，Python 开发者采用了一种约定，即通过在名称前添加单个下划线来命名“私有”库的符号，并通过显式记录库支持的公共接口来指定库的私有部分。Oslo 团队在整个 Oslo 代码库中遵循这些约定。

我们在 Kilo 周期开始的工作，以移出“oslo”命名空间包，暴露了几个项目中正在导入和直接使用我们标记为私有的符号的地方。通常这发生在测试中，但并非总是如此。这导致我们在发布新版本的库时出现问题，因为这些私有符号要么不再存在，要么已移动到新位置。

拟议政策

由于最近几次发布中反复出现的问题，我们构建了一些工具，以便针对库的预发布版本运行项目的测试，目前我们正在使用这些工具来尽量减少问题。与此同时，我们期望能够相对自由地更改库的实现细节——这就是为什么我们如此努力地指定公共 API，就像应用程序的 REST API 一样。

我们期望消费项目尊重符号的私有指定，并避免直接使用它们或在测试中模拟它们。在无法或不方便模拟库的公共 API 时，我们已经提供了（并将继续添加）用于配置库以在应用程序单元测试中使用的 fixture。我们还有所有 Oslo 库的公共 API 文档，以尽量明确 API 的哪些部分被认为是稳定和受支持的。

有一些简单的指南可以确定库的哪些部分是私有的

  1. 如果模块、类、函数、变量、属性或其他符号的名称以“_”开头，则它是私有的，不应使用。

  2. 如果该符号未记录，则它可能是私有的，可能不应使用。我们可能在文档中遗漏了一些符号，因此如果您不确定，请在 #openstack-oslo 或邮件列表中提问。

替代方案与历史

在网关中自动运行测试

在每次发布之前运行消费项目的单元测试非常昂贵。目前，oslo.i18n 的单个预发布版本需要针对 37 个仓库运行测试作业。我们为这些项目中的每一个运行 py27 和 pep8 作业，因此实际上运行 74 个作业。我们无法在 CI 基础设施上执行此操作，而不会消耗足够的虚拟机来对其他地方的补丁着陆能力产生负面影响，因此我们正在使用其他资源并手动进行测试。

手动在发布前运行测试

在发布前手动运行测试会延迟重要补丁和错误修复的快速发布。它还需要各个库维护者拥有足够的资源来运行所有单元测试。

实现

作者

主要作者：Doug Hellmann

其他贡献者：无

里程碑

我们将为剩余的命名空间包发布运行这些测试，以尽量减少进一步的破坏。但是，我们不计划在命名空间包更改完成后（目前计划在 Kilo-2 里程碑完成）继续进行这种级别的测试，因为我们预计代码的更改不会那么频繁。

工作项

N/A

参考资料

修订历史

修订版

发布名称

描述

Icehouse

引入

Kilo

在移出 oslo 命名空间包期间正式化。

注意

本作品采用知识共享署名 3.0 非移植许可协议授权。 http://creativecommons.org/licenses/by/3.0/legalcode