跳转到主要内容

​
用于 Python 的 pyproject.toml 文件

pyproject.toml 文件是一种现代方式，可在单个文件中指定项目的所有构建系统需求和依赖。本指南将展示如何创建、配置和使用 pyproject.toml，以确保开发环境和生产环境之间的一致性。

​
什么是 pyproject.toml 文件？

pyproject.toml 列出了 Python 项目的依赖、构建系统和其他元数据。这样可以：
  • 让你和你的团队维护完全相同的环境
  • 让新协作者精确地复现环境
  • 分别配置开发依赖和生产依赖
1

创建 pyproject.toml 文件

首先，在项目根目录下创建一个名为 pyproject.toml 的文件。
2

定义项目详情

在 pyproject.toml 文件中，先定义你的项目元数据。我们将定义项目名称、版本、描述以及其他相关信息。
项目名称必须由 ASCII 字母、数字、下划线“_”、连字符“-”和句点“.”组成。名称不能以下划线、连字符或句点开头或结尾。例如：
pyproject.toml
[project]
name = "my-python-project"
description = "A sample Python project using pyproject.toml"
version = "1.0.0"
3

列出项目依赖

接下来，我们将列出项目所需的依赖。我们可以同时指定开发依赖和生产依赖。生产依赖列在 dependencies 部分下，而开发依赖可以列在 optional-dependencies 下并使用特定的组名（例如 dev）。
你可以使用比较运算符（如 ==、>=、<……）为依赖指定版本。在下面的示例中，我们没有指定版本，这意味着将安装最新版本。 建议指定精确版本，以确保可复现性，并防止生产环境中因不兼容的更新而出现故障。
pyproject.toml
[project]
name = "my-python-project"
description = "A sample Python project using pyproject.toml"
version = "1.0.0"
dependencies = [
    "discord-py",
    "aiohttp"
]

[project.optional-dependencies]
dev = [
    "pytest",
    "black"
]
4

配置构建系统

最后，我们需要指定构建系统的需求。这对于像 pip 这样的工具了解如何构建和安装你的项目是必需的。我们将使用 setuptools 作为构建后端，这是 Python 项目的常见选择，但你也可以选择其他后端，如 poetry。
pyproject.toml
[project]
name = "my-python-project"
description = "A sample Python project using pyproject.toml"
version = "1.0.0"
dependencies = [
    "discord.py",
    "aiohttp"
]

[project.optional-dependencies]
dev = [
    "pytest",
    "black"
]

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

​
使用 pip 安装依赖

要安装 pyproject.toml 文件中列出的依赖，你可以使用 pip 或其他支持 pyproject.toml 的工具。这样你就可以在安装好依赖的情况下开展项目工作。 
pip install .
此命令会读取 pyproject.toml 文件，安装 dependencies 下列出的依赖，并为开发配置好你的项目。如果你还想安装开发依赖，可以使用： 
pip install .[dev]
这将同时安装生产依赖和开发依赖，让你能够使用所有必要的工具开展项目工作。

​
最佳实践与技巧：

  • 保持更新：在添加新依赖时，定期检查并更新 pyproject.toml
  • 使用精确版本：始终使用 ==，而不是 >、>= 或不指定版本，以避免生产环境中的意外
  • 版本控制：将 pyproject.toml 提交到 git，以跟踪依赖变更和版本更新
  • 隔离环境：为每个项目维护一个虚拟环境，以避免全局冲突
  • 本地测试：在部署之前，在一个新环境中使用 pip install . 测试该文件

​
后续步骤

配置好 pyproject.toml 文件后：
  1. 提交到你的 Git 仓库。
  2. 在 Square Cloud 上托管你的项目。
  3. 通过 GitHub 配置自动 deploy。
  4. 欢迎来到专业的 Python 应用托管！
结构良好的 pyproject.toml 文件是任何成功的 Python 应用的基础，确保你的应用在 Square Cloud 上完美运行。