掌握 Poetry new 命令：理解其行为变更与项目初始化策略

发布日期： 2025-11-26 阅读量： 作者： 花韻仙語

poetry 的 `new` 命令在项目初始化行为上发生了显著变化。自 2025 年 4 月起，它不再默认生成测试文件（如 `test_*.py`），且 `__init__.py` 文件也默认为空。本文将深入解析这些变更，指导用户如何适应新的初始化流程，并强调查阅最新官方文档的重要性，以确保项目设置的准确性与高效性。

理解 Poetry 项目初始化行为的演进

Poetry 作为一个现代 Python 依赖管理和打包工具，其设计理念之一是提供简洁高效的开发体验。然而，软件工具会随着时间的推移和社区反馈进行迭代更新，Poetry 也不例外。一个重要的行为变更发生在 2025 年 4 月，具体体现在其 poetry new 命令的项目初始化流程上。

在此变更之前，当用户执行 poetry new 命令时，Poetry 会自动在项目根目录下创建一个 tests 目录，并在其中生成一个示例测试文件（通常是 test_.py）。此外，项目模块内的 __init__.py 文件也可能包含一些默认内容。

然而，为了提供更灵活、更少侵入性的项目骨架，Poetry 团队决定调整这一默认行为。根据相关提交记录，自该时间点起：

不再自动生成测试文件： poetry new 命令不再默认创建 tests 目录及其内部的 test_*.py 文件。
__init__.py 文件默认为空： 生成的 Python 包结构中的 __init__.py 文件将是空的。

这一变化旨在让开发者对项目的初始结构拥有更大的控制权，允许他们根据具体需求自行决定测试框架和模块初始化方式。

应对行为变更：项目初始化与测试设置的最佳实践

由于 Poetry 的行为发生了变化，一些早期的教程或文档可能未能及时更新，导致用户在使用新版 Poetry 时发现与教程描述不符的情况。为了确保项目能够正确初始化并顺利进行测试开发，以下是一些推荐的实践方法：

1. 初始化项目

使用 poetry new 命令创建新项目的基础步骤保持不变：

poetry new my-project

执行此命令后，Poetry 会创建一个名为 my-project 的目录，其中包含以下基本结构：

my-project/
├── pyproject.toml
├── README.md
├── my_project/
│   └── __init__.py
└── .gitignore

可以看到，tests 目录和 test_my_project.py 文件并未自动生成，且 my_project/__init__.py 是空的。

2. 手动设置测试环境

由于 Poetry 不再自动生成测试文件，您需要手动创建测试目录和文件。

步骤一：创建 tests 目录

mkdir my-project/tests

步骤二：创建测试文件

在 tests 目录下创建您的测试文件，例如 test_example.py。您可以根据需要选择不同的测试框架（如 pytest 或 unittest）。

以 pytest 为例，创建一个简单的测试文件 my-project/tests/test_example.py：

# my-project/tests/test_example.py

from my_project import __version__

def test_version():
    assert __version__ == "0.1.0" # 假设pyproject.toml中版本为0.1.0

步骤三：安装测试依赖

如果您使用 pytest，需要将其添加到开发依赖中：

cd my-project
poetry add pytest --group dev

然后，您就可以运行测试了：

poetry run pytest

3. 关于 init.py 文件

__init__.py 文件是 Python 包的标志，它的存在告诉 Python 解释器该目录是一个包。当它为空时，意味着该包没有默认的初始化逻辑或需要导出的顶层对象。

在大多数情况下，空的 __init__.py 文件是完全可以接受的。只有当您需要执行以下操作时，才需要向其中添加内容：

定义包的元数据： 例如 __version__、__author__ 等。
简化模块导入： 将子模块或子包中的特定函数、类直接导入到父包的命名空间，以便用户可以直接从父包导入，而无需深入到子模块。

例如，如果您希望在 my_project/__init__.py 中定义版本信息，可以这样修改：

# my-project/my_project/__init__.py

__version__ = "0.1.0"

这样，其他模块就可以通过 from my_project import __version__ 来访问版本号。

关键注意事项与总结

始终查阅最新官方文档： 这是最重要的建议。Poetry 的官方文档（python-poetry.org/docs/）是获取最新、最准确信息的最佳来源。当您遇到与教程不符的行为时，第一时间应参考官方文档，尤其是 CLI 命令部分的说明。
理解工具演进： 软件工具会不断发展。过时的教程虽然有参考价值，但不能完全依赖。理解工具行为可能发生变化是现代软件开发者的基本素养。
自定义项目结构： Poetry 的新行为赋予了开发者更大的自由度。您可以根据项目的具体需求，自由选择测试框架、目录结构和模块初始化方式。

通过理解 Poetry new 命令的最新行为，并结合官方文档和最佳实践，您将能够更高效、更准确地初始化和管理您的 Python 项目。

上一篇: 如何安装WINDOWS系统（三）

下一篇: Airtest IDE 自动化测试13 - 报告加截图 sn

掌握 Poetry new 命令：理解其行为变更与项目初始化策略

随便看看

南昌壹佳企网络通信有限公司