tortoise-orm


Nametortoise-orm JSON
Version 0.17.4 PyPI version JSON
download
home_pagehttps://github.com/tortoise/tortoise-orm
SummaryEasy async ORM for python, built with relations in mind
upload_time2021-06-03 03:51:29
maintainer
docs_urlNone
authorAndrey Bondar
requires_python>=3.7,<4.0
licenseApache-2.0
keywords sql mysql postgres psql sqlite aiosqlite asyncpg relational database rdbms orm object mapper async asyncio aio
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            ============
Tortoise ORM
============

.. image:: https://badges.gitter.im/tortoise/community.png
   :target: https://gitter.im/tortoise/community
.. image:: https://img.shields.io/pypi/v/tortoise-orm.svg?style=flat
   :target: https://pypi.python.org/pypi/tortoise-orm
.. image:: https://readthedocs.org/projects/tortoise-orm/badge/?version=latest
   :target: http://tortoise-orm.readthedocs.io/en/latest/
.. image:: https://pepy.tech/badge/tortoise-orm/month
   :target: https://pepy.tech/project/tortoise-orm
.. image:: https://github.com/tortoise/tortoise-orm/workflows/ci/badge.svg
   :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://api.codacy.com/project/badge/Grade/b5b77021ba284e4a9e0c033a4611b046
   :target: https://app.codacy.com/app/Tortoise/tortoise-orm

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

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

Tortoise ORM was built with relations in mind and admiration for the excellent and popular Django ORM.
It's engraved in its design that you are working not with just tables, you work with relational data.

You can find the docs at `ReadTheDocs <http://tortoise-orm.readthedocs.io/en/latest/>`_

.. note::
   Tortoise ORM is a young project and breaking changes are to be expected.
   We keep a `Changelog <http://tortoise-orm.readthedocs.io/en/latest/CHANGELOG.html>`_ and it will have possible breakage clearly documented.

Tortoise ORM is supported on CPython >= 3.7 for SQLite, MySQL and PostgreSQL.

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

Python has many existing and mature ORMs, unfortunately they are designed with an opposing paradigm of how I/O gets processed.
``asyncio`` is relatively new technology that has a very different concurrency model, and the largest change is regarding how I/O is handled.

However, Tortoise ORM is not the first attempt of building an ``asyncio`` ORM. While there are many cases of developers attempting to map synchronous Python ORMs to the async world, initial attempts did not have a clean API.

Hence we started Tortoise ORM.

Tortoise ORM is designed to be functional, yet familiar, to ease the migration of developers wishing to switch to ``asyncio``.

It also performs well when compared to other Python ORMs. In `our benchmarks <https://github.com/tortoise/orm-benchmarks>`_, where we measure different read and write operations (rows/sec, more is better), it's trading places with Pony ORM:

.. 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?
---------------------

When you build an application or service that uses a relational database, there is a point where you can't get away with just using parameterized queries or even query builder. You just keep repeating yourself, writing slightly different code for each entity.
Code has no idea about relations between data, so you end up concatenating your data almost manually.
It is also easy to make mistakes in how you access your database, which can be exploited by SQL-injection attacks.
Your data rules are also distributed, increasing the complexity of managing your data, and even worse, could lead to those rules being applied inconsistently.

An ORM (Object Relational Mapper) is designed to address these issues, by centralising your data model and data rules, ensuring that your data is managed safely (providing immunity to SQL-injection) and keeping track of relationships so you don't have to.

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

Installation
------------
First you have to install Tortoise ORM like this:

.. code-block:: bash

    pip install tortoise-orm

You can also install with your db driver (`aiosqlite` is builtin):

.. code-block:: bash

    pip install tortoise-orm[asyncpg]


Or for MySQL:

.. code-block:: bash

    pip install tortoise-orm[aiomysql]

Or another asyncio MySQL driver `asyncmy <https://github.com/long2ice/asyncmy>`_:

.. code-block:: bash

    pip install tortoise-orm[asyncmy]

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

The primary entity of tortoise is ``tortoise.models.Model``.
You can start writing models like this:


.. code-block:: python3

    from tortoise.models import Model
    from tortoise import fields

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

        def __str__(self):
            return self.name


    class Event(Model):
        id = fields.IntField(pk=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(pk=True)
        name = fields.TextField()

        def __str__(self):
            return self.name


After you defined all your models, tortoise needs you to init them, in order to create backward relations between models and match your db client with the appropriate models.

You can do it like this:

.. code-block:: python3

    from tortoise import Tortoise

    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()


Here we create a connection to an SQLite database in the local directory called ``db.sqlite3``. Then we discover and initialise the models.

Tortoise ORM currently supports the following databases:

* SQLite (requires ``aiosqlite``)
* PostgreSQL (requires ``asyncpg``)
* MySQL (requires ``aiomysql``)

``generate_schema`` generates the schema on an empty database. Tortoise generates schemas in safe mode by default which
includes the ``IF NOT EXISTS`` clause, so you may include it in your main code.


After that you can start using your models:

.. code-block:: python3

    # Create instance by save
    tournament = Tournament(name='New Tournament')
    await tournament.save()

    # Or by .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)

    # M2M Relationship management is quite straightforward
    # (also look for methods .remove(...) and .clear())
    await event.participants.add(*participants)

    # You can query a related entity with async for
    async for team in event.participants:
        pass

    # After making a related query you can iterate with regular for,
    # which can be extremely convenient when using it with other packages,
    # for example some kind of serializers with nested support
    for team in event.participants:
        pass


    # Or you can make a preemptive call to fetch related objects
    selected_events = await Event.filter(
        participants=participants[0].id
    ).prefetch_related('participants', 'tournament')

    # Tortoise supports variable depth of prefetching related entities
    # This will fetch all events for Team and in those events tournaments will be prefetched
    await Team.all().prefetch_related('events__tournament')

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

Migration
=========

Tortoise ORM uses `Aerich <https://github.com/tortoise/aerich>`_ as its database migration tool, see more detail at its `docs <https://github.com/tortoise/aerich>`_.

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.


            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/tortoise/tortoise-orm",
    "name": "tortoise-orm",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.7,<4.0",
    "maintainer_email": "",
    "keywords": "sql,mysql,postgres,psql,sqlite,aiosqlite,asyncpg,relational,database,rdbms,orm,object mapper,async,asyncio,aio",
    "author": "Andrey Bondar",
    "author_email": "andrey@bondar.ru",
    "download_url": "https://files.pythonhosted.org/packages/16/4a/93f6cef51edf01aefbf2ddc0559612f4c9ce399cb340414c9273ec06c2c6/tortoise-orm-0.17.4.tar.gz",
    "platform": "",
    "description": "============\nTortoise ORM\n============\n\n.. image:: https://badges.gitter.im/tortoise/community.png\n   :target: https://gitter.im/tortoise/community\n.. image:: https://img.shields.io/pypi/v/tortoise-orm.svg?style=flat\n   :target: https://pypi.python.org/pypi/tortoise-orm\n.. image:: https://readthedocs.org/projects/tortoise-orm/badge/?version=latest\n   :target: http://tortoise-orm.readthedocs.io/en/latest/\n.. image:: https://pepy.tech/badge/tortoise-orm/month\n   :target: https://pepy.tech/project/tortoise-orm\n.. image:: https://github.com/tortoise/tortoise-orm/workflows/ci/badge.svg\n   :target: https://github.com/tortoise/tortoise-orm/actions?query=workflow:ci\n.. image:: https://coveralls.io/repos/github/tortoise/tortoise-orm/badge.svg\n   :target: https://coveralls.io/github/tortoise/tortoise-orm\n.. image:: https://api.codacy.com/project/badge/Grade/b5b77021ba284e4a9e0c033a4611b046\n   :target: https://app.codacy.com/app/Tortoise/tortoise-orm\n\nIntroduction\n============\n\nTortoise ORM is an easy-to-use ``asyncio`` ORM *(Object Relational Mapper)* inspired by Django.\n\nTortoise ORM was built with relations in mind and admiration for the excellent and popular Django ORM.\nIt's engraved in its design that you are working not with just tables, you work with relational data.\n\nYou can find the docs at `ReadTheDocs <http://tortoise-orm.readthedocs.io/en/latest/>`_\n\n.. note::\n   Tortoise ORM is a young project and breaking changes are to be expected.\n   We keep a `Changelog <http://tortoise-orm.readthedocs.io/en/latest/CHANGELOG.html>`_ and it will have possible breakage clearly documented.\n\nTortoise ORM is supported on CPython >= 3.7 for SQLite, MySQL and PostgreSQL.\n\nWhy was Tortoise ORM built?\n---------------------------\n\nPython has many existing and mature ORMs, unfortunately they are designed with an opposing paradigm of how I/O gets processed.\n``asyncio`` is relatively new technology that has a very different concurrency model, and the largest change is regarding how I/O is handled.\n\nHowever, Tortoise ORM is not the first attempt of building an ``asyncio`` ORM. While there are many cases of developers attempting to map synchronous Python ORMs to the async world, initial attempts did not have a clean API.\n\nHence we started Tortoise ORM.\n\nTortoise ORM is designed to be functional, yet familiar, to ease the migration of developers wishing to switch to ``asyncio``.\n\nIt also performs well when compared to other Python ORMs. In `our benchmarks <https://github.com/tortoise/orm-benchmarks>`_, where we measure different read and write operations (rows/sec, more is better), it's trading places with Pony ORM:\n\n.. image:: https://raw.githubusercontent.com/tortoise/tortoise-orm/develop/docs/ORM_Perf.png\n    :target: https://github.com/tortoise/orm-benchmarks\n\nHow is an ORM useful?\n---------------------\n\nWhen you build an application or service that uses a relational database, there is a point where you can't get away with just using parameterized queries or even query builder. You just keep repeating yourself, writing slightly different code for each entity.\nCode has no idea about relations between data, so you end up concatenating your data almost manually.\nIt is also easy to make mistakes in how you access your database, which can be exploited by SQL-injection attacks.\nYour data rules are also distributed, increasing the complexity of managing your data, and even worse, could lead to those rules being applied inconsistently.\n\nAn ORM (Object Relational Mapper) is designed to address these issues, by centralising your data model and data rules, ensuring that your data is managed safely (providing immunity to SQL-injection) and keeping track of relationships so you don't have to.\n\nGetting Started\n===============\n\nInstallation\n------------\nFirst you have to install Tortoise ORM like this:\n\n.. code-block:: bash\n\n    pip install tortoise-orm\n\nYou can also install with your db driver (`aiosqlite` is builtin):\n\n.. code-block:: bash\n\n    pip install tortoise-orm[asyncpg]\n\n\nOr for MySQL:\n\n.. code-block:: bash\n\n    pip install tortoise-orm[aiomysql]\n\nOr another asyncio MySQL driver `asyncmy <https://github.com/long2ice/asyncmy>`_:\n\n.. code-block:: bash\n\n    pip install tortoise-orm[asyncmy]\n\nQuick Tutorial\n--------------\n\nThe primary entity of tortoise is ``tortoise.models.Model``.\nYou can start writing models like this:\n\n\n.. code-block:: python3\n\n    from tortoise.models import Model\n    from tortoise import fields\n\n    class Tournament(Model):\n        id = fields.IntField(pk=True)\n        name = fields.TextField()\n\n        def __str__(self):\n            return self.name\n\n\n    class Event(Model):\n        id = fields.IntField(pk=True)\n        name = fields.TextField()\n        tournament = fields.ForeignKeyField('models.Tournament', related_name='events')\n        participants = fields.ManyToManyField('models.Team', related_name='events', through='event_team')\n\n        def __str__(self):\n            return self.name\n\n\n    class Team(Model):\n        id = fields.IntField(pk=True)\n        name = fields.TextField()\n\n        def __str__(self):\n            return self.name\n\n\nAfter you defined all your models, tortoise needs you to init them, in order to create backward relations between models and match your db client with the appropriate models.\n\nYou can do it like this:\n\n.. code-block:: python3\n\n    from tortoise import Tortoise\n\n    async def init():\n        # Here we connect to a SQLite DB file.\n        # also specify the app name of \"models\"\n        # which contain models from \"app.models\"\n        await Tortoise.init(\n            db_url='sqlite://db.sqlite3',\n            modules={'models': ['app.models']}\n        )\n        # Generate the schema\n        await Tortoise.generate_schemas()\n\n\nHere we create a connection to an SQLite database in the local directory called ``db.sqlite3``. Then we discover and initialise the models.\n\nTortoise ORM currently supports the following databases:\n\n* SQLite (requires ``aiosqlite``)\n* PostgreSQL (requires ``asyncpg``)\n* MySQL (requires ``aiomysql``)\n\n``generate_schema`` generates the schema on an empty database. Tortoise generates schemas in safe mode by default which\nincludes the ``IF NOT EXISTS`` clause, so you may include it in your main code.\n\n\nAfter that you can start using your models:\n\n.. code-block:: python3\n\n    # Create instance by save\n    tournament = Tournament(name='New Tournament')\n    await tournament.save()\n\n    # Or by .create()\n    await Event.create(name='Without participants', tournament=tournament)\n    event = await Event.create(name='Test', tournament=tournament)\n    participants = []\n    for i in range(2):\n        team = await Team.create(name='Team {}'.format(i + 1))\n        participants.append(team)\n\n    # M2M Relationship management is quite straightforward\n    # (also look for methods .remove(...) and .clear())\n    await event.participants.add(*participants)\n\n    # You can query a related entity with async for\n    async for team in event.participants:\n        pass\n\n    # After making a related query you can iterate with regular for,\n    # which can be extremely convenient when using it with other packages,\n    # for example some kind of serializers with nested support\n    for team in event.participants:\n        pass\n\n\n    # Or you can make a preemptive call to fetch related objects\n    selected_events = await Event.filter(\n        participants=participants[0].id\n    ).prefetch_related('participants', 'tournament')\n\n    # Tortoise supports variable depth of prefetching related entities\n    # This will fetch all events for Team and in those events tournaments will be prefetched\n    await Team.all().prefetch_related('events__tournament')\n\n    # You can filter and order by related models too\n    await Tournament.filter(\n        events__name__in=['Test', 'Prod']\n    ).order_by('-events__participants__name').distinct()\n\nMigration\n=========\n\nTortoise ORM uses `Aerich <https://github.com/tortoise/aerich>`_ as its database migration tool, see more detail at its `docs <https://github.com/tortoise/aerich>`_.\n\nContributing\n============\n\nPlease have a look at the `Contribution Guide <docs/CONTRIBUTING.rst>`_.\n\n\nLicense\n=======\n\nThis project is licensed under the Apache License - see the `LICENSE.txt <LICENSE.txt>`_ file for details.\n\n",
    "bugtrack_url": null,
    "license": "Apache-2.0",
    "summary": "Easy async ORM for python, built with relations in mind",
    "version": "0.17.4",
    "split_keywords": [
        "sql",
        "mysql",
        "postgres",
        "psql",
        "sqlite",
        "aiosqlite",
        "asyncpg",
        "relational",
        "database",
        "rdbms",
        "orm",
        "object mapper",
        "async",
        "asyncio",
        "aio"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "7f2d0d8554ed4dc68c8b0085bf82ed37",
                "sha256": "f052b6089e30748afec88669f1a1cf01a3662cdac81cf5427dfb338839ad6027"
            },
            "downloads": -1,
            "filename": "tortoise_orm-0.17.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "7f2d0d8554ed4dc68c8b0085bf82ed37",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7,<4.0",
            "size": 138013,
            "upload_time": "2021-06-03T03:51:28",
            "upload_time_iso_8601": "2021-06-03T03:51:28.055813Z",
            "url": "https://files.pythonhosted.org/packages/bb/e6/452622590a87be1af70695153e1d32f277f506072631277bc7d93288e6e5/tortoise_orm-0.17.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "375499baf1f0a4595bcdd528cacfd369",
                "sha256": "8314a9ae63d3f009bac5da3e7d1f7e3f2de8f9bad43ce1efcd3e059209cd3f9d"
            },
            "downloads": -1,
            "filename": "tortoise-orm-0.17.4.tar.gz",
            "has_sig": false,
            "md5_digest": "375499baf1f0a4595bcdd528cacfd369",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7,<4.0",
            "size": 114235,
            "upload_time": "2021-06-03T03:51:29",
            "upload_time_iso_8601": "2021-06-03T03:51:29.637450Z",
            "url": "https://files.pythonhosted.org/packages/16/4a/93f6cef51edf01aefbf2ddc0559612f4c9ce399cb340414c9273ec06c2c6/tortoise-orm-0.17.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2021-06-03 03:51:29",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": null,
    "github_project": "tortoise",
    "error": "Could not fetch GitHub repository",
    "lcname": "tortoise-orm"
}
        
Elapsed time: 0.30007s