基于版本控制标签的Poetry动态版本插件

这是一个Python 3.7+的插件，用于Poetry 1.2.0+和Poetry Core 1.0.0+，它可以通过Dunamai实现基于版本控制系统中标签的动态版本控制。支持许多不同的版本控制系统，包括Git和Mercurial；有关完整列表（以及适用的最低支持版本），请参阅Dunamai页面。

poetry-dynamic-versioning提供了一种构建后端，它修补了Poetry Core，以启用PEP 517构建前端中的版本控制系统。当与plugin功能一起安装时（即poetry-dynamic-versioning[plugin]），它还与Poetry CLI集成，以在诸如poetry build之类的命令中触发版本控制。

对于 Poetry 1.1.x，您可以使用依赖 *.pth 导入黑客的旧版 poetry-dynamic-versioning（0.17.1 或更早版本），但此功能不再受支持，因此您应该迁移到标准插件和 Poetry 1.2.0+。

安装

如果您之前已安装了已弃用的 poetry-dynamic-versioning-plugin 包，请确保在继续之前将其卸载。

• 使用以下任一选项安装插件

  • 在大多数情况下： poetry self add "poetry-dynamic-versioning[plugin]"
  • 如果您使用 Pipx 安装了 Poetry： pipx inject poetry "poetry-dynamic-versioning[plugin]"

  有关这些选项的更多信息，请参阅 Poetry 插件文档。

• 在您的项目中运行： poetry dynamic-versioning enable

  或者您可以手动更新您的 pyproject.toml 文件

  [tool.poetry-dynamic-versioning]
  enable = true
  

  在 pyproject.toml 的 build-system 部分中包含插件，以与 PEP 517 构建前端进行互操作性

  [build-system]
  requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
  build-backend = "poetry_dynamic_versioning.backend"
  

  这是一个围绕 poetry.core.masonry.api 的轻量级包装。

Poetry 仍然需要在 pyproject.toml 中存在 tool.poetry.version 字段，但您被鼓励使用 version = "0.0.0" 作为标准占位符。

使用上述最小配置，当您运行如 poetry build 等命令时，插件将自动生效。它将更新 pyproject.toml 中的版本，然后在插件停用时撤销更改。

默认配置还将更新一些文件中的任何现有 __version__ = "0.0.0" 和 __version_tuple__ = (0, 0, 0) 占位符。您可以根据需要配置其他替换模式/文件（见下文）。

配置

在您的 pyproject.toml 文件中，您可以配置以下选项

• [tool.poetry-dynamic-versioning]：常规选项。

  • enable（布尔值，默认：false）：由于插件必须全局安装，因此此设置是每个项目的自愿选择。

  • vcs（字符串，默认：any）：这是检查版本的版本控制系统。以下之一：any、git、mercurial、darcs、bazaar、subversion、fossil、pijul。

  • metadata（布尔值，默认：未设置）：如果为 true，则将提交哈希包含在版本中，如果 dirty 为 true，则还包括一个脏标志。如果未设置，则仅在您在一个不带版本标签的提交上时包含元数据。当使用 format 或 format-jinja 时，将忽略此设置。

  • tagged-metadata（布尔值，默认：false）：如果为 true，则将发现的任何标记元数据包含在元数据段的第一部分中。当 metadata 设置为 false 时，此设置不起作用。当使用 format 或 format-jinja 时，将忽略此设置。

  • dirty（布尔值，默认：false）：如果为 true，则在元数据中包含一个脏标志，指示是否存在任何未提交的更改。当 metadata 设置为 false 时，此设置不起作用。当使用 format 或 format-jinja 时，将忽略此设置。

  • pattern（字符串）：这是一个用于查找表示版本的标签的正则表达式。当此设置未设置时，Dunamai 将使用默认模式。

    必须有一个名为 base 的捕获组，包含版本的主要部分。可选地，它可能包含另外两个名为 stage 和 revision 的组，用于预发布版本，并且可能包含一个名为 tagged_metadata 的组，用于与 tagged-metadata 选项一起使用。还可以有一个名为 epoch 的组，用于 PEP 440 概念。

    如果 base 组未包含，则此设置将解释为 Dunamai Pattern 类的命名预设之一。这包括：default、default-unprefixed（使 v 前缀可选）。

    您可以通过运行以下命令来检查您安装的 Dunamai 版本的默认值

    poetry run python -c "import dunamai; print(dunamai.Pattern.Default.regex())"
    

    请记住，在 TOML 文件中必须转义反斜杠。

    # Regular expression:
    pattern = '(?P<base>\d+\.\d+\.\d+)'
    # Named preset:
    pattern = "default-unprefixed"
    

  • pattern-prefix（字符串）：这将插入到模式的开始锚点（^）之后。例如，为了匹配类似于 some-package-v1.2.3 的标签，您可以保留默认模式并将前缀设置为 some-package-。

  • format (字符串，默认：未设置)：这定义了版本的定制输出格式。可用的替换项

    • {base}
    • {stage}
    • {revision}
    • {distance}
    • {commit}
    • {dirty}
    • {tagged_metadata}
    • {branch}
    • {branch_escaped}，忽略任何非字母/数字字符
    • {timestamp}为当前提交的，展开为UTC的YYYYmmddHHMMSS

    示例：v{base}+{distance}.{commit}

  • format-jinja (字符串，默认：未设置)：这定义了版本的定制输出格式，使用Jinja模板。当此设置时，format被忽略。

    可用变量

    • base (字符串)
    • stage (字符串或None)
    • revision (整数或None)
    • distance (整数)
    • commit (字符串)
    • dirty (布尔值)
    • tagged_metadata (字符串或None)
    • version (dunumai.Version)
    • env (环境变量字典)
    • branch (字符串或None)
    • branch_escaped (字符串或None)
    • timestamp (字符串或None)

    可用函数

    • bump_version (来自Dunamai)
    • serialize_pep440 (来自Dunamai)
    • serialize_semver (来自Dunamai)
    • serialize_pvp (来自Dunamai)

    简单示例

    format-jinja = "{% if distance == 0 %}{{ base }}{% else %}{{ base }}+{{ distance }}.{{ commit }}{% endif %}"
    

    复杂示例

    format-jinja = """
        {%- if distance == 0 -%}
            {{ serialize_pep440(base, stage, revision) }}
        {%- elif revision is not none -%}
            {{ serialize_pep440(base, stage, revision + 1, dev=distance, metadata=[commit]) }}
        {%- else -%}
            {{ serialize_pep440(bump_version(base), stage, revision, dev=distance, metadata=[commit]) }}
        {%- endif -%}
    """
    

  • format-jinja-imports (表格数组，默认：空)：这定义了要导入并使可用给format-jinja模板的额外事物。每个表格必须包含一个module键，也可以包含一个item键。考虑以下示例

    format-jinja-imports = [
        { module = "foo" },
        { module = "bar", item = "baz" },
    ]
    

    这大致相当于

    import foo
    from bar import baz
    

    foo和baz将可在Jinja格式化中使用。

  • style (字符串，默认：未设置)：以下之一：pep440、semver、pvp。这些都是预配置的输出格式。如果您设置了style和format，则格式将根据样式的规则进行验证。如果未设置style，则默认输出格式将遵循PEP 440，但自定义format仅在显式设置style时才进行验证。

  • latest-tag (布尔值，默认：false)：如果为true，则只检查最新的标签版本，而不是查找所有标签直到找到适合的匹配pattern的标签。

  • bump (布尔值，默认：false)：如果为true，则将版本base的最后部分增加1，除非设置了stage，在这种情况下增加revision 1，或者如果未设置revision，则将其设置为默认的2。在带有版本标签的提交上不执行任何操作。

    示例，自v1.3.1标签以来已有3次提交

    • PEP 440与bump = false：1.3.1.post3.dev0+28c1684
    • PEP 440与bump = true：1.3.2.dev3+28c1684

  • tag-dir (字符串，默认：tags)：这是相对于根的标签位置。这仅用于Subversion。

  • tag-branch (字符串，默认：未设置)：在当前分支不同的分支上查找标签。这目前仅用于Git。

  • full-commit (布尔值，默认：false)：如果为true，则获取完整的提交哈希值而不是短形式。这仅用于Git和Mercurial。

  • strict (布尔值，默认：false)：如果为true，则在没有标签的情况下失败而不是回退到0.0.0。

  • fix-shallow-repository (布尔值，默认：false)：如果为 true，则自动尝试修复浅层仓库。目前，这仅支持 Git，并将运行 git fetch --unshallow。

  • ignore-untracked (布尔值，默认：false)：如果为 true，则在确定仓库是否脏时忽略未跟踪的文件。

• [tool.poetry-dynamic-versioning.substitution]：将动态版本插入除 pyproject.toml 之外的额外文件。这些更改将在插件停用时撤销。

  • files (字符串数组)：需要替换的任何文件的 glob。默认：["*.py", "*/__init__.py", "*/__version__.py", "*/_version.py"]。要禁用替换，将其设置为空列表。

  • patterns (字符串/表数组)：要替换的文本的正则表达式。每个正则表达式必须有两个捕获组，这些组是替换文本前后要保留的任何文本。

    字符串项直接解释为正则表达式。表项支持以下键

    • value (字符串)：这是正则表达式。
    • mode (字符串，可选)：这控制版本应该如何插入。选项
      • str (默认)：按原样序列化版本。捕获组应已包括周围的引号。
      • tuple：将 0.1.2.dev0+a.b 序列化为 0, 1, 2, "dev0", "a.b"。捕获组应已包括周围的括号。

    默认

    patterns = [
        '''(^__version__\s*(?::.*?)?=\s*['"])[^'"]*(['"])''',
        { value = '''(^__version_tuple__\s*(?::.*?)?=\s*\()[^)]*(\))''', mode = "tuple" },
    ]
    

    请记住，在 TOML 文件中必须转义反斜杠。

  • folders (表数组，默认：空)：要检查替换的额外文件夹列表。

    每个表支持以下选项

    • path (字符串，必需)：文件夹的路径。
    • files (字符串数组，可选)：为该文件夹覆盖 substitution.files。
    • patterns (字符串数组，可选)：为该文件夹覆盖 substitution.patterns。

    如果你使用 src 布局，你可能希望保留默认的 files/patterns，并且只需指定以下内容

    folders = [
      { path = "src" }
    ]
    

    这将检查默认的文件 glob（例如，./*.py），以及 src 内的相同文件 glob（例如，./src/*.py）。

• [tool.poetry-dynamic-versioning.files] (表，默认：空)：此部分允许你调整单个文件的特定行为。每个表键是相对于项目根的特定文件的路径（没有 glob）。每个嵌套表支持以下字段

  如果你使用这些选项生成一个被你的 VCS 忽略的文件，但你还希望该生成的文件包含在 poetry build 的输出中，那么你需要在你的 tool.poetry.include 配置中明确命名该文件。

  • persistent-substitution (布尔值，可选)：如果为 true，则不撤销此文件应用的任何替换。这对于可编辑安装非常有用，如果你需要版本保留在由你的 VCS 忽略的文件中。

  • initial-content (字符串，可选)：在替换阶段之前设置文件内容。根据需要创建或覆盖文件。将从每行中删除常见的开头的空白字符。

  • initial-content-jinja (字符串，可选)：与 initial-content 相同，但使用 Jinja 格式化。如果同时设置这两个选项，则此选项优先。你可以使用来自 format-jinja-imports 的相同导入和来自 format-jinja 的相同变量，以及此附加变量

    • formatted_version (字符串) - 由 format 或 format-jinja 选项格式化的版本

  示例

  [tool.poetry-dynamic-versioning.files."package/_version.py"]
  persistent-substitution = true
  initial-content = """
    # These version placeholders will be replaced later during substitution.
    __version__ = "0.0.0"
    __version_tuple__ = (0, 0, 0)
  """
  

• [tool.poetry-dynamic-versioning.from-file]：此部分允许你从文件中读取版本而不是从 VCS 中读取。

  • source (字符串)：如果设置，从此文件中读取版本。它必须是相对于 pyproject.toml 位置的路径。默认情况下，插件将读取文件的全部内容，不包括前导和尾随空白。
  • pattern (字符串)：如果设置，使用此正则表达式从文件中提取版本。第一个捕获组必须包含版本。

简单示例

[tool.poetry-dynamic-versioning]
enable = true
vcs = "git"
style = "semver"

环境变量

除了上面的项目特定配置之外，你还可以通过环境变量应用一些全局覆盖。

• POETRY_DYNAMIC_VERSIONING_BYPASS：使用此选项可绕过版本控制系统机制并使用静态版本。环境变量的值将用作活动项目的版本以及任何也使用该插件的路径/SSH依赖项。这主要用于需要修补现有发布版本而无需访问原始存储库的发行版包维护者。
• POETRY_DYNAMIC_VERSIONING_OVERRIDE：仅对特定包使用静态版本，但其他情况下仍启用动态版本。例如，pkg1 = 0.1.0, pkg2 = 0.2.0（空格可选）将pkg1设置为0.1.0，将pkg2设置为0.2.0。这仅影响已启用poetry-dynamic-versioning的包。当两个变量都设置时，OVERRIDE比BYPASS具有优先级。
• POETRY_DYNAMIC_VERSIONING_COMMANDS：可以在激活版本版的Poetry命令中设置逗号分隔的列表。例如，build,publish将动态版本限制在这两个命令中。类似地，设置POETRY_DYNAMIC_VERSIONING_COMMANDS=""将完全禁用动态版本，这在如Docker这样的隔离环境中很有用，其中版本可能不再可计算也不需要。
• POETRY_DYNAMIC_VERSIONING_COMMANDS_NO_IO：逗号分隔的Poetry命令列表，在这些命令期间插件不应直接修改文件。插件仍将在内存中设置动态版本，以便Poetry本身在需要时可以写入它。默认：version。
• POETRY_DYNAMIC_VERSIONING_DEBUG：如果设置为1，则某些调试日志将打印到stderr。目前，它记录了一些替换找不到要更改的内容的情况。

命令行模式

插件还具有命令行模式，可在需要时执行。此模式将动态版本应用于所有相关文件，并保留更改，以便您可以检查结果。您的配置将像通常一样从pyproject.toml检测到，但不需要enable选项。

要激活此模式，可以使用poetry dynamic-versioning（由plugin功能提供）或poetry-dynamic-versioning（具有默认功能的独立脚本）。

VCS存档

有时，您可能只能访问存储库的存档（例如，zip文件），而没有完整的记录。在这些情况下，插件仍可以检测到一些版本。有关更多信息，请参阅Dunamai文档。

注意事项

所有Dunamai的注意事项都适用。除了那些

• 由于Poetry设计选择阻止插件自行清理，因此动态版本在poetry run或poetry shell期间不可用。

• 关于PEP 517支持

  如果Pip版本足够新，默认为树内构建或支持--use-feature=in-tree-build选项，则pip wheel .和pip install .将正常工作。较旧的Pip版本将无法正常工作，因为它们创建了一个不包含版本控制历史的源代码的独立副本。

  如果您想构建依赖项的轮盘，可以这样做，尽管基于本地路径的依赖项可能不起作用

  poetry export -f requirements.txt -o requirements.txt --without-hashes
  pip wheel -r requirements.txt