On 11/1/2010 11:33 AM, Michael Bayer wrote:
OK I think in this case, as in many others, is that "subtransactions" are not an easy to learn feature, hence it is controlled by a flag that is off by default. ...
> ... for features that aren't intended for typical use
Then perhaps say that. "This is an advanced feature that will be of no interest to most users - begin_nested() is a much better choice for nesting of transactions."
In this case, the full phrase "When a rollback is issued, the subtransaction will directly roll back the innermost real transaction, however each subtransaction still must be explicitly rolled back to maintain proper stacking of subtransactions.", states the full reality of the behavior.
This may describe the full reality of the behavior, but IMHO it is a useful description only to someone who already understands it.
There is no "requirement" that the subsequent rollbacks must "immediately" follow, you can do any number of things including just discarding the whole session if you wanted.
If you say so ... but when I can't even do 'session.query().count()' without getting an exception, it appears to me I'm thoroughly dead-in-the-water until I do all those rollbacks. How is any other conclusion possible?
This is where we get into the fact that SQLAlchemy's error messages, which you may have observed are mostly very verbose, are themselves part of the documentation.
Yes, in fact I'd say they're considerably better than the majority of things I deal with. My compliments.
> If we tried to document the specific conditions leading to every ORM error message in the docs, the verbosity of the documentation would grow by a significant margin, the tone would become one of "careful not to do this! careful not to do that!" which would definitely scare away users in a big way.
That's not what I was suggesting. What I always find most helpful is a "here is the canonical way to use this feature ...", "see example at ...".
Is there an example somewhere that shows how to use subtransactions, if so why not link to it and let that be the documentation for this advanced feature that most people won't need anyway. (You can be as verbose and long-winded in the comments of that example as needed, and there such verbosity is considered a good thing rather than a distraction.)
In reality, getting an error message is not a "bad" thing and there's no reason the documentation needs expanded in such a way as to "protect" its users from ever getting an exception.
Again, that's not even close to what I was suggesting. Thanks, Michael -- You received this message because you are subscribed to the Google Groups "sqlalchemy" group. To post to this group, send email to sqlalch...@googlegroups.com. To unsubscribe from this group, send email to sqlalchemy+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sqlalchemy?hl=en.
