On Jun 29, 2011, at 12:24 PM, Ben Sizer wrote: > >> the lazy initializing behavior of the Session is documented: >> >> http://www.sqlalchemy.org/docs/orm/session.html#unitofwork-transaction > > Not exactly. It says it maintains a connection for each SQL statement,
OK, this happens a lot with me, if anyone can please recommend what university I should go to in order to learn to speak english correctly.... Here's the sentence: As the Session receives requests to execute SQL statements using a particular Engine or Connection, it adds each individual Engine encountered to its transactional state and maintains an open connection for each one (note that a simple application normally has just one Engine). You're taking "each one" to mean, "the SQL statement". When I wrote it, "each one" means, "each Engine". Ticket http://www.sqlalchemy.org/trac/ticket/2204 has been added. > There is a similar implication > in the 'What does the Session do?' paragraph also. Not seeing the "implication" in that one, please add some details to ticket 2204 as to the verbiage you find confusing (log in as guest/guest). > >> But that doesn't have anything to do with the Engine, which is its own >> thing. As far as the Engine, the docs currently use the term "connect" in >> conjunction with create_engine() which is for simplicities' sake, but is >> technically inaccurate, perhaps come up with some term other than "connect", >> "configure a connection source" perhaps. We can add an explicit sentence >> to the top ofhttp://www.sqlalchemy.org/docs/core/connections.html. > >>> I expect I am not unusual >>> in wanting an error in session configuration to fail as soon as >>> possible, >> >> Nobody has ever raised this issue before to my recollection. > > The problem with show-stopper bugs is that people often just give up > and switch to something else rather than tell you about it. ;) "show stopper bug" is quite an exaggeration over what is essentially a small documentation insufficiency. There's more than 25000 messages on the Google Groups list as well as several thousand on previous mailing lists as well as the several thousand tickets in trac, virtually all of which originate from a user experiencing a bug either in SQLAlchemy, in its documentation, or within his or her own usage of the product. The vast majority of these issues have been resolved and those users went away happy. So there is a class of users, and a large one at that, that experience bugs both large and small and don't immediately abandon the project. This class of users continues to expand as the project has grown much stronger over the course of many years, responding to user requests, competing products, etc. There are of course users who abandon the project within 5 minutes, and I would say if their level of tenacity is that low then they're probably better off with whatever tool they end up using. SQLAlchemy is more about a big payoff for some upfront investment. > >> I suppose inefficiency is the only issue but its so unnecessarily >> inefficient, most people would consider it to be wrong behavior. A >> Session may be configured such that depending on what's requested of it, it >> can connect to any number of different engines - connecting to >> several/dozens/hundreds of engines unconditionally upon construction is not >> an option. > > Yeah, that's fine. I just think it would be good to have had something > about this documented right in at the top of the Session docs so that I think the specifics of how Session interacts with engines at a more detailed level is appropriate to be farther down the page, while language can be adjusted higher up as to not introduce misunderstandings. It's common that we get a user who had some kind of problem, that user got frustrated, then they request that very specific documentation for their specific issue be placed as some prominent paragraph somewhere. Unfortunately if we did that every time, the docs would be an enormous list of bulletpoints with no narrative at all. With user confusion, we always take into account the problem they had and that thinking goes into subsequent documentation revisions. >> >> They exist because the intended usage is that sessionmaker() be placed as a >> global variable in the module space of an application - it is then often the >> case that the actual Engine does not exist at this point, so cannot be >> passed to the sessionmaker(). A later configuration step can then call >> configure() to add new Engine configurations. This usage is driven by the >> needs of web frameworks and such. > > Ok, so: > Session = sessionmaker(bind=some_engine) is for when you know > which engine you need at import time; > Session.configure(bind=engine) is when you have decided on the > engine and want all subsequent sessions to use that engine, without > needing to keep a reference to that engine; > session = Session(bind=engine) is when you want to be able to > specify the engine on a per-session basis. > > Is that right? it is > It seems to me like the middle one isn't strictly > necessary as you could just keep a reference to the engine yourself > rather than injecting it into the Session, but I guess that's just a > personal preference. well no, a framework like Pylons starts up, a module declares a scoped_session(), a later initialization phase starts up, reads the .ini file, creates engines, then .configure()s the scoped_session. Refusing to add the .configure() method due to purity concerns and then forcing the app to pass an Engine around whenever a new Session is created seems a little heavyhanded to me. > > I can see why you'd call sessionmaker() at file scope to ensure it's > done at import time, but then why isn't this part just rolled into the > sqlalchemy package directly? Can't it just expose Session to me and > let me call .configure on it? Maybe that's exactly what it means when > the docs say, "Session is a regular Python class which can be directly > instantiated.", which is great, but that means there would be 4 ways > of approaching this, which seems a little much. I'm not sure what the "four ways" are here. You create sessionmaker(), that's your factory. That's just one way. It allows configuration up front as well as additive configuration after the fact, those are two different use cases - one where you have config available immediately, one where some other startup procedure has additional configuration to provide. It allows ad-hoc configuration if you need to make a single Session() with some specific configuration, also, another use case. They can be explicitly documented, sure. Specific patches against the .rst files would be most helpful here. There are actually other "ways" to do it but those are explicitly not in the documentation for this very reason. -- You received this message because you are subscribed to the Google Groups "sqlalchemy" group. To post to this group, send email to sqlalchemy@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.
