跳转至

Python 开发环境配置最佳实践

预计阅读时长 : 13 分钟

在 Python 开发中，版本管理和依赖管理是两个关键问题。本文将介绍如何使用 Pyenv 和 Poetry 配合搭建一个完整的 Python 开发环境：

  • Pyenv：管理项目使用的 Python 版本
  • Poetry：管理项目依赖和构建发布

Pyenv 安装与配置

Pyenv 是一个用于管理 Python 版本的工具，可以方便地在不同版本的 Python 之间切换。

安装

首先让我们安装 Pyenv，直接在终端中执行以下命令：

1
curl https://pyenv.run | bash

然后将以下配置添加到 shell 配置文件（~/.bashrc 或 ~/.zshrc），并重启终端：

1
2
3
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

安装 Python 版本

接下去，我们就可以根据需要安装需要的 Python 版本了。

1
2
3
4
5
# 查看可用的 Python 版本
pyenv install --list

# 安装特定版本
pyenv install 3.12.1

查看已安装的 Python 版本

在 Pyenv 中，我们一般会安装多个 Python 版本，可以使用 pyenv versions 来查看所有已安装的 Python 版本：

1
pyenv versions

其中，使用 * 标记的就是当前正在路径下正在使用的 Python 版本。

设置全局默认版本

在 Pyenv 中，我们可以为系统设置一个全局的默认版本，这样默认情况下 python 命令都会使用这个版本：

1
pyenv global 3.12.1

后面我们会通过 pyenv local 来为某个项目设置独立的 Python 版本。

Poetry 安装与配置

Poetry 是 Python 的全流程包管理工具，可以用来管理项目依赖、构建项目、发布项目等。

为了方便管理，除了 Fork 的项目一般建议延续使用原作者的包管理工具之外，其他个人新项目都推荐使用 Poetry 来统一管理。

安装

Poetry 的安装非常简单，只需要执行以下命令即可：

1
curl -sSL https://install.python-poetry.org | python3 -

初始化

不管项目之前使用的是哪种包管理工具，都可以使用 Poetry 接管项目。

执行以下命令会启动交互式配置向导，帮助创建 pyproject.toml 文件：

1
poetry init

初始化过程中会询问包名称、版本、描述、作者、许可证、Python 版本依赖等信息。如果暂时不确定，可以直接按回车使用默认值，后续可以手动修改 pyproject.toml。

也可以直接使用 -n 参数来跳过交互式配置，直接使用默认值。

1
poetry init -n

关闭包管理模式

Poetry 默认会将项目作为一个包来管理，这会要求项目必须按照特定的格式来组织。

如果我们只是想使用 Python 来写一些脚本，或者作为自己独享的项目，那么可以关闭在 pyproject.toml 中添加配置项 package-mode 来关闭包管理模式。

1
2
[tool.poetry]
package-mode = false

项目 Python 版本配置

一个使用 Poetry 管理的 Python 项目，其 Python 版本管理主要涉及两个方面：

  1. pyproject.toml 中声明项目支持的 Python 版本范围
  2. 虚拟环境中实际使用的具体 Python 版本

首先，在 pyproject.toml 中，应该根据项目需求声明合适的 Python 版本范围：

1
2
[tool.poetry.dependencies]
python = ">=3.8,<4.0"  # 支持 Python 3.8 及以上的所有 3.x 版本

版本约束

建议使用相对宽松的版本范围（如 >=3.8,<4.0），而不是固定版本（如 ==3.8.0）。

然后，使用 pyenv local 命令指定项目使用的具体 Python 版本，这个命令会在当前项目目录下创建 .python-version 文件：

1
pyenv local 3.12.1

最后，指定 Poetry 使用项目 Python 版本创建虚拟环境：

1
poetry env use $(pyenv which python)

集成终端 Python 版本

需要注意的是，默认情况下，集成终端的 Python 版本并不会跟随项目 Python 版本的变化而变化，而是会使用 pyenv 的全局默认版本。

如果希望集成终端的 Python 版本能够跟随项目 Python 版本的变化而变化，可以使用 source .venv/bin/activate 命令来激活项目虚拟环境。

管理项目依赖

poetry 有自己一套单独的命令，和 pip 并不通用，但常用命令不超过 10 个，只需要掌握这些就足够了。

迁移已有项目

对于使用 pip 和 requirements.txt 的已有项目，可以通过以下的命令来迁移到 Poetry：

1
2
# 安装 requirements.txt 中的所有依赖
cat requirements.txt | xargs poetry add

如果对依赖版本不敏感，也可以去除所有的版本限制，直接安装最新版本。

1
2
# 移除所有版本约束并安装
cat requirements.txt | sed 's/==.*//g' | sed 's/>.*//g' | sed 's/<.*//g' | xargs poetry add

安装依赖

1
poetry add <package>

安装完成之后，此时项目中的 pyproject.toml 也发生了变化。

如果需要安装指定版本，可以使用 @ 符号。

1
poetry add <package>@<version>

add 命令背后的操作

除了更新 pyproject.toml ，此时项目中还会添加一个文档，名为 poetry.lock ，它实际上就相当于 pip 的 requirements.txt ，详细记录了所有安装的模块与版本。

当使用 poetry add 指令时，poetry 会自动依序帮你做完这三件事：

  • 更新 pyproject.toml。
  • 依照 pyproject.toml 的内容，更新 poetry.lock 。
  • 依照 poetry.lock 的内容，更新虚拟环境。

由此可见， poetry.lock 的内容是取决于 pyproject.toml ，但两者并不会自己连动，一定要基于特定指令才会进行同步与更新， poetry add 就是一个典型案例。

更新 lock

当你自行修改了 pyproject.toml 内容，比如变更特定模块的版本（这是有可能的，尤其在手动处理版本冲突的时候）。此时 poetry.lock 的内容与 pyproject.toml 出现了脱钩，必须让它依照新的 pyproject.toml 内容更新、同步。

1
poetry lock

但要特别注意的是， poetry lock 指令，仅会更新 poetry.lock ，不会同时安装模块至虚拟环境。

因此，在执行完 poetry lock 指令后，必须再使用 poetry install 来安装模块。

1
poetry install

更新依赖

1
poetry update

删除依赖

1
poetry remove <package>

查看依赖

1
poetry show

发布项目

Poetry 除了可以在本地管理项目依赖之外，还可以便捷地将项目发布到 PyPi 上。

项目架构

对于需要发布到 PyPi 上的项目，我们需要将其项目结构调整为如下：

1
2
3
4
5
6
7
my-project/
├── pyproject.toml
├── poetry.lock
├── src/
│   └── my_project/
│       └── __init__.py
└── tests/

注意，还需要在 pyproject.toml 中删除 package-mode 配置项，否则发布会失败。

PyPi 授权

然后，我们需要在 PyPi 上创建一个账户，并创建 API Token。然后，我们使用该 Token 对在本地对 Poetry 进行授权。

1
poetry config pypi-token.pypi <token>

构建项目

构建项目，实际上就是将项目打包成一个标准的压缩包。打包之后的文件通常会包含以下两个文件：

  • 源码压缩包
  • 二 制压缩包

我们可以在项目根目录下使用 poetry build 命令来构建项目，最后会生成一个 dist 文件夹，里面就是构建好的压缩包。

1
poetry build

配置项目

在上传项目之前，我们还需要对 pyproject.toml 文件进行一些配置。

主要是添加项目描述、作者、许可证等信息，以及修改版本信息等。

最好是能够再增加 changes.log 文件，来记录项目的变更历史等。

发布项目

发布项目，实际上就是将构建好的压缩包上传到 PyPi 上。

在发布的时候，poetry 会自动将 dist 文件夹中的压缩包上传到 PyPi 上。并根据 pyproject.toml 中的信息来上传其他的信息。

1
poetry publish

参考文档