贡献指南¶

如果您想做出贡献，请查看问题，或直接创建 PR。

Tortoise ORM 是一项志愿工作。我们鼓励您参与并加入团队！

请查看 贡献者契约行为准则

提交错误或请求功能¶

请检查是否存在解决您问题的现有问题或开放的拉取请求。如果没有，欢迎您打开一个。

如果您有一个不完整的更改，但不想/无法继续进行，请在任何情况下创建一个 PR 并将其标记为 (WIP)，以便我们可以互相帮助。

聊天¶

我们在 Gitter 上有一个聊天室

项目结构¶

我们有一个 Makefile，其中列出了常见操作，要开始，只需键入 make

Tortoise ORM development makefile

usage: make <target>
Targets:
    up          Updates dev/test dependencies
    deps        Ensure dev/test dependencies are installed
    check       Checks that build is sane
    lint        Reports all linter violations
    test        Runs all tests
    docs        Builds the documentation
    style       Auto-formats the code

因此，要运行测试，您只需要运行 make test 等...

代码按以下目录组织

docs/:

文档

examples/:

示例代码

tortoise/:

基础 Tortoise ORM

tortoise/fields/:

字段在此处定义。

tortoise/backends/:

数据库后端，例如 sqlite、asyncpg、psycopg 和 mysql

tortoise/backends/base/:

通用数据库后端代码

tortoise/contrib/:

任何有助于人们使用该项目的工具，例如测试框架和 linter 插件

tortoise/tests/:

Tortoise 测试代码

编码指南¶

我们相信保持代码简单，这样更容易测试，并且错误隐藏的地方更少。

优先级¶

Tortoise ORM 的一个重要部分是，我们想要一个简单的界面，只做预期的事情。由于这是一个对不同的人来说不同的值，我们已经确定

• Model/QuerySet 的使用应该是明确和简洁的。

• 保持简单，因为简单的代码不仅通常运行得更快，而且错误也更少。

• 正确性 > 易用性 > 性能 > 维护

• 测试所有内容。

• 只有在有可重复的基准进行测量时才进行性能/内存优化。

风格¶

我们尝试尽可能多地自动化，所以一个简单的 make check 将执行自动化的样式检查和 linting，但这些不会拾取非明显的样式首选项。

Tortoise ORM 遵循以下商定的样式

• 尽可能遵循 PEP8

• 最大行长已更改为 100

• 始终尝试清楚地分隔术语，而不是直接连接单词

  • some_purpose 而不是 somepurpose

  • SomePurpose 而不是 Somepurpose

• 记住 >=3.8 的目标 Python 版本

  • 请使用 f 字符串

• 请尽可能提供类型注释，这将改善编辑器中的自动完成，并进行更好的静态分析。

运行测试¶

在 Windows 上本机运行测试（尚未）受支持。目前运行它们的最佳方法是使用 WSL。Postgres 使用默认 postgres 用户，mysql 使用 root。如果其中任何一个有密码，则可以使用 TORTOISE_POSTGRES_PASS 和 TORTOISE_MYSQL_PASS 环境变量分别设置它。

不同类型的测试¶

• make test：最基本的快速测试。仅在内存 sqlite 数据库中运行测试，而不生成覆盖率报告。

• make test_sqlite：在内存 sqlite 数据库中运行测试

• make test_postgres_asyncpg：在 postgres 数据库上运行 asyncpg 测试

• make test_postgres_psycopg：在 postgres 数据库上运行 psycopg 测试

• make test_mysql_myisam：使用 MYISAM 存储引擎（无事务）在 mysql 数据库上运行测试

• make test_mysql：在 mysql 数据库上运行测试

• make testall：在所有 4 种数据库类型上运行测试：sqlite（内存）、postgresql、MySQL-MyISAM 和 MySQL-InnoDB

• green：运行与 make test 相同的测试，确保 green 插件正常工作

• nose2 --plugin tortoise.contrib.test.nose2 --db-module tests.testmodels --db-url sqlite://:memory: ``: 与 ``make test 相同的测试，确保 nose2 插件正常工作

运行测试套件时需要注意的事项¶

• 无论你运行的是哪个测试套件，某些测试始终会运行（例如，mysql 和 postgres 的连接测试，你不需要运行数据库，因为它实际上并未连接）

• 无论你指定了哪个数据库 URL，某些测试都会使用硬编码的数据库（通常是 sqlite）进行测试。

• postgres 驱动程序在 Pypy 下不起作用，因此如果你在 Pypy 下运行，这些测试将被跳过

• 你可以通过运行 `` py.test <testfiles>`` 或 green -s 1 <testfile> 来仅运行特定测试

• 如果你想窥探挂起的测试的内部情况以进行调试，请尝试使用 green -s 1 -vv -d -a <test> 运行它们

  • -s 1 表示它一次只运行一个测试

  • -vv 非常详细的输出

  • -d 记录调试输出

  • -a 不捕获 stdout，而是让它输出

• Mysql 往往相对较慢，但你可以调整一些设置来使其更快，但这同时意味着冗余性更低。自行承担风险使用：http://www.tocker.ca/2013/11/04/reducing-mysql-durability-for-testing.html