Metadata-Version: 2.1
Name: tortoise-orm
Version: 1.0.0
Summary: Easy async ORM for python, built with relations in mind
Keywords: sql,mysql,postgres,psql,sqlite,aiosqlite,asyncpg,relational,database,rdbms,orm,object mapper,async,asyncio,aio,psycopg
Author-Email: Andrey Bondar <andrey@bondar.ru>, Nickolas Grigoriadis <nagrigoriadis@gmail.com>, long2ice <long2ice@gmail.com>
License: Apache-2.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: PL/SQL
Classifier: Framework :: AsyncIO
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Database
Classifier: Typing :: Typed
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Project-URL: documentation, https://tortoise.github.io
Project-URL: homepage, https://github.com/tortoise/tortoise-orm
Project-URL: repository, https://github.com/tortoise/tortoise-orm.git
Requires-Python: >=3.10
Requires-Dist: pypika-tortoise<1.0.0,>=0.6.3
Requires-Dist: iso8601<3.0.0,>=2.1.0; python_version < "4.0"
Requires-Dist: aiosqlite<1.0.0,>=0.16.0
Requires-Dist: anyio
Requires-Dist: tomlkit<1.0.0,>=0.11.4; python_version < "3.11"
Requires-Dist: typing-extensions>=4.1.0; python_version < "3.11"
Provides-Extra: ipython
Requires-Dist: ipython; extra == "ipython"
Requires-Dist: nest-asyncio>=1.6.0; extra == "ipython"
Provides-Extra: ptpython
Requires-Dist: ptpython>=3.0.0; extra == "ptpython"
Provides-Extra: accel
Requires-Dist: ciso8601; sys_platform != "win32" and implementation_name == "cpython" and extra == "accel"
Requires-Dist: uvloop; sys_platform != "win32" and implementation_name == "cpython" and extra == "accel"
Requires-Dist: orjson; extra == "accel"
Provides-Extra: asyncpg
Requires-Dist: asyncpg; extra == "asyncpg"
Provides-Extra: aiomysql
Requires-Dist: aiomysql; extra == "aiomysql"
Provides-Extra: asyncmy
Requires-Dist: asyncmy<1.0.0,>=0.2.11; extra == "asyncmy"
Provides-Extra: psycopg
Requires-Dist: psycopg[binary,pool]<4.0.0,>=3.0.12; extra == "psycopg"
Provides-Extra: asyncodbc
Requires-Dist: asyncodbc<1.0.0,>=0.1.1; python_version < "4.0" and extra == "asyncodbc"
Description-Content-Type: text/x-rst

============
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

Introduction
============

Tortoise ORM is an easy-to-use ``asyncio`` ORM *(Object Relational Mapper)* inspired by Django.

You can find the docs at `Documentation <https://tortoise.github.io>`_

Tortoise ORM supports CPython 3.10 and later for SQLite, MySQL, PostgreSQL, Microsoft SQL Server, and Oracle.

Why was Tortoise ORM built?
---------------------------

Tortoise ORM was built to provide a lightweight, async-native Object-Relational Mapper for Python with a familiar Django-like API.

Tortoise ORM performs well when compared to other Python ORMs. Here are `our benchmarks <https://github.com/tortoise/orm-benchmarks>`_ on PostgreSQL 17, where we measure different read and write operations (rows/sec, more is better):

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

How is an ORM useful?
---------------------

An Object-Relational Mapper (ORM) abstracts database interactions, allowing developers to work with databases using high-level, object-oriented code instead of raw SQL.

* Reduces boilerplate SQL, allowing faster development with cleaner, more readable code.
* Helps prevent SQL injection by using parameterized queries.
* Centralized schema and relationship definitions make code easier to manage and modify.
* Handles schema changes through version-controlled migrations.

Getting Started
===============

Installation
------------

The following table shows the available installation options for different databases (note that there are multiple options of clients for some databases):

.. list-table:: Available Installation Options
   :header-rows: 1
   :widths: 30 70

   * - Database
     - Installation Command
   * - SQLite
     - ``pip install tortoise-orm``
   * - PostgreSQL (psycopg)
     - ``pip install tortoise-orm[psycopg]``
   * - PostgreSQL (asyncpg)
     - ``pip install tortoise-orm[asyncpg]``
   * - MySQL (aiomysql)
     - ``pip install tortoise-orm[aiomysql]``
   * - MySQL (asyncmy)
     - ``pip install tortoise-orm[asyncmy]``
   * - MS SQL
     - ``pip install tortoise-orm[asyncodbc]``
   * - Oracle
     - ``pip install tortoise-orm[asyncodbc]``


Quick Tutorial
--------------

Define the models by inheriting from ``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.CharField(max_length=20)


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


    class Team(Model):
        id = fields.UUIDField(primary_key=True)
        name = fields.CharField(max_length=20, unique=True)


After defining the models, Tortoise ORM needs to be initialized to establish the relationships between models and connect to the database.
The code below creates a connection to a SQLite DB database with the ``aiosqlite`` client. ``generate_schema`` sets up schema on an empty database.
``generate_schema`` is for development purposes only; use the built-in
migrations for production use.

.. code-block:: python3

    from tortoise import Tortoise, run_async

    async def init():
        # Here we connect to a SQLite DB file.
        # also specify the app name of "models"
        # which contain models from "app.models"
        await Tortoise.init(
            db_url='sqlite://db.sqlite3',
            modules={'models': ['app.models']}
        )
        # Generate the schema
        await Tortoise.generate_schemas()

    run_async(main())

``run_async`` is a helper function to run simple Tortoise scripts. Check out `Documentation <https://tortoise.github.io>`_ for FastAPI, Sanic and other integrations.

With the Tortoise initialized, the models are available for use:

.. code-block:: python3

    async def main():
        await Tortoise.init(
            db_url='sqlite://db.sqlite3',
            modules={'models': ['app.models']}
        )
        await Tortoise.generate_schemas()

        # Creating an instance with .save()
        tournament = Tournament(name='New Tournament')
        await tournament.save()

        # Or with .create()
        await Event.create(name='Without participants', tournament=tournament)
        event = await Event.create(name='Test', tournament=tournament)
        participants = []
        for i in range(2):
            team = await Team.create(name='Team {}'.format(i + 1))
            participants.append(team)

        # One to Many (ForeignKey) relations support creating related objects
        another_event = await tournament.events.create(name='Another Event')

        # Many to Many Relationship management is quite straightforward
        # (there are .remove(...) and .clear() too)
        await event.participants.add(*participants)

        # Iterate over related entities with the async context manager
        async for team in event.participants:
            print(team.name)

        # The related entities are cached and can be iterated in the synchronous way afterwards
        for team in event.participants:
            pass

        # Use prefetch_related to fetch related objects
        selected_events = await Event.filter(
            participants=participants[0].id
        ).prefetch_related('participants', 'tournament')
        for event in selected_events:
            print(event.tournament.name)
            print([t.name for t in event.participants])

        # Prefetch multiple levels of related entities
        await Team.all().prefetch_related('events__tournament')

        # Filter and order by related models too
        await Tournament.filter(
            events__name__in=['Test', 'Prod']
        ).order_by('-events__participants__name').distinct()

    run_async(main())


Learn more at the `documentation site <https://tortoise.github.io>`_


Migrations
==========

Tortoise ORM ships with a built-in migration framework and CLI.
Autodetect model changes, generate migration files, and apply them:

.. code-block:: shell

    tortoise init                # create migration packages
    tortoise makemigrations      # detect changes and generate migrations
    tortoise migrate             # apply pending migrations
    tortoise sqlmigrate app 001  # preview SQL without executing

Migrations support ``RunPython`` and ``RunSQL`` for data migrations, offline migration generation,
reversible operations, and multi-app and multi db-schema projects.

See the `migrations documentation <https://tortoise.github.io/migration.html>`_ for
full setup and examples.

Contributing
============

Please have a look at the `Contribution Guide <docs/CONTRIBUTING.rst>`_.

License
=======

This project is licensed under the Apache License - see the `LICENSE.txt <LICENSE.txt>`_ file for details.
