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. With features like that, there is simply no way to write a paragraph that will unconditionally impart the correct meaning - only several paragraphs plus examples, bulletpoints would really do the job. However, that is an even worse idea for features that aren't intended for typical use - the verbosity itself gives the wrong impression that this is a key technique, the users continue to not really read or understand the now much more long winded documentation, and you then see the feature being recommended across blogs by users who have come to believe that the flag/method is "necessary", even though they don't know why, and that all goes into the "SQLAlchemy is mysterious" meme. So the choice here is between not documenting the feature at all, getting someone to write the SQLAlchemy book, which has been as yet impossible, which would provide lots and lots of exposition as to which methods are the ones everyone should be using versus those that are for seldom use, or just having a paragraph that does include all the information but doesn't give the impression that people really need to care about it.
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. 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. 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. 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. 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. I get exceptions of all kinds with SQLAlchemy all day long. As long as they are clear and describe the barrier that's been reached, they serve to allow the main documentation to be less daunting and verbose and to provide contextually accurate development guidelines in real time. On Nov 1, 2010, at 11:39 AM, Michael Hipp wrote: > On 11/1/2010 10:19 AM, Michael Bayer wrote: >> SAVEPOINT. This is the technique the average user wants to use. > > Thanks for that. > >> Pertinent documentation: begin(): "When a rollback is issued, the >> subtransaction will directly roll back the innermost *real* transaction". >> rollback(): "This method rolls back the current transaction or nested >> transaction regardless of subtransactions being in effect." > > I think the main thing that seems missing is that once an "inner" rollback is > issued, then the "outer" ones must immediately follow; no other db action > allowed until this is done. (Which isn't the case with nested). > > 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. > -- 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.
