如何贡献

首先，感谢您考虑为 prisma-client-py 做贡献！正是像您这样的人让它成为每个人都喜欢的伟大工具。

本文档旨在通过将部落知识和期望编码来使贡献更容易。不要害怕打开半成品的 PR，如果有任何不清楚的地方，请随时提问！

一般先决条件

您必须在系统上安装 Python >= 3.7。

环境变量

要能够运行数据库测试，您必须为要运行测试的每个数据库提供程序定义一个环境变量，所需环境变量的完整列表可以在 databases/example.env 中找到。

SQLITE_URL='file:dev.db'
POSTGRES_URL='postgresql://<...>'

您可以根据需要设置这些环境变量。

本地开发环境

克隆仓库

git clone https://github.com/RobertCraigie/prisma-client-py.git
cd prisma-client-py

根据您的喜好设置虚拟环境，在本例中我们使用 venv

python3 -m venv .venv
source .venv/bin/activate

引导目录，此命令执行以下操作

以可编辑模式安装 prisma-client-py 及其所有依赖项
创建用于测试的本地 SQLite 数据库
安装 pre-commit

make bootstrap

工作流程

代码更改

在进行任何代码更改后，您必须运行 linter 并添加测试以确保您的更改有效。

您可以使用以下命令运行 linter 和测试，并提供覆盖率信息。

注意

这些命令不会运行 mypy 检查，因为完成 mypy 检查需要大量时间。

可以使用 nox -s mypy 运行 mypy 检查

make format
nox -s setup lint
nox -s test -p 3.9
nox -s report

调试客户端生成

将环境变量 PRISMA_PY_DEBUG_GENERATOR 设置为 1，这将把 prisma DMMF 数据写入您本地目录的 src/prisma/generator/debug-data.json 中。

文档

此项目的文档使用 mkdocs 和 mkdocs-material 主题。

在编辑文档时，您可以启动本地服务器并使用以下命令获得实时反馈

make docs-serve

测试

我们使用 nox 运行使用 pytest 编写的测试

我在哪里编写测试？

我们有几个地方可以编写测试

命令行: tests/test_cli/
数据库交互: databases/tests/
客户端生成: tests/test_generation/
集成测试: tests/integrations/
类型测试: typesafety/

数据库测试

Prisma Client Python 使用自定义测试套件针对多个数据库提供程序运行客户端 API 测试。这些测试可以在 databases/tests 和 databases/sync_tests 目录中找到。

要运行这些测试，您需要定义某些环境变量，有关设置的详细信息，请参阅环境变量。

您可以使用以下命令运行测试

nox -s databases -- test --inplace

提示

--inplace 标志表示客户端将生成到您的本地 src/prisma/ 目录中，以便更轻松地检查/开发循环。

默认情况下，将运行异步测试，要运行同步数据库测试，您可以传递 --for-async=false 标志。

或者，您可以明确指定要运行测试的数据库

nox -s databases -- test --databases=postgresql

这将为每个给定的数据库生成客户端并执行以下操作

对为给定数据库提供程序启用的所有测试运行 pytest
对生成的客户端代码和所有启用的测试文件运行 Pyright

这些测试通过将特定于数据库的功能拆分为自己的目录/文件，然后根据您运行测试的数据库来排除某些文件来实现。

集成测试

注意

运行数据库集成测试需要存在某些环境变量

集成测试可以在 tests/integrations 目录中找到。每个集成测试的入口点是位于目录顶层的 test.sh 脚本，例如 tests/integrations/custom-generator/test.sh。

您可以在此文件中执行任何您需要的操作，但是，每个 test.sh 应该以以下内容开头

#!/bin/bash

set -eux

python3 -m venv .venv

set +x
source .venv/bin/activate
set -x

要在集成测试中安装 prisma 包，您可以添加以下命令，将 <EXTRA> 替换为需要安装的任何其他内容。

pip install -U -r ../../../requirements/<EXTRA>.txt
pip install -U --force-reinstall ../../../.tests_cache/dist/*.whl

您现在可以添加任何您需要的特定于集成的命令。

您可以使用以下命令仅运行集成测试

nox -s test -p 3.9 -- tests/integrations/

或特定测试

nox -s test -p 3.9 -- --confcutdir . tests/integrations/postgresql

警告

如果您在集成测试中运行 pytest，您可能还需要更新根 pytest.ini 文件以将您的集成测试包含在 norecursedirs 选项中

单元测试

单元测试使用 pytest 运行，每个测试用例都必须包含一个文档字符串。

要添加测试用例，请在 tests 目录中找到相应的测试文件（如果找不到匹配的文件，请随意创建一个新文件），您可以像这样测试客户端

import pytest
from prisma import Prisma

@pytest.mark.asyncio
async def test_example(client: Prisma) -> None:
    """Test docstring"""
    ...

如果您编写的测试使用基于模型的访问，则必须像这样标记测试

import pytest

@pytest.mark.prisma
@pytest.mark.asyncio
async def test_example() -> None:
    """Test docstring"""
    ...

然后可以使用 nox 运行测试，例如

nox -s test -p 3.9

您可以像这样直接将参数传递给 pytest

nox -s test -p 3.9 -- -x --ignore=tests/integrations

有关编写良好的测试文档字符串，请参阅这篇文章。

对于更具体的测试用例，请查看测试并找到一个与您需要的类似的测试，不要害怕复制和粘贴测试代码。

快照测试

我们使用 inline-snapshot 用于，您猜对了，内联快照！如果您正在使用这些快照，您可能希望使用 --inline-snapshot=create 或 --inline-snapshot=fix 运行测试，例如

nox -s test -p 3.9 -- --inline-snapshot=fix

我们还使用 syrupy 来管理最好持久保存到独立文件的测试快照。您可以通过使用 --snapshot-update 运行测试来更新生成的快照，例如

nox -s test -p 3.9 -- --snapshot-update tests/test_generation/exhaustive

类型测试

为了确保类型已正确实现，我们使用 pytest-pyright 和 pytest-mypy-plugins。

您可以使用以下命令运行 pyright 和 mypy 测试

make typesafety

添加 Pyright 测试

要添加新的测试，只需在 typesafety/pyright 目录中创建一个 .py 文件并运行

nox -s typesafety-pyright

有关更多信息，请参阅 pytest-pyright 文档。

添加 Mypy 测试

Mypy 测试可以在 typesafety 目录中找到。

要添加新的测试，只需在 typesafety 目录中创建一个 test_*.yml 文件并运行

nox -s typesafety-mypy

有关更多信息，请参阅 pytest-mypy-plugins 文档。

Docker 测试 + 多平台（CPU 架构）支持

由于 Github Actions (CI) 不允许在多个 CPU 架构上运行代码（并使用 amd64 又名 x86_64 指令集），我们使用一个 docker 构建过程，该过程使用其 QEMU 支持来模拟多个 CPU 平台。make docker 命令可用于在本地执行此类构建。在 CI 中，这是通过测试工作流中的 docker 作业强制执行的。

我们还使用 docker 构建参数 OS_DISTRO，以便我们可以尝试针对多个官方上游 Python docker 镜像版本进行测试。

注意： docker 设置仅应在内部用于测试，而不应通过远程注册表重新分发。