升级金字塔

当发布新版本的金字塔时，它有时会贬低某个功能或删除旧版本中不推荐的功能。当特性从金字塔中移除时，依赖这些特性的应用程序将开始中断。本章介绍如何在升级正在使用的金字塔版本时确保金字塔应用程序继续工作。

金字塔核心团队在删除功能方面是保守的。我们不会不必要地删除特性，但我们是人类，我们会犯错误，导致某些特性成为进化的死胡同。虽然我们愿意在一段时间内支持死端特性，但是当支持它们的成本超过了保持它们在周围的好处时，最终必须删除一些特性，因为金字塔中的每个特性都代表了一定的文档和维护负担。

弃用和移除政策

当计划从金字塔或其任何官方附加组件中删除某个功能时，核心开发团队将采取以下步骤：

  • 使用该功能将开始生成 DeprecationWarning ，指示功能被弃用的版本。

  • 在文档中添加了一个说明，指出该功能已被弃用。

  • 注释添加到 Pyramid 改变历史 关于折旧。

最终删除不推荐使用的功能时：

功能从未在中删除 微型的 释放。它们只在次要版本和主要版本中被删除。不推荐使用的功能至少保留了一段时间 三 从该功能被弃用时起的次要版本。因此，如果在金字塔1.0中添加了一个特性，但在金字塔1.1中已弃用了它，那么它将一直保留到所有1.1.x版本、所有1.2.x版本和所有1.3.x版本。它最终将在第一个1.4.x版本中删除。

有时功能是“文档已弃用”而不是正式弃用。这意味着该特性将无限期保留，但它将从文档中删除，或者在文档中添加一个注释，告诉人们使用其他较新的特性。当保留旧特性的成本非常低，并且支持和文档负担非常低时，就会发生这种情况。例如，我们可以重命名一个API函数，而不更改它接受的参数。在这种情况下，我们通常会重命名函数，并将文档更改为指向新的函数名，但保留旧函数名的向后兼容性别名，这样旧代码就不会中断。

“不推荐使用的文档”功能通常“永远”工作，这意味着它们不会被删除，也不会生成拒绝警告。然而，这些变化在 Pyramid 改变历史 因此，有可能知道您应该将旧的拼写改为新的拼写，以确保阅读您的代码的人能够找到您在金字塔文档中使用的API。

python支持策略

在金字塔版本发布时，每个版本在其生命周期结束时都支持所有版本的Python。给定版本的python的生命周期结束于不再发布安全更新的时候。

要确定特定版本的金字塔对python的支持，请查看其 tox.ini 存储库版本根目录下的文件。

查阅变更历史

对于升级到新的金字塔版本导致的应用程序失败，您的第一道防线就是始终阅读 Pyramid 改变历史 在当前运行的版本和要升级到的版本之间查找每个版本的拒绝和删除。更改历史记录记录了 Deprecation 截面和每个移除 Backwards Incompatibilities 每个版本的部分。

更改历史记录通常包含更改代码以避免拒绝警告以及如何将不推荐使用的文档拼写更改为新的文档的说明。您可以按照更改历史记录中的每个拒绝解释进行操作，只需对应用程序执行grep或其他代码搜索，并使用更改日志示例修复每个潜在问题。

在新的金字塔版本下测试应用程序

一旦您将应用程序升级到新的金字塔版本，并且使用更改历史记录笔记尽可能地修正了这些问题，您将希望运行应用程序的测试（请参见 运行测试 ）以这样的方式，您可以在测试运行时看到打印到控制台的拒绝警告。

python -Wd setup.py test -q

这个 -Wd 参数告诉python将拒绝警告打印到控制台。见 the Python -W flag documentation 更多信息。

测试运行时，将在控制台上打印拒绝警告，解释拒绝，并提供有关如何防止发出拒绝警告的说明。例如：

python -Wd setup.py test -q
# .. elided ...
running build_ext
/home/chrism/projects/pyramid/env27/myproj/myproj/views.py:3:
DeprecationWarning: static: The "pyramid.view.static" class is deprecated
as of Pyramid 1.1; use the "pyramid.static.static_view" class instead with
the "use_subpath" argument set to True.
  from pyramid.view import static
.
----------------------------------------------------------------------
Ran 1 test in 0.014s

OK

在上面的例子中，它是 myproj.views 模块 (from pyramid.view import static ）这就是问题的根源：

1from pyramid.view import view_config
2
3from pyramid.view import static
4myview = static('static', 'static')

Deprecation警告告诉我如何修复它，因此我可以更改代码以更新方式执行操作：

1from pyramid.view import view_config
2
3from pyramid.static import static_view
4myview = static_view('static', 'static', use_subpath=True)

当我再次运行测试时，不预测警告将不再打印到我的控制台：

python -Wd setup.py test -q
# .. elided ...
running build_ext
.
----------------------------------------------------------------------
Ran 1 test in 0.014s

OK

我的应用程序没有任何测试或测试很少

如果您的应用程序没有测试，或者只有中等的测试覆盖率，那么运行测试不会告诉您太多，因为不会执行生成拒绝警告的金字塔代码路径。

在这种情况下，可以在使用 PYTHONWARNINGS 环境变量设置为 default . 在Unix上，您可以通过以下方式完成：

PYTHONWARNINGS=default $VENV/bin/pserve development.ini

在Windows上，您需要发出两个命令：

set PYTHONWARNINGS=default
Scripts\pserve development.ini

在这一点上，可以确保每当点击生成一个代码路径时，都会将拒绝警告打印到控制台上。然后，您可以在应用程序中以交互方式单击以尝试生成它们，并按照中的说明进行修正。 在新的金字塔版本下测试应用程序 .

见 the PYTHONWARNINGS environment variable documentation 或 the Python -W flag documentation 更多信息。

升级到最新的金字塔版本

当您将应用程序升级到最新的金字塔版本时，建议您逐步升级每个最新的次要版本，从您知道应用程序当前运行的版本开始，到最新的版本结束。例如，如果您的应用程序正在金字塔1.2.1上运行，而最新的金字塔1.3版本是金字塔1.3.3，而最新的金字塔版本是1.4.4，则建议这样做：

  • 将您的环境升级到最新的1.2版本。例如，最近的1.2版本可能是1.2.3，因此请升级到它。然后在1.2.3下运行应用程序的测试，如中所述 在新的金字塔版本下测试应用程序 . 注意任何不赞成的警告和补救措施。

  • 升级至最新的1.3版本1.3.3。运行应用程序的测试，注意任何拒绝警告，然后进行补救。

  • 升级至1.4.4。运行应用程序的测试，注意任何拒绝警告，然后进行补救。

如果您跳过在每个次要版本下测试应用程序（例如，如果您直接从1.2.1升级到1.4.4），那么您可能会错过一个拒绝警告，并且在尝试找出功能删除导致的错误时花费的时间可能比在每个次要版本中逐步升级所花费的时间要多。