raincoat 1.2.4

问题

假设您正在使用一个名为umbrella的库，它提供了一个名为use_umbrella的函数，其代码如下

def use_umbrella(umbrella):

    # Prepare umbrella
    umbrella.remove_pouch()
    umbrella.open()

    # Use umbrella
    while rain_detector.still_raining():
        umbrella.keep_over_me()

    # Put umbrella away
    umbrella.close()
    while not umbrella.is_wet():
        time.sleep(1)
    umbrella.put_pouch()

此函数做了它所说的，但没有理想地分割，这取决于您的需求。例如，您可能会在某一点意识到您需要将3个单独的部分各自成为一个函数。或者您不能在您的应用程序中调用time.sleep。或者当umbrella打开时，对其进行其他操作，比如和它跳舞。

也可能你无法真正发起一个拉取请求，因为你的需求很特殊，或者你没有时间（这很遗憾，但，嘿，我知道这种情况会发生）或者任何其他个人原因。那么你该怎么办呢？实际上没有真正的替代方案。你只能复制/粘贴代码，修改它以满足你的需求，并使用你的修改版本。而且每当上游功能发生变化时，你很可能永远不知道。

解决方案

请进入Raincoat。

你已经创建了 umbrella.use_umbrella （umbrella当时版本为14.5.7）的私有副本，它看起来像这样

def dance_with_umbrella(umbrella):
    """
    I'm siiiiiinging in the rain!
    """
    # Prepare umbrella
    umbrella.remove_pouch()
    umbrella.open()

    # Use umbrella
    while rain_detector.still_raining():
        Dancer.sing_in_the_rain(umbrella)

    # Put umbrella away
    umbrella.close()
    while not umbrella.is_wet()
        time.sleep(1)
    umbrella.put_pouch()

现在只需在某个地方添加一条注释（最好是文档字符串之后）说类似的话

def dance_with_umbrella(umbrella):
    """
    I'm siiiiiinging in the rain!
    """
    # This code was adapted from the original umbrella.use_umbrella function
    # (we just changed the part inside the middle while loop)
    # Raincoat: pypi package: umbrella==14.5.7 path: umbrella/__init__.py element: use_umbrella

    ...

现在，在你的项目中安装并运行 raincoat

$ pip install raincoat
$ raincoat

它会

查找代码中的所有 # Raincoat: 注释，并对每个注释

1. 查看当前安装的库版本（例如，umbrella 16.0.3）（或者如果找不到，则是最新版本）

2. 将版本与Raincoat注释中的版本进行比较（这里为14.5.7）

3. 如果它们不同，则下载并在临时目录中安装指定的版本（使用pip默认使用的缓存wheel，这在大多数情况下应该相当快）

4. 使用提供的路径定位下载版本和当前安装版本中的代码

5. 比较它们

6. 告诉你是否有差异（并指出原始Raincoat注释的位置）

无论是否有需要更改的内容，你现在已经使用umbrella 16.0.3验证了你的代码，因此你可以手动更新umbrella注释。

# Raincoat: pypi package: umbrella==16.0.3 path: umbrella/__init__.py element: use_umbrella"

Raincoat可以用作代码检查器，你可以将其集成到CI中，使其成为tox目标...

等等！

实际上，Raincoat的基本原理可以扩展到PyPI包以外的许多其他主题。为了适应这一点，Raincoat被编写成一个模块化架构，允许其他类型的Raincoat注释。

目前Raincoat包含

• PyPI：上面提到的模块

• Django：一个模块，用于检查你为Django中可能需要编写的解决方案的bug是否在Django的（或最新版本）中已修复。语法是

# Raincoat: django ticket: #26976

• PyGitHub：与PyPI模块相同，但使用Github。如果你的上游是一个不在PyPI上的Python包，例如Python标准库本身，这很有用。比如说，你想知道文件 Lib/mailbox.py 中的元素 Maildir._lookup 自提交43ba8861以来在master分支上是否有变化。你可以这样做

# Raincoat: pygithub repo: python/cpython@43ba8861 branch: master path: Lib/mailbox.py element: Maildir._lookup

你也可以创建自己的Raincoat注释检查器。

你可以访问 快速入门 部分进行一般了解，或访问 如何使用 部分了解具体功能。希望 讨论 部分可以回答你的问题。否则，请随意打开一个 问题。

从这里开始

完整的 文档 可能是了解这个项目的最佳地方。

如果你遇到错误，或者想取得联系，你总是可以打开一个 问题。