Refs -- Updated sql.query.Query.join() docstring.
Follow up to
@@ -894,27 +894,16 @@ class Query:
def join(self, join, reuse=None):
"""
- Return an alias for the join in 'connection', either reusing an
- existing alias for that join or creating a new one. 'connection' is a
- tuple (lhs, table, join_cols) where 'lhs' is either an existing
- table alias or a table name. 'join_cols' is a tuple of tuples containing
- columns to join on ((l_id1, r_id1), (l_id2, r_id2)). The join corresponds
- to the SQL equivalent of::
+ Return an alias for the 'join', either reusing an existing alias for
+ that join or creating a new one. 'join' is either a
+ sql.datastructures.BaseTable or Join.
- lhs.l_id1 = table.r_id1 AND lhs.l_id2 = table.r_id2
-
- The 'reuse' parameter can be either None which means all joins
- (matching the connection) are reusable, or it can be a set containing
- the aliases that can be reused.
+ The 'reuse' parameter can be either None which means all joins are
+ reusable, or it can be a set containing the aliases that can be reused.
A join is always created as LOUTER if the lhs alias is LOUTER to make
- sure we do not generate chains like t1 LOUTER t2 INNER t3. All new
- joins are created as LOUTER if nullable is True.
-
- If 'nullable' is True, the join can potentially involve NULL values and
- is a candidate for promotion (to "left outer") when combining querysets.
-
- The 'join_field' is the field we are joining along (if any).
+ sure chains like t1 LOUTER t2 INNER t3 aren't generated. All new
+ joins are created as LOUTER if the join is nullable.
"""
reuse = [a for a, j in self.alias_map.items()
if (reuse is None or a in reuse) and j == join]
