构建良好的软件遵循特定规则并强制执行行业标准,同时需要考虑:依赖关系、代码质量、工作流程、凭据。但这些如何反映在现实代码库中呢?在这篇文章中,我将向您展示我在Python/ target=_blank class=infotextkey>Python项目中设置的4个工具,以便简化开发工作流程并强制执行一些优秀实践。
当我开始一个新项目时,我通常使用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等)。更多功能可以查看官方文档以了解更多信息。
如果您是Python开发人员,您可能经常会遇到这样的情况:您的团队成员具有不同的编码风格,这使得代码库不一致。结果,这导致错误,降低了生产力,并使协作困难。pre-commit hooks就可以解决这个问题,它在每次提交之前自动运行的脚本,用于检查您的代码是否存在错误。
在我的项目中,我通常会在我的预提交配置中添加这些脚本:
要配置这些首先需要安装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。
这将迫使您修复代码,然后再次提交。
Makefile将一系列shell命令分组在一个快捷方式(也称为目标)下。想象一下,每次更新代码时都必须运行以下单元测试命令:
poetry run coverage run -m pytest
poetry run coverage report
poetry run coverage html
那不是很繁琐吗?使用Makefile,您可以将这三个命令分组在一个 test 目标下。现在,您只需运行make test,而不是输入这三行,这避免了不必要的代码输入或记住复杂的指令。
Makefile还有助于简化其他任务,如:
以下是我在我的一个开源项目中使用的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 html
Makefiles通常易于阅读和理解,清晰地显示了项目的不同部分是如何组织的,以及它们如何相互依赖。这对于新团队成员入职或一段时间后重访自己的项目尤其有帮助。
作为开发人员,我使用Python构建依赖于凭据和敏感设置的应用程序。以下是这些凭据的一些示例:
⚠️ 这些凭据不应该硬编码或版本化在您的脚本中。一种安全的良好实践是将它们加载为环境变量。
import os
api_key = os.environ.get("API_KEY")
为了避免每次都使用shell命令导出环境变量,您可以使用Python dotenv包:
我希望您发现这些工具有助于更好地构建Python项目的结构,并自动化繁琐和重复的任务。