- attached session.txt.patch
Session documentation: defaults of create_session() vs. sessionmaker()
I believe that the defaults of create_session() should be in the documentation. Since they are different than the defaults for sessionmaker, it can be a bit confusing.
Attached is a documentation patch.
Comments (11)
-
Account Deleted -
repo owner a doc patch ! thanks very much, will try to get it in soon.
-
Thank you for the patch. My only question is regarding the recommendation. I don't know that it's fair to say that the recommendation is for sessionmaker, it kind of depends on your use case.
-
Account Deleted My documentation patch quotes the docstring for create_session(), more or less. As you can see, the create_session docstring recommends against itself:
def create_session(bind=None, **kwargs): """create a new [sqlalchemy.orm.session#Session](sqlalchemy.orm.session#Session). The defaults of create_session() are the opposite of that of sessionmaker(); autoflush and expire_on_commit are false, autocommit is True. In this sense the session acts more like the "classic" SQLAlchemy 0.3 session with these defaults. It is recommended to use the [sqlalchemy.orm#sessionmaker()](sqlalchemy.orm#sessionmaker()) function instead of create_session(). """
In any case, the documentation should mention the difference in default values.
I also suggest to include the reason for the difference. The attached patch file (session.txt.patch_v2) includes a sentence abt. that as well ("create_session() has different default values for autoflush, autocommit and expire_on_commit to be backwards compatible with SQLAlchemy version 0.3."). I am, however, unsure if this statement is correct (i.e. is that the reason?).
-
Account Deleted - attached session.txt.patch_v2
with extra sentence
-
- assigned issue to
Thank you for the research on this. I was not aware of the docstring recommendation. I will check with zzzeek on this. Thanks again for the help.
-
Account Deleted Could someone with "Trac admin" privileges please put me (bernt.brenna@gmail.com) in the CC: field for this ticket and ticket 1198. I just noticed it said to do so in the ticket guidelines. Thanks.
-
- changed watchers to bernt.brenna@gmail.com
-
- attached doc.diff
Fixes the rationale
-
- changed status to resolved
Added in c4da034f7e7ea2d25cee357b11576c4531aed52f. Thank you. Doc patches are lovely.
-
repo owner - removed milestone
Removing milestone: 0.5.0 (automated comment)
- Log in to comment
patch for session.txt