Documentation, 0.3.1

Author: abondar

Makefile docs/Makefile

@@ -76,6 +76,17 @@
 # a list of builtin themes.
 #
 html_theme = 'alabaster'
+# html_theme = 'sphinx_rtd_theme'
+
+html_sidebars = {
+    '**': [
+        'about.html',
+        'localtoc.html',
+        'navigation.html',
+        'relations.html',
+        'searchbox.html',
+    ]
+}
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

conf.py docs/conf.py

@@ -148,3 +148,12 @@ Also
 Huge thanks to https://github.com/kayak/pypika for making this possible.
 
 If you want to contribute check out issues, or just straightforwardly create PR
+
+
+Table Of Contents
+=================
+
+.. toctree::
+
+   models_and_fields
+   query

index.rst docs/index.rst

@@ -0,0 +1,149 @@
+=================
+Models and fields 
+=================
+To get working with models, first you should import them 
+ from tortoise.models import Model
+
+With that you can start describing your own models like that
+
+.. code-block:: python
+
+    class Tournament(Model):
+        id = fields.IntField(pk=True)
+        name = fields.StringField()
+        created = fields.DatetimeField(auto_now_add=True)
+
+        def __str__(self):
+            return self.name
+
+
+    class Event(Model):
+        id = fields.IntField(pk=True)
+        name = fields.StringField()
+        tournament = fields.ForeignKeyField('models.Tournament', related_name='events')
+        participants = fields.ManyToManyField('models.Team', related_name='events', through='event_team')
+        modified = fields.DatetimeField(auto_now=True)
+        prize = fields.DecimalField(max_digits=10, decimal_places=2, null=True)
+
+        def __str__(self):
+            return self.name
+
+
+    class Team(Model):
+        id = fields.IntField(pk=True)
+        name = fields.StringField()
+
+        def __str__(self):
+            return self.name
+
+Let see in details what we accomplished here:
+
+.. code-block:: python
+
+    class Tournament(Model):
+
+Every model should be derived from base model. You also can derive from your own model subclasses and you can make abstract models like this
+
+.. code-block:: python
+
+    class AbstractTournament(Model):
+        id = fields.IntField(pk=True)
+        name = fields.StringField()
+        created = fields.DatetimeField(auto_now_add=True)
+
+        class Meta:
+            abstract = True
+
+        def __str__(self):
+            return self.name
+
+This models won't be created in schema generation and won't create relations to other models.
+
+Further, let's take a look at created fields for models
+
+.. code-block:: python
+
+    id = fields.IntField(pk=True)
+
+This code defines integer primary key for table. Sadly, currently only simple integer pk is supported.
+
+.. code-block:: python
+
+    tournament = fields.ForeignKeyField('models.Tournament', related_name='events')
+    participants = fields.ManyToManyField('models.Team', related_name='events', through='event_team')
+    modified = fields.DatetimeField(auto_now=True)
+    prize = fields.DecimalField(max_digits=10, decimal_places=2, null=True)
+
+In event model we got some more fields, that could be interesting for us. 
+``fields.ForeignKeyField('models.Tournament', related_name='events')`` - here we create foreign key reference to tournament. We create it by referring to model by it's literal, consisting of app name and model name. `models` is default app name, but you can change it in `class Meta` with `app = 'other'`.
+``related_name`` is keyword argument, that defines field for related query on referenced models, so with that you could fetch all tournaments's events with like this:
+
+.. code-block:: python
+
+    await tournament.events.all()
+
+or like this:
+
+.. code-block:: python
+
+    await tournament.fetch_related('events')
+
+
+Next field is ``fields.ManyToManyField('models.Team', related_name='events', through='event_team')``. It describes many to many relation to model Team.
+Here we have additional kwarg ``through`` that defines name of intermediate table.
+
+Further we have field ``fields.DatetimeField(auto_now=True)``. Options ``auto_now`` and ``auto_now_add`` work like Django's options.
+
+Init app
+========
+
+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:: python
+
+    from tortoise.backends.asyncpg.client import AsyncpgDBClient
+    from tortoise import Tortoise
+    from app import models # without importing models Tortoise can't find and init them
+
+
+    async def init():
+        db = AsyncpgDBClient(
+            host='localhost',
+            port=5432,
+            user='postgres',
+            password='qwerty123',
+            database='events',
+       )
+        
+        await db.create_connection()
+        Tortoise.init(db)
+        
+        await generate_schema(client)
+
+Here we create connection to database with default asyncpg client and then we init models. Be sure that you have your models imported in the app. Usually that's the case, because you use your models across you app, but if you have only local imports of it, tortoise won't be able to find them and init them with connection to db.
+``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.
+
+
+Fields
+======
+
+Here is list of fields available at the moment with custom options of this fields:
+
+- IntField (``pk``)
+- SmallIntField
+- StringField
+- BooleanField
+- DecimalField (``max_digits``, ``decimal_places``)
+- DatetimeField (``auto_now``, ``auto_now_add``)
+- DateField
+- ForeignKeyField (model_name, related_name, on_delete)
+- ManyToManyField (``model_name``, ``related_name``, ``through``, ``backward_key``, ``forward_key``)
+
+Also all fields fields have this options:
+- ``source_field`` - field name in schema, can be different from field name
+- ``null`` - is field nullable
+- ``default`` - default value for field
+- ``generated`` - flag that says that this field is read only and value should be generated in db. Normally, should be used only if you working on already created schema, not generated by tortoise.
+

docs/models_and_fields.rst

@@ -0,0 +1,94 @@
+=========
+Query API
+=========
+
+Be sure to check `examples <https://github.com/Zeliboba5/tortoise-orm/tree/master/examples>`_ for better understanding
+
+You start your query from your model instance:
+
+.. code-block:: python
+
+    Event.filter(id=1)
+
+There are several method on model itself to start query:
+
+- ``first(*args, **kwargs)`` - create QuerySet with given filters
+- ``all()`` - create QuerySet without filters
+- ``first()`` - create QuerySet limited to one object and returning instance instead of list
+
+This method returns ``QuerySet`` object, that allows further filtering and some more complex operations
+
+Also model class have this methods to create object:
+
+- ``create(**kwargs)`` - creates object with given kwargs
+- ``get_or_create(defaults, **kwargs)`` - gets object for given kwargs, if not found create it with additional kwargs from defaults dict
+
+Also instance of model itself has these methods:
+
+- ``save()`` - update instance, or insert it, if it was never saved before
+- ``delete()`` - delete instance from db
+- ``fetch_related(*args)`` - fetches objects related to instance. It can fetch fk relation, backward fk realtion and m2m relation. It also can fetch variable depth of related objects like this: ``await team.fetch_related('events__tournament')`` - this will fetch all events for team, and for each of this events their tournament will be prefetched too. After fetching objects they should be available normally like this: ``team.events[0].tournament.name``
+
+Another approach to work with related objects on instance is to query them explicitly in ``async for``:
+
+.. code-block:: python
+
+    async for team in event.participants:
+        print(team.name)
+
+You also can filter related objects like this:
+
+await team.events.filter(name='First')
+
+which will return you a QuerySet object with predefined filter
+
+QuerySet
+========
+
+After you obtained queryset from object you can do following operations with it:
+
+- ``filter(*args, **kwargs)`` - filters QuerySet by given kwargs. You can filter by related objects like this: ``Team.filter(events__tournament__name='Test')``. You can also pass ``Q`` objects to ``filters`` as args.
+- ``order_by(*args)`` - accept args to filter by in format like ``.order_by('name', '-tournament__name')``. Supports ordering by related models too.
+- ``limit(limit)`` - limits QuerySet by given int
+- ``offset(offset)`` - offset for QuerySet
+- ``distinct()`` - make QuerySet distinct
+- ``values_list(*args, flat=False)`` - make QuerySet returns list of tuples for given args instead of objects. If ``flat`` is  ``True`` and only one arg is passed can return flat list
+- ``values(*args)`` - make QuerySet return dicts instead of objects
+- ``delete()`` - deletes all objects in QuerySet
+- ``update(**kwargs)`` - updates all objects in QuerySet with given kwargs
+- ``count()`` - returns count of objects in queryset instead of objects
+- ``first()`` - limit queryset to one object and return one object instead of list
+- ``prefetch_related(*args)`` - like ``.fetch_related()`` on instance, but works on all objects in QuerySet.
+- ``using_db(client)`` - executes query in other db client. Useful for transactions workaround.
+
+After making your QuerySet you just have to ``await`` it to get the result
+
+Check `examples <https://github.com/Zeliboba5/tortoise-orm/tree/master/examples>`_ to see it all in work
+
+Many to Many
+============
+
+Tortoise provides api for working with M2M relations
+- ``add(*args)`` - adds instances to relation
+- ``remove(*args)`` - removes instances from relation
+- ``clear()`` - removes all objects from relation
+
+You can use them like this:
+
+.. code-block:: python
+
+    await event.participants.add(participant_1, participant_2)
+
+
+
+Q objects
+=========
+
+When you need to make ``OR`` query or something a little more challenging you could use Q objects for it. It is as easy as this:
+
+.. code-block:: python
+
+    found_events = await Event.filter(
+        Q(id__in=[event_first.id, event_second.id]) | Q(name='3')
+    )
+

docs/query.rst

@@ -127,4 +127,4 @@ def init(cls, global_client=None, db_routing=None):
         cls._inited = True
 
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"

tortoise/__init__.py

@@ -187,11 +187,19 @@ def __init__(self, model, instance, m2m_field, is_new):
     async def add(self, *instances, using_db=None):
         db = using_db if using_db else self._db
         through_table = Table(self.field.through)
+        select_query = db.query_class.from_(through_table).where(
+            getattr(through_table, self.field.backward_key) == self.instance.id
+        )
         query = db.query_class.into(through_table).columns(
             getattr(through_table, self.field.forward_key),
             getattr(through_table, self.field.backward_key),
         )
         for instance_to_add in instances:
+            already_existing = await db.execute_query(str(select_query.where(
+                getattr(through_table, self.field.forward_key) == instance_to_add.id
+            ).limit(1)))
+            if already_existing:
+                continue
             query = query.insert(instance_to_add.id, self.instance.id)
         await db.execute_query(str(query))
 

tortoise/fields.py

@@ -266,12 +266,6 @@ async def save(self, *args, **kwargs):
         else:
             await self._update_instance(*args, **kwargs)
 
-    @classmethod
-    async def create(cls, **kwargs):
-        instance = cls(**kwargs)
-        await instance.save(kwargs.get('using_db'))
-        return instance
-
     async def delete(self, using_db=None):
         db = using_db if using_db else self._meta.db
         if not self.id:
@@ -316,6 +310,12 @@ async def get_or_create(cls, using_db=None, defaults=None, **kwargs):
             return instance, False
         return await cls(**defaults, **kwargs).save(using_db=using_db), True
 
+    @classmethod
+    async def create(cls, **kwargs):
+        instance = cls(**kwargs)
+        await instance.save(kwargs.get('using_db'))
+        return instance
+
     @classmethod
     def first(cls):
         return QuerySet(cls).first()