Session documentation: defaults of create_session() vs. sessionmaker()

[Former user]

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.

[Former user]

patch for session.txt

[Mike Bayer]

a doc patch ! thanks very much, will try to get it in soon.

[Michael Trier]

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.

[Former user]

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?).

[Former user]

with extra sentence

[Michael Trier]

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.

[Former user]

Could someone with "Trac admin" privileges please put me ([e-mail]) in the CC: field for this ticket and ticket 1198. I just noticed it said to do so in the ticket guidelines. Thanks.

[Michael Trier]

Fixes the rationale

[Michael Trier]

Added in c4da034f7e7ea2d25cee357b11576c4531aed52f. Thank you. Doc patches are lovely.

[Mike Bayer]

Removing milestone: 0.5.0 (automated comment)