make `.join()` more standard, or improve error

This kept tripping me up, largely from how searching for join data online (or on the docs) eventually directs queries.

it seems that every version of .join() within sqlalchemy accepts an isouter=BOOLEAN argument -- except for sqlalchemy.orm.query.Query.join

sqlalchemy.orm.query.Query.join(*props, **kwargs)
sqlalchemy.sql.expression.join(left, right, onclause=None, isouter=False)
sqlalchemy.sql.expression.CLASS.join(right, onclause=None, isouter=False)
sqlalchemy.schema.Table.join(right, onclause=None, isouter=False)
sqlalchemy.orm.join(left, right, onclause=None, isouter=False, join_to_left=None)

In practice, they all behave similarly and will accept this form:

FROM_CLAUSE.join( Class, ClassLeft.on_column == ClassRight.OnColumn )

Everything pretty much works the same... except the orm.query.Query.join doesn't work if you pass in isouter=True. You need to call the outerjoin() method instead.

Things only get confusing when searching online or in the docs, and you end up looking at the docs for the wrong class. Passing isouter to a Query.join just raises a generic TypeError that makes it look like you're joining on the wrong columns:

Traceback (most recent call last):
  File "/Users/jvanasco/Desktop/test.py", line 24, in <module>
    q1.join( A.id, A.id == A.id, isouter=False)
  File "/Users/jvanasco/webserver/environments/test-2.7.5/lib/python2.7/site-packages/SQLAlchemy-0.9.7-py2.7-macosx-10.6-intel.egg/sqlalchemy/orm/query.py", line 1701, in join
    ','.join(kwargs.keys))
TypeError

My suggestion is for one of two behaviors:

orm.query.Query.join accepts isouter and just proxies the request to outerjoin()
if isouter is supplied to orm.query.Query.join, an informative error is raised that just instructs developers that they're using the wrong class and outerjoin is what they want.

Comments (7)