在PyPI上发布非向后兼容的库？

Question

我在PyPI上有一个名为foobar的库，它目前在版本1.2.0（使用语义版本控制）。

下一版本不保留与版本1.x的API兼容性，因此我将其发布为2.0.0。

将此新版本发布到PyPI的最佳做法是什么，以便使用1.x版本的客户端不会意外升级到2.0.0并破坏其代码？ （我假设有人没有在代码中强制执行类似>=1.0.0, <2.0.0的版本依赖项）。

在PyPI上创建一个名为foobar2的全新包并在那里推送新版本会更好吗？其他项目如何处理这个问题？

Answer 1

我断言：API更改通常分为两类。

1. 新API B取代A但A可以完全使用新的API B实现。因此，使用新API同时维护旧API是可行的。

   这可能就像移动整齐或合理化模块的新API一样简单，或者更复杂，例如将args转换为kwargs或其他任何东西。

2. 新API替换旧API，但出于技术原因无法实现。

这些是IMO类别的选项。您选择哪一个将取决于您正在做出哪些更改以及您a）关心或b）与您联系并且可以与您的用户交谈（即如果只是少数几个未公布的破损）您团队中随后可以帮助解决问题的人员。）

1。在新版本中提供旧版和新版。

使用新API实现旧API，但使用warnings模块将其标记为已弃用。你给人们注意转换，你可以在将来的某个时候删除旧的API。

这是第一种API更改的最佳做法。它让每个人都在同一个流上，让你在将来的某个时候整理一下。

2。警告，然后介绍新的API。

如果您处于情境2或情况1但无法证明资源使用new实现旧，那么您可以轻松发布使用警告模块的1.2.1版本警告用户您即将添加新版本将破坏他们的codez，并且他们应该快速将版本挂在他们的requirements.txt中。

说你什么时候发布2.0版，然后你就警告过了。

但是，如果您的用户从1.2.0迁移到2.0并不是太费力，那么这是非常公平的。

3。添加一个全新的包。

如果存在深刻的差异，并且用户将代码更新到他们基本上需要重写代码是一件非常痛苦的事情，那么您不应该害怕只使用全新的软件包。我们都犯了错误，并且鉴于Python 2和Python 3之间存在差异，Python社区中没有人不知道这一点:-)。 unittest2也是前一个例子。

人们会期待什么。

就个人而言，如果我在一个我关心的系统上进行了自动升级，如果我没有将版本挂起来只升级维护版本，我认为如果有人发布了我的系统自动进行的主要升级，那是我的错然后由于它而停止工作。

这给了你道德的高地IMO，但对于那些没有检查并被烧毁的懒惰用户（或更糟糕的是，顾客）来说，这并不是什么安慰。

其他人做什么

• paramiko保持API在1.x到2.0
上的兼容性
• beautifulsoup更改PyPI上的名称（从BeautifulSoup更改为bs4）
• django倾向于弃用功能并在以后的功能发行版中将其删除，一般情况下，我绝不会将我从1.X关注的django安装升级到1.（X + 1）而不先测试它。 （我认为这是最好的做法，就像django人做的很多事情。）

所以总结是：有一个混合，它真的取决于你。然而，避免用户自己造成问题的唯一完全安全的方法是完全保持后向兼容性或创建一个新的包，就像BeautifulSoup那样。