On Jun 29, 7:30 pm, Michael Bayer <[email protected]> wrote: > On Jun 29, 2011, at 12:24 PM, Ben Sizer wrote: > >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:
It's not incorrect, just ambiguous. I expect most people would have read it the way you intended it. But this wasn't my point and it's not directly relevant to my issue: whether it maintains an open connection for each engine or each request doesn't matter - what is important is that it won't make any attempt to connect at all until this point. It's arguably implied, but not explicitly stated. > > 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). The part I meant is: "The Session begins in an essentially stateless form. Once queries are issued or other objects are persisted with it, it requests a connection resource from an Engine that is associated either with the Session itself or with the mapped Table objects being operated upon." This part isn't confusing, it's just that again it does not explicitly state that no connection happens at the start. Saying "When X occurs, Y also occurs" isn't logically the same as "Before X occurs, Y never occurs". So I've not added this to the ticket because I don't this anything about this needs to change. I have just been suggesting something extra to be added in the session config/creation docs: eg., "Note, this does not actually connect to the database yet. Only when your first query is issued will a physical connection be made." > >>> 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. To you (and now to me), it's a small documentation insufficiency, because we know what the problem was. But to me 24 hours ago, this was a problem that stopped my app running entirely. > 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. Yes, of course. sqlalchemy is the best product of its kind, which is why I am here! I was just pointing out that sometimes it's the stuff that -isn't- reported that is actually really important for user retention. It just happens to be one of the things we tracked on the last product I worked on, and I got an eye-opening view into how most users stop using a product for reasons completely different to the ones people complain about. :) My level of tenacity is pretty low, I'll admit! But, I already fixed my bug, and with your help also understand the fix. I just came here to try and help others who might hit the same thing. If you don't think my suggestions help, that's fine. I do accept your point about not being able to adjust the docs to suit every individual user. > > [...] 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. As a user who has no real restriction on configuration, where my use case is simply, "connect to a database and get a session for it", it appears there are 4 different ways I can do that, and the docs tell me how to do all these but don't really explain why, meaning I was not sure whether I was using the wrong approach or a sub-optimal one. 1) import Session directly from sqlalchemy.orm.session and bind that to the engine with the keyword argument on creation. -- "Session is a regular Python class which can be directly instantiated." 2) call sessionmaker() to get a factory for unbound Session subclasses, and call .configure(bind=whatever) to bind it. -- "You can also associate a Engine with an existing sessionmaker() using the sessionmaker.configure() method" 3) call sessionmaker() to get a factory for unbound Session subclasses, and bind each to the engine with the keyword argument on creation. -- "you can also associate individual Session objects with an Engine on each invocation" 4) call sessionmaker(bind=some_engine) to get a factory for bound Sessions and create an already-bound instance. "However, to standardize how sessions are configured and acquired, the sessionmaker() function is normally used" There's also 5) binding to a connection, and it says "the rationale for the above example may not be apparent". But I think the rationale for having the previous 4 different approaches is not immediately apparent either. Now that I vaguely understand all the different use cases (eg. the Pylons example you gave), I can see why you want to support these 4 slightly different routes to the same goal, but I couldn't work them out from the docs, which creates a bit of confusion. > Specific patches against the .rst files would be most helpful here. I'll give it some thought, but the problem with documentation is that the people who don't fully understand the app can't usually be the ones to fix the docs for it. :) Thanks again for your explanations. -- Ben Sizer -- You received this message because you are subscribed to the Google Groups "sqlalchemy" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/sqlalchemy?hl=en.
