Python项目管理-poetry – 孙成新的个人博客

Poetry 是 Python 的一个依赖管理和项目构建工具，旨在简化 Python 项目的工作流。它可以管理虚拟环境、依赖、打包和发布等任务。以下是对 Poetry 如何管理 Python 项目的详细介绍，涵盖下载、安装、初始化、添加第三方库等步骤：

1. 下载和安装 Poetry

Poetry 是一个独立的工具，需要先安装到系统上。以下是安装步骤：

Windows

在 PowerShell 或命令提示符中运行以下命令：

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

Linux

在终端中运行：

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

MacOS

brew install poetry

验证安装

安装完成后，检查 Poetry 是否正确安装：

poetry --version

输出类似 Poetry (version 1.8.3) 表示安装成功。

配置 Poetry

Poetry 默认会为每个项目创建独立的虚拟环境。可以通过以下命令配置全局设置（可选）：

poetry config virtualenvs.in-project true  poetry config --list

这会将虚拟环境创建在项目目录下的 .venv 文件夹中，便于管理。

国内lib下载慢问题

# 添加一个国内仓库

poetry config repositories.aliyun https://mirrors.aliyun.com/pypi/simple/
poetry config installer.max-workers 10

添加一个私有有 PyPI 仓库（包含认证信息）

poetry config http-basic.my-pypi username password

poetry config –unset http-basic.my-pypi

2. 初始化 Poetry 项目

Poetry 可以用来创建一个新的 Python 项目或管理现有项目。

创建新项目

运行以下命令创建一个新项目：

   poetry new my-project

这会生成一个包含以下结构的目录：

   my-project/
   ├── pyproject.toml
   ├── README.md
   ├── my_project/
   │   └── __init__.py
   └── tests/
       └── __init__.py

pyproject.toml 是 Poetry 的核心配置文件，包含项目元数据和依赖信息。
my_project 是项目的主模块目录。
tests 是测试目录。

   cd my-project

初始化虚拟环境：

   poetry install

这会根据 pyproject.toml 创建虚拟环境并安装必要的依赖。

在现有项目中初始化

如果已有项目目录，可以通过以下命令初始化 Poetry：

poetry init

该命令会交互式地生成 pyproject.toml 文件，提示输入项目名称、版本、描述、作者等信息。
完成后，运行 poetry install 创建虚拟环境。

3. 管理依赖

Poetry 通过 pyproject.toml 文件管理项目的依赖，支持精确版本、范围版本和开发依赖。

添加第三方库

使用 poetry add 命令添加依赖。例如：

poetry add requests

这会自动：
将 requests 及其版本添加到 pyproject.toml 的 [tool.poetry.dependencies] 部分。
下载并安装 requests 及其依赖到虚拟环境中。
更新 poetry.lock 文件，锁定依赖的具体版本。

示例 pyproject.toml：

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.28.0"

添加开发依赖

开发依赖（如测试框架）只用于开发环境：

poetry add pytest --group dev

这会将 pytest 添加到 pyproject.toml 的 [tool.poetry.group.dev.dependencies] 部分。

移除依赖

移除某个依赖：

poetry remove requests

更新依赖

更新所有依赖到最新兼容版本：

poetry update

或者更新特定依赖：

poetry update requests

4. 管理虚拟环境

Poetry 自动为项目创建虚拟环境，隔离依赖。

激活虚拟环境

运行以下命令激活虚拟环境：

poetry shell

这会进入项目的虚拟环境 shell，类似 source .venv/bin/activate。
要退出虚拟环境，输入 exit。

在虚拟环境中运行命令

如果不想进入 shell，可以直接运行命令：

poetry run python my_script.py

或者运行其他工具：

poetry run pytest

查看虚拟环境信息

检查当前虚拟环境路径：

poetry env info

删除虚拟环境

如果需要删除虚拟环境：

poetry env remove python

5. 构建和发布项目

Poetry 提供了打包和发布项目的便捷方式。

构建项目

生成 sdist（源代码分发）或 wheel 文件：

poetry build

输出文件会出现在 dist/ 目录中。

发布到 PyPI

配置 PyPI 凭据：

   poetry config pypi-token.pypi your-api-token

发布项目：

   poetry publish

6. 其他常用命令

查看依赖树：

  poetry show --tree

检查配置：

  poetry check

导出 requirements.txt（用于兼容其他工具）：

  poetry export -f requirements.txt --output requirements.txt

查看当前poetry项目运行环境

poetry env info --path

查看所有配置

poetry config --list

7. 最佳实践

版本约束：使用 ^（允许次要版本更新）或 ~（允许补丁版本更新）来指定依赖版本范围，避免过于严格的版本锁定。
分组依赖：将开发、测试等依赖放入 dev 或自定义分组，保持生产环境的精简。
使用 poetry.lock：始终提交 poetry.lock 到版本控制，确保依赖版本一致性。
定期更新：运行 poetry update 检查和更新依赖，保持项目安全性和兼容性。

示例：完整的工作流

创建项目：

   poetry new my-app
   cd my-app

添加依赖：

   poetry add fastapi
   poetry add pytest --group dev

编写代码并运行：

   poetry run python -m my_app

运行测试：

   poetry run pytest

构建并发布：

   poetry build
   poetry publish

Poetry 提供了直观且强大的工具来管理 Python 项目，简化了依赖管理和发布流程。通过 pyproject.toml 和 poetry.lock，它确保了项目的可重复性和一致性。更多详情可参考 Poetry 官方文档。

Poetry 的常用命令列表

涵盖项目管理、依赖管理、虚拟环境操作等功能。

项目管理

poetry new <project-name>
创建一个新的 Poetry 项目，生成标准目录结构和 pyproject.toml。
poetry init
在现有目录中交互式初始化 pyproject.toml。
poetry install
安装 pyproject.toml 中定义的依赖并创建虚拟环境。
poetry update
更新所有依赖到最新兼容版本，更新 poetry.lock。
poetry check
检查 pyproject.toml 的配置是否有效。

依赖管理

poetry add <package> [version]
添加依赖到 pyproject.toml 并安装（如 poetry add requests）。
poetry add <package> --group <group>
添加依赖到特定组（如开发组：poetry add pytest --group dev）。
poetry remove <package>
移除指定依赖并更新 poetry.lock。
poetry show
显示所有已安装的依赖及其版本。
poetry show --tree
以树形结构显示依赖关系。
poetry export -f requirements.txt --output requirements.txt
导出依赖到 requirements.txt 文件。

虚拟环境管理

poetry shell
激活项目的虚拟环境。
poetry run <command>
在虚拟环境中运行命令（如 poetry run python script.py）。
poetry env info
显示当前虚拟环境的信息。
poetry env list
列出所有虚拟环境。
poetry env remove <python-version>
删除指定的虚拟环境（如 poetry env remove python3.8）。

构建和发布

poetry build
构建项目，生成 sdist 和 wheel 文件到 dist/ 目录。
poetry publish
发布项目到 PyPI（需配置 PyPI 令牌）。
poetry publish --build
构建并发布项目到 PyPI。

配置管理

poetry config [setting] [value]
设置 Poetry 配置（如 poetry config virtualenvs.in-project true）。
poetry config --list
列出所有 Poetry 配置。

其他

poetry version
显示或修改项目版本（如 poetry version patch 升级补丁版本）。
poetry self update
更新 Poetry 自身到最新版本。
poetry --version
显示 Poetry 的版本。
poetry cache clear --all <cache>
清除 Poetry 缓存（如 poetry cache clear --all pypi）。
poetry lock
产生或更新poetry.lock文件

## 示例配置
toml
[project]
name = "gexa"
version = "0.1.0"
description = ""
authors = [
    {name = "Chengxin",email = "[email protected]"}
]
readme = "README.md"

[tool.poetry.dependencies]
python = ">=3.9,<4.0"
python-dotenv = "*"
pytz = "*"
tenacity = "*"


[tool.poetry.group.dev.dependencies]
pytest = "*"
pytest-asyncio = "*"
pyright = "*"
isort = "*"
black = "*"

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

[tool.pyright]
reportCallIssue = false

[tool.isort]
line_length = 100
wrap_length = 100
multi_line_output = 3
profile = "black"
include_trailing_comma = true

[tool.pytest.ini_options]
log_cli = true
log_cli_level = "DEBUG"
log_cli_format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
```

备注

更多详细信息可通过 poetry --help 或 poetry <command> --help 查看具体命令的帮助。
访问 Poetry 官方文档获取完整命令说明和高级用法。