============ Tortoise ORM

.. image:: https://img.shields.io/pypi/v/tortoise-orm.svg?style=flat :target: https://pypi.python.org/pypi/tortoise-orm .. image:: https://pepy.tech/badge/tortoise-orm/month :target: https://pepy.tech/project/tortoise-orm .. image:: https://github.com/tortoise/tortoise-orm/workflows/gh-pages/badge.svg :target: https://github.com/tortoise/tortoise-orm/actions?query=workflow:gh-pages .. image:: https://github.com/tortoise/tortoise-orm/actions/workflows/ci.yml/badge.svg?branch=develop :target: https://github.com/tortoise/tortoise-orm/actions?query=workflow:ci .. image:: https://coveralls.io/repos/github/tortoise/tortoise-orm/badge.svg :target: https://coveralls.io/github/tortoise/tortoise-orm .. image:: https://app.codacy.com/project/badge/Grade/844030d0cb8240d6af92c71bfac764ff :target: https://www.codacy.com/gh/tortoise/tortoise-orm/dashboard?utm_source=github.com&utm_medium=referral&utm_content=tortoise/tortoise-orm&utm_campaign=Badge_Grade

简介

Tortoise ORM 是一个易于使用的 asyncio ORM（对象关系映射器），灵感来自 Django。

Tortoise ORM 在设计时考虑到了关系，并对优秀且流行的 Django ORM 表示敬意。其设计理念深深地铭刻着这样一个观点：你不仅仅是在处理表格，而是在处理关系型数据。

你可以在 文档 <https://tortoise.github.io>_ 中找到更多信息。

.. note:: Tortoise ORM 是一个年轻的项目，可能会有破坏性的变更。我们会保持 更新日志 <https://tortoise.github.io/CHANGELOG.html>_ 的更新，并在其中清楚地记录可能的破坏性变更。

Tortoise ORM 支持 CPython >= 3.8，适用于 SQLite、MySQL、PostgreSQL、Microsoft SQL Server 和 Oracle 数据库。

为什么要创建 Tortoise ORM？

Python 已经有许多现有的成熟 ORM，但遗憾的是，它们的设计采用了与 I/O 处理方式相反的范式。asyncio 是一项相对较新的技术，具有非常不同的并发模型，最大的变化在于 I/O 的处理方式。

然而，Tortoise ORM 并不是构建 asyncio ORM 的第一次尝试。虽然有许多开发者试图将同步 Python ORM 映射到异步世界，但初次尝试并没有一个干净的 API。

因此，我们开始了 Tortoise ORM 项目。

Tortoise ORM 的设计既实用又熟悉，以便于希望切换到 asyncio 的开发者能够轻松迁移。

与其他 Python ORM 相比，它的性能也很出色。在 我们的基准测试 <https://github.com/tortoise/orm-benchmarks>_ 中，我们测量了不同的读写操作（行/秒，数值越高越好），它与 Pony ORM 不相上下：

.. image:: https://raw.githubusercontent.com/tortoise/tortoise-orm/develop/docs/ORM_Perf.png :target: https://github.com/tortoise/orm-benchmarks

ORM 如何有用？

当你构建使用关系型数据库的应用程序或服务时，总有一个时刻你无法仅仅依靠参数化查询或查询构建器。你会发现自己不断重复，为每个实体编写略有不同的代码。代码不了解数据之间的关系，所以你最终几乎是手动连接数据。在访问数据库时也很容易犯错误，这可能会被 SQL 注入攻击所利用。你的数据规则也是分散的，增加了管理数据的复杂性，更糟糕的是，可能导致这些规则被不一致地应用。

ORM（对象关系映射器）旨在解决这些问题，通过集中管理你的数据模型和数据规则，确保你的数据被安全管理（提供免疫 SQL 注入的能力），并跟踪关系，让你不必自己处理。

入门

安装

首先，你需要像这样安装 Tortoise ORM：

.. code-block:: bash

pip install tortoise-orm

你也可以与数据库驱动一起安装（aiosqlite 是内置的）：

.. code-block:: bash

pip install tortoise-orm[asyncpg]

对于 MySQL：

.. code-block:: bash

pip install tortoise-orm[asyncmy]

对于 Microsoft SQL Server/Oracle（未完全测试）：

.. code-block:: bash

pip install tortoise-orm[asyncodbc]

快速教程

Tortoise 的主要实体是 tortoise.models.Model。你可以像这样开始编写模型：

.. code-block:: python3

from tortoise.models import Model
from tortoise import fields

class Tournament(Model):
    id = fields.IntField(primary_key=True)
    name = fields.TextField()

    def __str__(self):
        return self.name


class Event(Model):
    id = fields.IntField(primary_key=True)
    name = fields.TextField()
    tournament = fields.ForeignKeyField('models.Tournament', related_name='events')
    participants = fields.ManyToManyField('models.Team', related_name='events', through='event_team')

    def __str__(self):
        return self.name


class Team(Model):
    id = fields.IntField(primary_key=True)
    name = fields.TextField()

    def __str__(self):
        return self.name

在定义完所有模型后，Tortoise 需要你初始化它们，以便在模型之间创建反向关系，并将数据库客户端与适当的模型匹配。

你可以这样做：

.. code-block:: python3

from tortoise import Tortoise

async def init():
    # 这里我们连接到一个 SQLite 数据库文件。
    # 同时指定 "models" 应用名称，
    # 其中包含来自 "app.models" 的模型
    await Tortoise.init(
        db_url='sqlite://db.sqlite3',
        modules={'models': ['app.models']}
    )
    # 生成架构
    await Tortoise.generate_schemas()

在这里，我们创建了一个连接到本地目录中名为 db.sqlite3 的 SQLite 数据库。然后我们发现并初始化模型。

Tortoise ORM 目前支持以下数据库：

SQLite（需要 aiosqlite）
PostgreSQL（需要 asyncpg）
MySQL（需要 asyncmy）
Microsoft SQL Server/Oracle（需要 asyncodbc）

generate_schema 在空数据库上生成架构。默认情况下，Tortoise 以安全模式生成架构，其中包括 IF NOT EXISTS 子句，因此你可以将其包含在主代码中。

之后，你就可以开始使用你的模型了：

.. code-block:: python3

# 通过保存创建实例
tournament = Tournament(name='新锦标赛')
await tournament.save()

# 或者通过 .create() 方法
await Event.create(name='无参与者', tournament=tournament)
event = await Event.create(name='测试', tournament=tournament)
participants = []
for i in range(2):
    team = await Team.create(name='队伍 {}'.format(i + 1))
    participants.append(team)

# 多对多关系管理非常直观
# （还可以查看 .remove(...) 和 .clear() 方法）
await event.participants.add(*participants)

# 你可以使用 async for 查询相关实体
async for team in event.participants:
    pass

# 在进行相关查询后，你可以使用常规的 for 循环进行迭代，
# 这在与其他包一起使用时可能非常方便，
# 例如某些支持嵌套的序列化器
for team in event.participants:
    pass


# 或者你可以预先调用以获取相关对象
selected_events = await Event.filter(
    participants=participants[0].id
).prefetch_related('participants', 'tournament')

# Tortoise 支持预取相关实体的可变深度
# 这将获取 Team 的所有事件，并在这些事件中预取锦标赛
await Team.all().prefetch_related('events__tournament')

# 你也可以通过相关模型进行过滤和排序
await Tournament.filter(
    events__name__in=['测试', '生产']
).order_by('-events__participants__name').distinct()