Poetry 是一个现代的 Python 包管理工具,它不仅能够管理依赖,还可以构建和发布 Python 包。Poetry 的目标是简化 Python 项目的管理,替代传统的 requirements.txt
、setup.py
和 pip
等工具。下面是 Poetry 的简要教程说明,包括安装、常用命令和基本使用。
1. 安装 Poetry
Poetry 可以通过 Python 包管理工具 pip
或官方安装脚本安装。
# 使用 `pip` 安装
pip install poetry
# 使用官方安装脚本安装(推荐 🌟)
curl -sSL https://install.python-poetry.org | python3 -
安装完成后,你可以通过以下命令确认 Poetry 是否安装成功:
poetry --version
# 查看当前配置
poetry config --list
2. 初始化 Poetry 项目
❶ 初始化新的项目
Poetry 可以用来快速初始化一个新的 Python 项目。通过 poetry new
命令创建一个项目。
|
|
这将创建一个新的 my_project
目录,包含一个基本的 Python 包结构:
/my_project
/my_project
__init__.py
pyproject.toml
README.rst
tests
__init__.py
test_my_project.py
pyproject.toml
文件是 Poetry 的核心配置文件,用于描述项目的元数据、依赖关系、构建工具等。
❷ 初始化已有项目
还可以通过 poetry init
:初始化当前目录为一个 Poetry 项目(创建 pyproject.toml
)。
3. 管理项目依赖
Poetry 提供了非常简洁的命令来管理项目的依赖,包括安装、添加、删除等操作。
❶ 添加依赖:
使用 poetry add
来添加依赖,支持通过指定版本号来精确安装依赖。
|
|
你也可以添加开发依赖(如测试框架):
|
|
❷ 查看当前依赖:
查看项目的所有依赖,可以使用:
|
|
❸ 删除依赖:
如果需要删除某个依赖,可以使用:
|
|
4. 虚拟环境管理
Poetry 会自动为每个项目创建一个独立的虚拟环境来隔离项目依赖。你可以通过以下命令查看虚拟环境的路径:
|
|
💡 这里有一点需要注意:
Poetry 的虚拟环境默认放在默认的全局缓存位置 :
- Windows:
%LOCALAPPDATA%\pypoetry\Cache\virtualenvs\
- macOS/Linux:
~/.cache/pypoetry/virtualenvs/
如果我们想要把它放在当前项目中,应该怎么做呢?
运行以下命令:
|
|
虚拟环境会存放在项目根目录的 .venv
文件夹中。
❶ 激活虚拟环境:
你可以通过以下命令激活虚拟环境,进入虚拟环境后执行 Python 或其他命令:
|
|
⚠️ 这个命令在 Windows 下不可用❗️
不能用该怎么办呢?手动激活喽~ 通过脚本〔 推荐 〕,或者像下面这样手动创建虚拟环境。
如果 poetry shell
无法正常工作,可以尝试手动创建虚拟环境并指定 Python 版本。可以使用 poetry env use
来指定 Python 版本:
poetry env use python3.8
如果虚拟环境已经存在,但无法进入,尝试删除现有的虚拟环境并重新创建:
poetry env remove python3.x # 根据需要选择 Python 版本 poetry env use python3.8 # 再次创建新的虚拟环境
❷ 退出虚拟环境:
使用以下命令退出虚拟环境:
|
|
❸ 如何不激活虚拟环境?
使用 poetry 默认会为每个项目创建一个虚拟环境,但这在某些情况下不是我们想要的,比如在个人主机中。那么如何设置默认禁用虚拟环境呢?
方法¹ 全局配置禁用虚拟环境
poetry config virtualenvs.create false
# 验证配置,确保 virtualenvs.create 的值为 false
poetry config --list
方法² 项目级别禁用虚拟环境
# 编辑 pyproject.toml
[tool.poetry]
[tool.poetry.virtualenvs]
create = false
# 验证配置,确保 virtualenvs.create 的值为 false
poetry config --local --list
方法³ 临时禁用虚拟环境
poetry install --no-venv
禁用虚拟环境后,Poetry 将直接使用系统的 Python 环境。请确保系统的 Python 环境干净且与项目依赖兼容,避免依赖冲突。
如果需要重新启用虚拟环境,可以运行以下命令:
poetry config virtualenvs.create true
🪧 无论什么时候,都可以方便地使用 poetry env info
显示虚拟环境的启用状态。
5. 安装项目依赖
当你克隆一个使用 Poetry 管理的项目时,可以使用 poetry install
来安装项目的所有依赖:
|
|
这会根据 pyproject.toml
文件中的依赖信息安装所有必要的包。
6. 运行命令
Poetry 允许你在项目的虚拟环境中直接运行 Python 命令或其他工具。例如,如果你想运行一个 Python 脚本,可以使用:
|
|
7. 构建和发布包
Poetry 可以自动构建和发布 Python 包到 PyPI。要构建包,只需运行:
|
|
这会在 dist/
目录下生成 .tar.gz
和 .whl
格式的包。
发布包
要将包发布到 PyPI,首先需要配置你的 PyPI 凭据:
|
|
然后运行:
|
|
8. pyproject.toml 配置文件
pyproject.toml
文件是 Poetry 项目的核心配置文件,包含项目信息、依赖、构建工具等。下面是一个简单的 pyproject.toml
示例:
|
|
[tool.poetry]
部分定义了项目的基本信息。[tool.poetry.dependencies]
定义了项目的运行时依赖。[tool.poetry.dev-dependencies]
定义了项目的开发时依赖。[build-system]
定义了构建系统,Poetry 使用的是poetry.masonry.api
。
9. 常用命令汇总
poetry new <project-name>
:创建一个新的项目。poetry init
:初始化当前目录为一个 Poetry 项目(创建pyproject.toml
)。poetry add <package>
:添加依赖包。poetry remove <package>
:移除依赖包。poetry install
:安装依赖。poetry update
:更新依赖。poetry shell
:激活虚拟环境。poetry run <command>
:在虚拟环境中运行命令。poetry build
:构建包。poetry publish
:发布包到 PyPI。
10. Poetry 的优势
- 简化依赖管理:Poetry 自动管理所有依赖和虚拟环境,无需手动编辑
requirements.txt
。 - 一致性:Poetry 使用
pyproject.toml
来定义依赖,避免了传统的setup.py
和requirements.txt
文件的不一致性。 - 集成的发布功能:Poetry 让发布包到 PyPI 变得非常简单,几乎不需要配置。
总结
Poetry 提供了一种现代、简洁且强大的方式来管理 Python 项目,它解决了传统 Python 包管理工具的一些痛点,并使得依赖管理、虚拟环境、包构建和发布等变得更加简单和统一。如果你在开发中遇到问题,Poetry 的文档非常详细,并且社区支持活跃,可以随时查询或寻求帮助。
希望这个简要教程能帮助你更好地使用 Poetry!如果有任何问题,欢迎随时提问!