Python Academy · 课时

项目结构与 pyproject.toml

Q: 「项目结构与 pyproject.toml」课时是免费的吗？

是的 — 「项目结构与 pyproject.toml」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Python Academy 课程的其余内容，请升级到 CoddyKit PRO。 Python Academy 课程共包含 4 节课。

Q: 「项目结构与 pyproject.toml」这节课中我会学到什么？

规划软件包结构 你通过在浏览器中直接运行的动手代码来练习 Python Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

Q: 学习 Python Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Python Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 1 节课，共 4 节。

Q: 「项目结构与 pyproject.toml」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

Q: 我能在这节 Python Academy 课中编写并运行代码吗？

能。每节 Python Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

规划软件包结构

项目结构与 pyproject.toml 是 CoddyKit 上的免费 Python Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Python Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Python Academy 课程共包含 4 节课。

为什么要将代码打包

脚本存在于您的计算机上，而包可以由任何人通过 pip install 安装。打包会将一个代码文件夹变成可分发、带版本且可复用的单元。

第一步是整理出清晰的项目布局和配置文件。

src 布局

推荐的结构会将可导入的代码放在 src/ 目录下：

src/mypackage/__init__.py
src/mypackage/core.py
pyproject.toml
README.md 和 tests/

src 布局可以防止代码从项目根目录被意外导入，而不是从已安装的副本中导入。

init.py 文件

__init__.py 会将目录标记为可导入的包，并在包首次导入时运行。您还可以在其中导入关键名称，以公开包的公共接口。

即使是空的 __init__.py，也足以构成一个包。

package_dir = 'src/mypackage'
files = ['__init__.py', 'core.py', 'utils.py']
for f in files:
    print(package_dir + '/' + f)
print('Importable as:', 'mypackage')

pyproject.toml 是什么

pyproject.toml 是现代 Python 打包所使用的单一标准化配置文件（PEP 518/621）。对于大多数项目，它取代了旧的 setup.py，并由构建工具读取。

它使用 TOML 格式：节写在方括号中，行采用键 = 值的形式。

build-system 表

[build-system] 表会告诉工具如何构建您的包。常见的选择是：

requires = ['setuptools', 'wheel']
build-backend = 'setuptools.build_meta'

其他构建后端包括 Hatchling 和 Flit；理念相同。

project 表

[project] 表包含元数据：name、version、description、authors、readme、requires-python 和 dependencies。用户会在 PyPI 上看到这些信息。

可以把它看作您这个包的身份证。

project = {
    'name': 'mytool',
    'version': '0.1.0',
    'requires-python': '>=3.9',
    'dependencies': ['requests>=2.0'],
}
for k, v in project.items():
    print(k, '=', v)

命名规则

包名必须在 PyPI 上唯一，并遵循规范化规则：不区分大小写，连字符和下划线视为相同。在确定名称前请先检查其可用性，以免上传时发生冲突。

name = 'My_Cool.Tool'
normalized = name.lower().replace('_', '-').replace('.', '-')
print('PyPI normalized name:', normalized)

声明依赖项

在 dependencies 下列出运行时依赖项，并使用类似 'requests>=2.28,<3' 的版本约束。可选的额外依赖项放在 [project.optional-dependencies] 下，可以通过 pip install mytool[dev] 安装。

在安全的前提下，应尽量放宽约束，使您的包能与其他包共存。

入口点

要发布命令行工具，请添加类似 [project.scripts] 中的入口点：mytool = 'mypackage.cli:main'。安装后，输入 mytool 就会运行该函数。这正是 black 或 pytest 等命令行界面公开其命令的方式。

包含非代码文件

数据文件（模板、JSON）不会自动包含在内。请在构建后端中配置包数据，以便将文件打包到分发包中。忘记这一步是导致“本地正常、安装后却崩溃”问题的常见原因。

用于开发的可编辑安装

开发期间，请使用 pip install -e . 以可编辑模式安装您的包。源代码的更改会立即生效，无需重新安装。这依赖于正确的 pyproject.toml，也是应该尽早完成配置的另一个原因。

在迭代开发包时，可编辑安装能提供最快的反馈循环。

快速检查

测试您对项目结构的了解。

回顾

您已经完成了包的布局：

使用src 布局，并用 __init__.py 标记包
pyproject.toml 是标准配置文件，包含 [build-system] 和 [project]
声明 name、version、requires-python 和 dependencies
为命令行界面添加 [project.scripts] 入口点，并配置包数据

常见问题解答