yore

使用注释管理旧代码。

在古时候，先贤们书写了古老的脚本，他们的遗产代码是神秘知识的遗迹。这些崇高的、神秘的、深刻的线条，低语着往昔大师的智慧，塑造了我们数字世界的根基。

—— 智者 ChatGPT

随着时间的推移，您项目的代码库会演变。您添加功能，修复错误，并通常重新组织代码。这些变化中的一些可能使您的项目的公共 API 与先前版本不兼容。在这种情况下，您通常必须“弃用”先前的用法，以便于新的用法。这意味着您必须支持这两种用法，并在检测到旧用法时发出弃用警告。

有时，您可能不会以不兼容的方式更改任何内容，但您想要支持多个版本的Python，这些版本提供不同的、不兼容的API，或者您依赖的库提供不同的、不兼容的API。在这种情况下，您必须编写多个代码分支来支持不同的Python版本。对于比最新版本更早的Python版本的代码分支，我们称之为遗留代码。理想情况下，您可能只想使用最新Python版本的API和功能，但您的用户有时可能被限制在较老版本中，并且您希望遵循官方Python发布周期，该周期承诺在初始发布后的一定时间内支持每个小版本（3.11、3.12等）。截至本文撰写时间（2024年，请参阅Python发布周期获取最新信息），每个小版本的支持时间大约为5年。每年都有一个新小版本，因此如果您遵循发布周期，您可以在任何时间维护5个小Python版本的支持窗口。有时您可能必须支持更老的版本...

对于这些用例，Yore会伸出援手。

Yore诞生于我在项目演变过程中添加自动化注释的愿望。我通常会写一些注释，例如 TODO: 一旦放弃对Python 3.8的支持，请删除，或者 TODO: 当我们准备好v1时请删除。有一天我决定使这些注释更加正式，所以我设计了一种非常简单的语法，并编写了一个工具来解析它们并对其采取行动。

因此，Yore可以在您的代码库中找到注释，以警告您关于即将到来的Python版本的生命周期结束日期或基于项目版本的过时代码。它还可以对您的代码应用转换，以删除遗留代码块或行或更新它们。

快速使用

编写Yore注释

# YORE: EOL 3.8: Replace block with line 4.
if sys.version_info < (3, 9):
    from astunparse import unparse
else:
    from ast import unparse

检查您的代码库

$ yore check --eol-within '5 months'
./src/griffe/agents/nodes/_values.py:11: Python 3.8 will reach its End of Life within approx. 4 months

修复您的代码库

$ yore fix --eol-within '5 months'
fixed 1 comment in ./src/griffe/agents/nodes/_values.py

diff --git a/src/griffe/agents/nodes/_values.py b/src/griffe/agents/nodes/_values.py
index 59bfacac..2f6eaa88 100644
--- a/src/griffe/agents/nodes/_values.py
+++ b/src/griffe/agents/nodes/_values.py
@@ -8,11 +8,7 @@ from typing import TYPE_CHECKING
 
 from griffe.logger import get_logger
 
-# YORE: EOL 3.8: Replace block with line 4.
-if sys.version_info < (3, 9):
-    from astunparse import unparse
-else:
-    from ast import unparse
+from ast import unparse
 
 if TYPE_CHECKING:
     from pathlib import Path

查看使用文档。

安装

使用pip

pip install yore

使用pipx

python3.8 -m pip install --user pipx
pipx install yore