poetry 的 `new` 命令在项目初始化行为上发生了显著变化。自 2021 年 4 月起，它不再默认生成测试文件（如 `test_*.py`），且 `__init__.py` 文件也默认为空。本文将深入解析这些变更，指导用户如何适应新的初始化流程，并强调查阅最新官方文档的重要性，以确保项目设置的准确性与高效性。
理解 Poetry 项目初始化行为的演进
Poetry 作为一个现代 Python 依赖管理和打包工具，其设计理念之一是提供简洁高效的开发体验。然而，软件工具会随着时间的推移和社区反馈进行迭代更新，Poetry 也不例外。一个重要的行为变更发生在 2021 年 4 月，具体体现在其 poetry new 命令的项目初始化流程上。
在此变更之前，当用户执行 poetry new <project-name> 命令时，Poetry 会自动在项目根目录下创建一个 tests 目录，并在其中生成一个示例测试文件（通常是 test_<project_name>.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 目录
在项目根目录下创建 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 项目。
