Why not treat the one-to-many join as what it naturally returns? A list. Let the user make natural Python list operations on the join and perform the necessary magic in the background. Rails ActiveRecord has a similar approach, and use Ruby list operators to deal with it to an extent.
It seems very natural and Pythonic to use Python list operators to deal with results that for all appearences are a list (though un-ordered).
I'll agree in general that using familiar list constructs is good.
Ian's example above is actually something that there is no Python list equivalent for: "create" would create a new instance (with the provided parameters, plus a parameter for the join column) and add it to the list. This is not the same as a simple "append".
ManyToMany joins will use the set-like methods .add() and .remove(). The fact that Set uses .add() is the specific reason I named the method I showed as create and not add. It's certainly my intention to make these recognizable to the degree possible.# Ian Bicking
Also, they are still lazily evaluated. So you can apply methods like .filter(extra_clauses) or .orderBy(column) and these are evaluated in the database. I think -- but still need to give it some thought -- that it will be good for "natural" joins as well. E.g., if there's a ManyToMany join between Book and Author, you might do Author.select(Author.books & Book.title.startswith('L')) to select all authors that have books with titles that start with L -- Author.books would evaluate (in that context) to the SQL join. So that would kind of address a separate request at the same time.# Ian Bicking