Added type hints for relation managers (#235)

CHANGELOG.rst

@@ -2,6 +2,11 @@
 
 Changelog
 =========
+0.14.1
+-------
+- `ManyToManyField` is now a function instead of a class.
+- Added section on adding better autocomplete for relations in editors.
+
 0.14.0
 ------
 .. caution::

docs/fields.rst

@@ -77,9 +77,11 @@ Relational Fields
 .. autoclass:: tortoise.fields.ForeignKeyField
     :exclude-members: to_db_value, to_python_value
 
-.. autoclass:: tortoise.fields.ManyToManyField
-    :exclude-members: to_db_value, to_python_value
+.. autofunction:: tortoise.fields.ManyToManyField
+
+.. autodata:: tortoise.fields.ForeignKeyRelation
 
+.. autodata:: tortoise.fields.ForeignKeyNullableRelation
 
 Extending A Field
 =================

docs/models.rst

@@ -306,6 +306,58 @@ Sync usage requires that you call `fetch_related` before the time, and then you
 
 The reverse lookup of ``team.event_team`` works exactly the same way.
 
+``Improving relational type hinting``
+-------------------------------------
+
+Since Tortoise ORM is still a young project, it does not have such widespread support by
+various editors who help you writing code using good autocomplete for models and
+different relations between them.
+However, you can get such autocomplete by doing a little work yourself.
+All you need to do is add a few annotations to your models for fields that are responsible
+for the relations.
+
+Here is an updated example from :ref:`getting_started`, that will add autocomplete for
+all models including fields for the relations between models.
+
+.. code-block:: python3
+
+    from tortoise.models import Model
+    from tortoise import fields
+
+
+    class Tournament(Model):
+        id = fields.IntField(pk=True)
+        name = fields.CharField(max_length=255)
+
+        events: fields.ReverseRelation["Event"]
+
+        def __str__(self):
+            return self.name
+
+
+    class Event(Model):
+        id = fields.IntField(pk=True)
+        name = fields.CharField(max_length=255)
+        tournament: fields.ForeignKeyRelation[Tournament] = fields.ForeignKeyField(
+            "models.Tournament", related_name="events"
+        )
+        participants: fields.ManyToManyRelation["Team"] = 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.CharField(max_length=255)
+
+        events: fields.ManyToManyRelation[Event]
+
+        def __str__(self):
+            return self.name
+
 
 Reference
 =========

docs/query.rst

@@ -150,7 +150,7 @@ Foreign Key
 
 Tortoise ORM provides an API for working with FK relations
 
-.. autoclass:: tortoise.fields.RelationQueryContainer
+.. autoclass:: tortoise.fields.ReverseRelation
     :members:
 
 
@@ -161,7 +161,7 @@ Many to Many
 
 Tortoise ORM provides an API for working with M2M relations
 
-.. autoclass:: tortoise.fields.ManyToManyRelationManager
+.. autoclass:: tortoise.fields.ManyToManyRelation
     :members:
     :inherited-members:
 

examples/complex_filtering.py

@@ -12,15 +12,19 @@ class Tournament(Model):
     id = fields.IntField(pk=True)
     name = fields.TextField()
 
+    events: fields.ReverseRelation["Event"]
+
     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(
+    tournament: fields.ForeignKeyRelation[Tournament] = fields.ForeignKeyField(
+        "models.Tournament", related_name="events"
+    )
+    participants: fields.ManyToManyRelation["Team"] = fields.ManyToManyField(
         "models.Team", related_name="events", through="event_team"
     )
 
@@ -32,6 +36,8 @@ class Team(Model):
     id = fields.IntField(pk=True)
     name = fields.TextField()
 
+    events: fields.ManyToManyRelation[Event]
+
     def __str__(self):
         return self.name
 

examples/complex_prefetching.py

@@ -7,15 +7,19 @@ class Tournament(Model):
     id = fields.IntField(pk=True)
     name = fields.TextField()
 
+    events: fields.ReverseRelation["Event"]
+
     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(
+    tournament: fields.ForeignKeyRelation[Tournament] = fields.ForeignKeyField(
+        "models.Tournament", related_name="events"
+    )
+    participants: fields.ManyToManyRelation["Team"] = fields.ManyToManyField(
         "models.Team", related_name="events", through="event_team"
     )
 
@@ -27,6 +31,8 @@ class Team(Model):
     id = fields.IntField(pk=True)
     name = fields.TextField()
 
+    events: fields.ManyToManyRelation[Event]
+
     def __str__(self):
         return self.name
 

examples/functions.py

@@ -8,15 +8,19 @@ class Tournament(Model):
     name = fields.TextField()
     desc = fields.TextField(null=True)
 
+    events: fields.ReverseRelation["Event"]
+
     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(
+    tournament: fields.ForeignKeyRelation[Tournament] = fields.ForeignKeyField(
+        "models.Tournament", related_name="events"
+    )
+    participants: fields.ManyToManyRelation["Team"] = fields.ManyToManyField(
         "models.Team", related_name="events", through="event_team"
     )
 
@@ -28,6 +32,8 @@ class Team(Model):
     id = fields.IntField(pk=True)
     name = fields.TextField()
 
+    events: fields.ManyToManyRelation[Event]
+
     def __str__(self):
         return self.name
 

examples/relations.py

@@ -14,15 +14,19 @@ class Tournament(Model):
     id = fields.IntField(pk=True)
     name = fields.TextField()
 
+    events: fields.ReverseRelation["Event"]
+
     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(
+    tournament: fields.ForeignKeyRelation[Tournament] = fields.ForeignKeyField(
+        "models.Tournament", related_name="events"
+    )
+    participants: fields.ManyToManyRelation["Team"] = fields.ManyToManyField(
         "models.Team", related_name="events", through="event_team"
     )
 
@@ -34,6 +38,8 @@ class Team(Model):
     id = fields.IntField(pk=True)
     name = fields.TextField()
 
+    events: fields.ManyToManyRelation[Event]
+
     def __str__(self):
         return self.name
 

examples/relations_recursive.py

@@ -14,8 +14,16 @@
 
 class Employee(Model):
     name = fields.CharField(max_length=50)
-    manager = fields.ForeignKeyField("models.Employee", related_name="team_members", null=True)
-    talks_to = fields.ManyToManyField("models.Employee", related_name="gets_talked_to")
+
+    manager: fields.ForeignKeyNullableRelation["Employee"] = fields.ForeignKeyField(
+        "models.Employee", related_name="team_members", null=True
+    )
+    team_members: fields.ReverseRelation["Employee"]
+
+    talks_to: fields.ManyToManyRelation["Employee"] = fields.ManyToManyField(
+        "models.Employee", related_name="gets_talked_to"
+    )
+    gets_talked_to: fields.ManyToManyRelation["Employee"]
 
     def __str__(self):
         return self.name

examples/schema_create.py

@@ -11,17 +11,19 @@ class Tournament(Model):
     name = fields.CharField(max_length=255, description="Tournament name", index=True)
     created = fields.DatetimeField(auto_now_add=True, description="Created datetime")
 
+    events: fields.ReverseRelation["Event"]
+
     class Meta:
         table_description = "What Tournaments we have"
 
 
 class Event(Model):
     id = fields.IntField(pk=True, description="Event ID")
     name = fields.CharField(max_length=255, unique=True)
-    tournament = fields.ForeignKeyField(
+    tournament: fields.ForeignKeyRelation[Tournament] = fields.ForeignKeyField(
         "models.Tournament", related_name="events", description="FK to tournament"
     )
-    participants = fields.ManyToManyField(
+    participants: fields.ManyToManyRelation["Team"] = fields.ManyToManyField(
         "models.Team",
         related_name="events",
         through="event_team",
@@ -38,6 +40,8 @@ class Meta:
 class Team(Model):
     name = fields.CharField(max_length=50, pk=True, description="The TEAM name (and PK)")
 
+    events: fields.ManyToManyRelation[Event]
+
     class Meta:
         table_description = "The TEAMS!"
 

examples/two_databases.py

@@ -29,7 +29,7 @@ class Event(Model):
     name = fields.TextField()
     tournament_id = fields.IntField()
     # Here we make link to events.Team, not models.Team
-    participants = fields.ManyToManyField(
+    participants: fields.ManyToManyRelation["Team"] = fields.ManyToManyField(
         "events.Team", related_name="events", through="event_team"
     )
 
@@ -44,6 +44,8 @@ class Team(Model):
     id = fields.IntField(pk=True)
     name = fields.TextField()
 
+    event_team: fields.ManyToManyRelation[Event]
+
     def __str__(self):
         return self.name
 

tests/models_dup1.py

@@ -1,6 +1,7 @@
 """
 This is the testing Models — Duplicate 1
 """
+
 from tortoise import fields
 from tortoise.models import Model
 

tests/models_dup2.py

@@ -1,6 +1,7 @@
 """
 This is the testing Models — Duplicate 1
 """
+
 from tortoise import fields
 from tortoise.models import Model
 

tests/models_schema_create.py

@@ -38,8 +38,8 @@ class Meta:
 
 class Team(Model):
     name = fields.CharField(max_length=50, pk=True, description="The TEAM name (and PK)")
-    manager = fields.ForeignKeyField("models.Team", related_name="team_members", null=True)
     key = fields.IntField()
+    manager = fields.ForeignKeyField("models.Team", related_name="team_members", null=True)
     talks_to = fields.ManyToManyField("models.Team", related_name="gets_talked_to")
 
     class Meta:
@@ -50,9 +50,11 @@ class Meta:
 class SourceFields(Model):
     id = fields.IntField(pk=True, source_field="sometable_id")
     chars = fields.CharField(max_length=255, source_field="some_chars_table", index=True)
+
     fk = fields.ForeignKeyField(
         "models.SourceFields", related_name="team_members", null=True, source_field="fk_sometable"
     )
+
     rel_to = fields.ManyToManyField(
         "models.SourceFields",
         related_name="rel_from",