fix bug with infinite relation auto extraction, finish initial relations docs

docs/relations.md

@@ -19,6 +19,9 @@ It automatically creates an sql foreign key constraint on a underlying table as
 
 Of course it's handled for you so you don't have to delve deep into this but you can.
 
+!!!tip
+    Note how by default the relation is optional, you can require the related `Model` by setting `nullable=False` on the `ForeignKey` field.
+
 ### Reverse Relation
 
 At the same time the reverse relationship is registered automatically on parent model (target of `ForeignKey`).
@@ -40,8 +43,13 @@ But you can overwrite this name by providing `related_name` parameter like below
 
 ## Relationship Manager
 
+!!!tip
+    This section is more technical so you might want to skip it if you are not interested in implementation details.
+
+### Need for a manager?
+
 Since orm uses Sqlalchemy core under the hood to prepare the queries, 
-the orm needs a way to uniquely identify each relationship between to tables to construct working queries.
+the orm needs a way to uniquely identify each relationship between the tables to construct working queries.
 
 Imagine that you have models as following:
 
@@ -56,12 +64,15 @@ classes = await SchoolClass.objects.select_related(
 ["teachers__category", "students__category"]).all()
 ```
 
+!!!tip
+    To query a chain of models use double underscores between the relation names (`ForeignKeys` or reverse `ForeignKeys`)
+
 !!!note
     To select related models use `select_related` method from `Model` `QuerySet`.
     
     Note that you use relation (`ForeignKey`) names and not the table names.
 
-Since you join two times to the same table it won't work by default -> you would need to use aliases for category tables and columns.
+Since you join two times to the same table (categories) it won't work by default -> you would need to use aliases for category tables and columns.
 
 But don't worry - orm can handle situations like this, as it uses the Relationship Manager which has it's aliases defined for all relationships.
 
@@ -78,6 +89,8 @@ print(Teacher._orm_relationship_manager == Student._orm_relationship_manager)
 # will produce: True
 ```
 
+### Table aliases
+
 You can even preview the alias used for any relation by passing two tables names.
 
 ```python
@@ -94,3 +107,100 @@ print(Teacher._orm_relationship_manager.resolve_relation_join(
     The order that you pass the names matters -> as those are 2 different relationships depending on join order.
     
     As aliases are produced randomly you can be presented with different results.
+
+### Query automatic construction
+
+Orm is using those aliases during queries to both construct a meaningful and valid sql, 
+as well as later use it to extract proper columns for proper nested models.
+
+Running a previously mentioned query to select school classes and related teachers and students: 
+
+```Python
+classes = await SchoolClass.objects.select_related(
+["teachers__category", "students__category"]).all()
+```
+
+Will result in a query like this (run under the hood):
+
+```sql
+SELECT schoolclasses.id,
+       schoolclasses.name,
+       schoolclasses.department,
+       NZc8e2_students.id          as NZc8e2_id,
+       NZc8e2_students.name        as NZc8e2_name,
+       NZc8e2_students.schoolclass as NZc8e2_schoolclass,
+       NZc8e2_students.category    as NZc8e2_category,
+       MYfe53_categories.id        as MYfe53_id,
+       MYfe53_categories.name      as MYfe53_name,
+       WA49a3_teachers.id          as WA49a3_id,
+       WA49a3_teachers.name        as WA49a3_name,
+       WA49a3_teachers.schoolclass as WA49a3_schoolclass,
+       WA49a3_teachers.category    as WA49a3_category,
+       WZa13b_categories.id        as WZa13b_id,
+       WZa13b_categories.name      as WZa13b_name
+FROM schoolclasses
+         LEFT OUTER JOIN students NZc8e2_students ON NZc8e2_students.schoolclass = schoolclasses.id
+         LEFT OUTER JOIN categories MYfe53_categories ON MYfe53_categories.id = NZc8e2_students.category
+         LEFT OUTER JOIN teachers WA49a3_teachers ON WA49a3_teachers.schoolclass = schoolclasses.id
+         LEFT OUTER JOIN categories WZa13b_categories ON WZa13b_categories.id = WA49a3_teachers.category
+ORDER BY schoolclasses.id, NZc8e2_students.id, MYfe53_categories.id, WA49a3_teachers.id, WZa13b_categories.id
+```
+
+!!!note
+    As mentioned before the aliases are produced dynamically so the actual result might differ.
+    
+    Note that aliases are assigned to relations and not the tables, therefore the first table is always without an alias.
+
+### Returning related Models
+
+Each object in Relationship Manager is identified by orm_id which you can preview like this
+
+```python
+category = Category(name='Math')
+print(category._orm_id)
+# will produce: c76046d9410c4582a656bf12a44c892c (sample value)
+```
+
+Each call to related `Model` is actually coming through the Manager which stores all
+the relations in a dictionary and returns related `Models` by relation type (name) and by object _orm_id.
+
+Since we register both sides of the relation the side registering the relation 
+is always registering the other side as concrete model, 
+while the reverse relation is a weakref.proxy to avoid circular references.
+
+Sounds complicated but in reality it means something like this:
+
+```python
+test_class = await SchoolClass.objects.create(name='Test')
+student = await Student.objects.create(name='John', schoolclass=test_class)
+# the relation to schoolsclass from student (i.e. when you call student.schoolclass) 
+# is a concrete one, meaning directy relating the schoolclass `Model` object
+# On the other side calling test_class.students will result in a list of wekref.proxy objects
+```
+
+!!!tip
+    To learn more about queries and available methods please review [queries][queries] section.
+
+All relations are kept in lists, meaning that when you access related object the Relationship Manager is
+searching itself for related models and get a list of them. 
+
+But since child to parent relation is a many to one type,
+the Manager is unpacking the first (and only) related model from a list and you get an actual `Model` instance instead of a list.
+
+Coming from parent to child relation (one to many) you always get a list of results.
+
+Translating this into concrete sample, the same as above:
+
+```python
+test_class = await SchoolClass.objects.create(name='Test')
+student = await Student.objects.create(name='John', schoolclass=test_class)
+
+student.schoolclass # return a test_class instance extracted from relationship list
+test_class.students # return a list of related wekref.proxy refering related students `Models`
+
+``` 
+
+!!!tip
+    You can preview all relations currently registered by accessing Relationship Manager on any class/instance `Student._orm_relationship_manager._relations`
+
+[queries]: ./queries.md

orm/queryset/query.py

@@ -38,6 +38,7 @@ class Query:
 
         self.auto_related = []
         self.used_aliases = []
+        self.already_checked = []
 
         self.select_from = None
         self.columns = None
@@ -107,7 +108,7 @@ class Query:
         partial_match = any(
             [x.startswith(prev_part_of_related) for x in self._select_related]
         )
-        already_checked = any([x.startswith(rel_part) for x in self.auto_related])
+        already_checked = any([x.startswith(rel_part) for x in (self.auto_related + self.already_checked)])
         return (
                        (field.virtual and parent_virtual)
                        or (partial_match and not already_checked)
@@ -189,6 +190,7 @@ class Query:
                         parent_virtual=field.virtual,
                     )
                 else:
+                    self.already_checked.append(rel_part)
                     rel_part = ""
 
     def _include_auto_related_models(self) -> None:
@@ -225,3 +227,4 @@ class Query:
         self.order_bys = None
         self.auto_related = []
         self.used_aliases = []
+        self.already_checked = []

tests/test_same_table_joins.py

@@ -120,7 +120,7 @@ async def test_right_tables_join():
 async def test_multiple_reverse_related_objects():
     async with database:
         classes = await SchoolClass.objects.select_related(
-            ["teachers__category", "students"]
+            ["teachers__category", "students__category"]
         ).all()
         assert classes[0].name == "Math"
         assert classes[0].students[1].name == "Jack"