[Sqlalchemy-tickets] Issue #3217: make `.join()` more standard, or improve error (zzzeek/sqlalchemy)

[jvanasco <iss...@bi...>]

New issue 3217: make `.join()` more standard, or improve error
https://bitbucket.org/zzzeek/sqlalchemy/issue/3217/make-join-more-standard-or-improve-error

jvanasco:

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:

1. `orm.query.Query.join` accepts `isouter` and just proxies the request to `outerjoin()`
2. 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.