Metadata-Version: 1.1
Name: tortoise-orm
Version: 0.10.0
Summary: Easy async ORM for python, built with relations in mind
Home-page: https://github.com/Zeliboba5/tortoise-orm
Author: Andrey Bondar
Author-email: andrey@bondar.ru
License: Apache License Version 2.0
Description: ========
        Tortoise
        ========
        
        .. image:: https://travis-ci.com/Zeliboba5/tortoise-orm.svg?branch=master
            :target: https://travis-ci.com/Zeliboba5/tortoise-orm
        .. image:: https://coveralls.io/repos/github/Zeliboba5/tortoise-orm/badge.svg?branch=master
            :target: https://coveralls.io/github/Zeliboba5/tortoise-orm?branch=master
        
        Introduction
        ============
        Tortoise is easy-to-use asyncio ORM inspired by Django.
        
        It is built with relations between models in mind and provides simple api for it, that gives you potential for building web services with easy abstractions.
        
        You can find docs at `readthedocs <http://tortoise-orm.readthedocs.io/en/latest/>`_
        
        Disclaimer
        ----------
        Tortoise is young project and breaking changes without following semantic versioning are to be expected
        
        
        Installation
        ===============
        First you have to install tortoise like this:
        
        .. code-block:: bash
        
            pip install tortoise-orm
        
        Then you should install your db driver
        
        .. code-block:: bash
        
            pip install asyncpg aiosqlite
        
        
        Tutorial
        ========
        
        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 appropriate models.
        
        You can do it like this:
        
        .. code-block:: python3
        
            from tortoise import Tortoise
            from tortoise.utils import generate_schema
        
            async def init():
                # Here we connect to a PostgresQL DB
                # also specify the app name of "models"
                # which contain models from "app.models"
                await Tortoise.init(
                    db_url='postgres://postgres:qwerty123@localhost:5432/events',
                    modules={'models': ['app.models']}
                )
                # Generate the schema
                await Tortoise.generate_schemas()
        
        
        Here we create connection to PostgresQL database with default ``asyncpg`` client and then we discover & initialise models.
        
        ``generate_schema`` generates schema on empty database, you shouldn't run it on every app init, run it just once, maybe out of 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 = 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 related entity just with async for
            async for team in event.participants:
                pass
            
            # After making related query you can iterate with regular for,
            # which can be extremely convenient for using with other packages,
            # for example some kind of serializers with nested support
            for team in event.participants:
                pass
        
        
            # Or you can make 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()
        
        
        
        If you want to contribute check out issues, or just straightforwardly create PR
        
Keywords: sql mysql postgres psql sqlite aiosqlite asyncpg relational database rdbms orm object mapper async asyncio aio
Platform: UNKNOWN
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.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: PL/SQL
Classifier: Framework :: AsyncIO
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Database
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS :: MacOS X
