构建良好的软件遵循特定规则并强制执行行业标准，同时需要考虑：依赖关系、代码质量、工作流程、凭据。但这些如何反映在现实代码库中呢？在这篇文章中，我将向您展示我在Python项目中设置的4个工具，以便简化开发工作流程并强制执行一些优秀实践。
1. Poetry
当我开始一个新项目时，我通常使用Poetry来管理依赖关系并创建一个全新的虚拟环境。这在不同项目依赖于相同包的不同版本时非常有用。
Poetry是一个很好的工具，因为它在解析依赖关系方面速度很快。它还通过用户友好的CLI易于使用，并有助于快速打包和分发您的代码。
以下是如何使用Poetry启动新项目的方法：
poetry init
一旦你按下yes，就会创建一个pyproject.toml文件，用于包含项目的 metadata。这个文件可以提交到Git，并与您的同事共享，以重现相同的环境。项目设置完成后，您可以使用add命令添加依赖项。示例：
poetry add pandas
您还可以分组依赖项。例如，您可以将black和isort添加为开发依赖项到dev组。示例：
poetry add black --group dev
如果再次查看pyproject.toml文件，我们将注意到依赖项的两个单独部分：
为什么这有用呢？
分组使您能够轻松管理不同环境的依赖关系。例如，如果您有开发和测试依赖项，您可能希望在生产设置中安装项目库时忽略它们。这是如何做到的：
poetry install --without dev,test依赖项安装在哪里？
Poetry为每个项目创建一个虚拟环境。它位于隐藏的.venv文件夹中。您可以使用poetry shell命令激活它，并访问其特定的二进制文件（python、pip、black等）。更多功能可以查看官方文档以了解更多信息。
2. Pre-commit hooks
如果您是Python开发人员，您可能经常会遇到这样的情况：您的团队成员具有不同的编码风格，这使得代码库不一致。结果，这导致错误，降低了生产力，并使协作困难。pre-commit hooks就可以解决这个问题，它在每次提交之前自动运行的脚本，用于检查您的代码是否存在错误。
在我的项目中，我通常会在我的预提交配置中添加这些脚本：
- black — 用于格式化代码
- pydoctyle — 确保代码文档符合Google的标准
- pycln — 用于删除未使用的导入
- trailing-whitespace — 用于删除额外的空格
- unitest — 用于运行单元测试和检测破坏性更改
要配置这些首先需要安装pre-commit包：
pip install pre-commit
或者
poetry add pre-commit然后，您需要在名为.pre-commit-configuration.yaml的YAML文件中进行定义。以下是我通常使用的一个：
repos:
- repo: https://github.com/psf/black
rev: '23.1.0'
hooks:
- id: black
args: [--config=pyproject.toml]
- repo: https://github.com/pycqa/pydocstyle
rev: '6.3.0'
hooks:
- id: pydocstyle
args: ['.']
- repo: https://github.com/hadialqattan/pycln
rev: 'v2.1.5'
hooks:
- id: pycln
args: ['.']
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: 'v4.4.0'
hooks:
- id: trailing-whitespace
- repo: local
hooks:
- id: unittest
name: run unit tests
language: system
pass_filenames: false
entry: poetry run coverage run -m pytest现在你可以使用 install 命令进行安装：
pre-commit install另外，如果您尝试提交没有文档的代码，您将收到此错误，不会提交任何内容到git。
这将迫使您修复代码，然后再次提交。
3. Makefiles
Makefile将一系列shell命令分组在一个快捷方式（也称为目标）下。想象一下，每次更新代码时都必须运行以下单元测试命令：
poetry run coverage run -m pytest
poetry run coverage report
poetry run coverage html那不是很繁琐吗？使用Makefile，您可以将这三个命令分组在一个 test 目标下。现在，您只需运行make test，而不是输入这三行，这避免了不必要的代码输入或记住复杂的指令。
Makefile还有助于简化其他任务，如：
- 安装依赖项
- 设置环境变量
- 运行脚本
- 构建和推送Docker镜像
- 构建文档
- 为代码添加样式
以下是我在我的一个开源项目中使用的Makefile示例：
DOCKER_IMAGE := ahmedbesbes/cowriter
VERSION := $(shell git describe --always --dirty --long)
ifneq (,$(wildcard ./.env))
include .env
export
endif
run-cowriter:
@poetry run python -m src.main
run-cowriter-job:
@poetry run python -m src.job
run-web-agent:
@rm -rf db/ && poetry run python -m src.actions.web_searcher
build-image:
@docker build . -t $(DOCKER_IMAGE):$(VERSION)
push-docker-image-to-artifact-registry:
@gcloud builds submit --tag gcr.io/$(PROJECT_ID)/run_cowriter_job
lint:
@poetry run black .
test:
@poetry run coverage run -m pytest
@poetry run coverage report
@poetry run coverage htmlMakefiles通常易于阅读和理解，清晰地显示了项目的不同部分是如何组织的，以及它们如何相互依赖。这对于新团队成员入职或一段时间后重访自己的项目尤其有帮助。
4. python-dotenv
作为开发人员，我使用Python构建依赖于凭据和敏感设置的应用程序。以下是这些凭据的一些示例：
- 用于访问第三方服务的API密钥
- 密码和凭据
- 标志
- 域名或URL
⚠️ 这些凭据不应该硬编码或版本化在您的脚本中。一种安全的良好实践是将它们加载为环境变量。
import os
api_key = os.environ.get("API_KEY")为了避免每次都使用shell命令导出环境变量，您可以使用Python dotenv包：
- pip install python-dotenv
- 创建一个包含键值对凭据的.env文件
- 将.env添加到.gitignore，以防止Git提交它
- 使用python-dotenv模块将设置加载到您的Python文件中
结论
我希望您发现这些工具有助于更好地构建Python项目的结构，并自动化繁琐和重复的任务。
