Commits

Mike Bayer committed 8f2b744

- some docstrings for select()
- fixed tutorial doctests to adjust for execution changes, session being weak-referencing
(reloads objects more frequently which get u'' applied to their __repr__())

  • Participants
  • Parent commits 05027b9

Comments (0)

Files changed (3)

doc/build/content/ormtutorial.txt

         password VARCHAR(15), 
         PRIMARY KEY (id)
     )
-    None
+    {}
     COMMIT
 
 So now our database is created, our initial schema is present, and our SQLAlchemy application knows all about the tables and columns in the database; this information is to be re-used by the Object Relational Mapper, as we'll see now.
     ...         self.password = password
     ...
     ...     def __repr__(self):
-    ...        return "<User(%r,%r, %r)>" % (self.name, self.fullname, self.password)
+    ...        return "<User('%s','%s', '%s')>" % (self.name, self.fullname, self.password)
 
 ## Setting up the Mapping
 
     {python}
     >>> session.save(ed_user)
     
-But you'll notice nothing has happened yet.  Well, lets pretend something did, and try to query for our user.  This is done using the `query()` method on `Session`.  We create a new query representing the set of all `User` objects first.  Then we narrow the results by "filtering" down to the user we want; that is, the user whose `name` attribute is `"ed"`.  Finally we call `first()` which tells `Query`, "we'd like the first result in this list".
+But yo'll notice nothing has happened yet.  Well, lets pretend something did, and try to query for our user.  This is done using the `query()` method on `Session`.  We create a new query representing the set of all `User` objects first.  Then we narrow the results by "filtering" down to the user we want; that is, the user whose `name` attribute is `"ed"`.  Finally we call `first()` which tells `Query`, "we'd like the first result in this list".
 
     {python}
     {sql}>>> session.query(User).filter_by(name='ed').first() # doctest:+ELLIPSIS,+NORMALIZE_WHITESPACE
     ['ed']
     {stop}<User('ed','Ed Jones', 'edspassword')>
 
-And we get back our new user.  If you view the generated SQL, you'll see that the `Session` issued an `INSERT` statement before querying.  The `Session` stores whatever you put into it in memory, and at certain points it issues a **flush**, which issues SQL to the database to store all pending new objects and changes to existing objects.  You can manually invoke the flush operation using `flush()`; however when the `Session` is configured to `autoflush`, its usually not needed.
+And we get back our new user.  If you view the generated SQL, yo'll see that the `Session` issued an `INSERT` statement before querying.  The `Session` stores whatever you put into it in memory, and at certain points it issues a **flush**, which issues SQL to the database to store all pending new objects and changes to existing objects.  You can manually invoke the flush operation using `flush()`; however when the `Session` is configured to `autoflush`, its usually not needed.
 
 OK, let's do some more operations.  We'll create and save three more users:
 
         PRIMARY KEY (id), 
          FOREIGN KEY(user_id) REFERENCES users (id)
     )
-    None
+    {}
     COMMIT
 
 For our ORM setup, we're going to start all over again.  We will first close out our `Session` and clear all `Mapper` objects:
     ...         self.email_address = email_address
     ...
     ...     def __repr__(self):
-    ...         return "<Address(%r)>" % self.email_address
+    ...         return "<Address('%s')>" % self.email_address
 
 Now comes the fun part.  We define a mapper for each class, and associate them using a function called `relation()`.  We can define each mapper in any order we want:
 
     ['jack']
     
     >>> jack
-    <User(u'jack',u'Jack Bean', u'gjffdd')>
+    <User('jack','Jack Bean', 'gjffdd')>
     
 Let's look at the `addresses` collection.  Watch the SQL:
 
     FROM addresses 
     WHERE ? = addresses.user_id ORDER BY addresses.oid
     [5]
-    {stop}[<Address(u'jack@google.com')>, <Address(u'j25@yahoo.com')>]
+    {stop}[<Address('jack@google.com')>, <Address('j25@yahoo.com')>]
     
 When we accessed the `addresses` collection, SQL was suddenly issued.  This is an example of a **lazy loading relation**.
 
     ['jack']
     
     >>> jack
-    <User(u'jack',u'Jack Bean', u'gjffdd')>
+    <User('jack','Jack Bean', 'gjffdd')>
     
     >>> jack.addresses
-    [<Address(u'jack@google.com')>, <Address(u'j25@yahoo.com')>]
+    [<Address('jack@google.com')>, <Address('j25@yahoo.com')>]
     
 If you think that query is elaborate, it is !  But SQLAlchemy is just getting started.  Note that when using eager loading, *nothing* changes as far as the ultimate results returned.  The "loading strategy", as its called, is designed to be completely transparent in all cases, and is for optimization purposes only.  Any query criterion you use to load objects, including ordering, limiting, other joins, etc., should return identical results regardless of the combination of lazily- and eagerly- loaded relationships present.
 
     FROM users, addresses 
     WHERE users.id = addresses.user_id AND addresses.email_address = ? ORDER BY users.oid
     ['jack@google.com']
-    {stop}[<User(u'jack',u'Jack Bean', u'gjffdd')>]
+    {stop}[<User('jack','Jack Bean', 'gjffdd')>]
 
 Or we can make a real JOIN construct; below we use the `join()` function available on `Table` to create a `Join` object, then tell the `Query` to use it as our FROM clause:
 
     FROM users JOIN addresses ON users.id = addresses.user_id 
     WHERE addresses.email_address = ? ORDER BY users.oid
     ['jack@google.com']
-    {stop}[<User(u'jack',u'Jack Bean', u'gjffdd')>]
+    {stop}[<User('jack','Jack Bean', 'gjffdd')>]
 
 Note that the `join()` construct has no problem figuring out the correct join condition between `users_table` and `addresses_table`..the `ForeignKey` we constructed says it all.
 
     FROM users JOIN addresses ON users.id = addresses.user_id 
     WHERE addresses.email_address = ? ORDER BY users.oid
     ['jack@google.com']
-    {stop}[<User(u'jack',u'Jack Bean', u'gjffdd')>]
+    {stop}[<User('jack','Jack Bean', 'gjffdd')>]
 
 By "A to B", we mean a single relation name or a path of relations.  In our case we only have `User->addresses->Address` configured, but if we had a setup like `A->bars->B->bats->C->widgets->D`, a join along all four entities would look like:
 
     FROM users JOIN addresses ON users.id = addresses.user_id 
     WHERE addresses.email_address = ? AND users.name = ? ORDER BY users.oid
     ['jack@google.com', 'jack']
-    {stop}[<User(u'jack',u'Jack Bean', u'gjffdd')>]
+    {stop}[<User('jack','Jack Bean', 'gjffdd')>]
 
 In all cases, we can get the `User` and the matching `Address` objects back at the same time, by telling the session we want both.  This returns the results as a list of tuples:
 
     FROM users JOIN addresses ON users.id = addresses.user_id 
     WHERE addresses.email_address = ? ORDER BY users.oid
     ['jack@google.com']
-    {stop}[(<User(u'jack',u'Jack Bean', u'gjffdd')>, <Address(u'jack@google.com')>)]
+    {stop}[(<User('jack','Jack Bean', 'gjffdd')>, <Address('jack@google.com')>)]
 
 Another common scenario is the need to join on the same table more than once.  For example, if we want to find a `User` who has two distinct email addresses, both `jack@google.com` as well as `j25@yahoo.com`, we need to join to the `Addresses` table twice.  SQLAlchemy does provide `Alias` objects which can accomplish this; but far easier is just to tell `join()` to alias for you:
 
     FROM users JOIN addresses AS addresses_1 ON users.id = addresses_1.user_id JOIN addresses AS addresses_2 ON users.id = addresses_2.user_id 
     WHERE addresses_1.email_address = ? AND addresses_2.email_address = ? ORDER BY users.oid
     ['jack@google.com', 'j25@yahoo.com']
-    {stop}[<User(u'jack',u'Jack Bean', u'gjffdd')>]
+    {stop}[<User('jack','Jack Bean', 'gjffdd')>]
 
 The key thing which occured above is that our SQL criterion were **aliased** as appropriate corresponding to the alias generated in the most recent `join()` call.  
 
         PRIMARY KEY (id), 
          FOREIGN KEY(user_id) REFERENCES users (id)
     )
-    None
+    {}
     COMMIT
     CREATE TABLE keywords (
         id INTEGER NOT NULL, 
         PRIMARY KEY (id), 
          UNIQUE (keyword)
     )
-    None
+    {}
     COMMIT
     CREATE TABLE post_keywords (
         post_id INTEGER, 
          FOREIGN KEY(post_id) REFERENCES posts (id), 
          FOREIGN KEY(keyword_id) REFERENCES keywords (id)
     )
-    None
+    {}
     COMMIT
 
 Then some classes:
     
 There's three new things in the above mapper:
 
-  * the `User` relation has a backref, like we've used before, except this time it references a function called `backref()`.  This function is used when you'd like to specify keyword options for the backwards relationship.
+  * the `User` relation has a backref, like we've used before, except this time it references a function called `backref()`.  This function is used when yo'd like to specify keyword options for the backwards relationship.
   * the keyword option we specified to `backref()` is `lazy="dynamic"`.  This sets a default **loader strategy** on the attribute, in this case a special strategy that allows partial loading of results.
   * The `keywords` relation uses a keyword argument `secondary` to indicate the **association table** for the many to many relationship from `BlogPost` to `Keyword`.
     
     FROM post_keywords, keywords 
     WHERE posts.id = post_keywords.post_id AND keywords.id = post_keywords.keyword_id AND keywords.keyword = ?) ORDER BY posts.oid
     ['firstpost']
-    {stop}[BlogPost("Wendy's Blog Post", 'This is a test', <User(u'wendy',u'Wendy Williams', u'foobar')>)]
+    {stop}[BlogPost("Wendy's Blog Post", 'This is a test', <User('wendy','Wendy Williams', 'foobar')>)]
     
 If we want to look up just Wendy's posts, we can tell the query to narrow down to her as a parent:
 
     FROM post_keywords, keywords 
     WHERE posts.id = post_keywords.post_id AND keywords.id = post_keywords.keyword_id AND keywords.keyword = ?)) ORDER BY posts.oid
     [2, 'firstpost']
-    {stop}[BlogPost("Wendy's Blog Post", 'This is a test', <User(u'wendy',u'Wendy Williams', u'foobar')>)]
+    {stop}[BlogPost("Wendy's Blog Post", 'This is a test', <User('wendy','Wendy Williams', 'foobar')>)]
 
 Or we can use Wendy's own `posts` relation, which is a "dynamic" relation, to query straight from there:
 
     FROM post_keywords, keywords 
     WHERE posts.id = post_keywords.post_id AND keywords.id = post_keywords.keyword_id AND keywords.keyword = ?)) ORDER BY posts.oid
     [2, 'firstpost']
-    {stop}[BlogPost("Wendy's Blog Post", 'This is a test', <User(u'wendy',u'Wendy Williams', u'foobar')>)]
+    {stop}[BlogPost("Wendy's Blog Post", 'This is a test', <User('wendy','Wendy Williams', 'foobar')>)]
 
 ## Further Reference 
 

doc/build/content/sqlexpression.txt

         fullname VARCHAR(100), 
         PRIMARY KEY (id)
     )
-    None
+    {}
     COMMIT
     CREATE TABLE addresses (
         id INTEGER NOT NULL, 
         PRIMARY KEY (id), 
          FOREIGN KEY(user_id) REFERENCES users (id)
     )
-    None
+    {}
     COMMIT
 
 ## Insert Expressions

lib/sqlalchemy/sql/expression.py

         self._froms = [f for f in oldfroms.union(newfroms)]
 
     def column(self, column):
+        """return a new select() construct with the given column expression added to its columns clause."""
+        
         s = self._generate()
         s.append_column(column)
         return s
 
     def where(self, whereclause):
+        """return a new select() construct with the given expression added to its WHERE clause, joined
+        to the existing clause via AND, if any."""
+        
         s = self._generate()
         s.append_whereclause(whereclause)
         return s
 
     def having(self, having):
+        """return a new select() construct with the given expression added to its HAVING clause, joined
+        to the existing clause via AND, if any."""
+        
         s = self._generate()
         s.append_having(having)
         return s
 
     def distinct(self):
+        """return a new select() construct which will apply DISTINCT to its columns clause."""
+        
         s = self._generate()
         s._distinct = True
         return s
 
     def prefix_with(self, clause):
+        """return a new select() construct which will apply the given expression to the start of its
+        columns clause, not using any commas."""
+        
         s = self._generate()
         s.append_prefix(clause)
         return s
 
     def select_from(self, fromclause):
+        """return a new select() construct with the given FROM expression applied to its list of 
+        FROM objects."""
+        
         s = self._generate()
         s.append_from(fromclause)
         return s
         return s
 
     def correlate(self, fromclause):
+        """return a new select() construct which will correlate the given FROM clause to that
+        of an enclosing select(), if a match is found.  
+        
+        By "match", the given fromclause must be present in this select's list of FROM objects
+        and also present in an enclosing select's list of FROM objects.
+        
+        Calling this method turns off the select's default behavior of "auto-correlation".  Normally,
+        select() auto-correlates all of its FROM clauses to those of an embedded select when 
+        compiled.
+        
+        If the fromclause is None, the select() will not correlate to anything. 
+        """
+        
         s = self._generate()
         s._should_correlate=False
         if fromclause is None:
         return s
 
     def append_correlation(self, fromclause, copy_collection=True):
+        """append the given correlation expression to this select() construct."""
+        
         if not copy_collection:
             self.__correlate.add(fromclause)
         else:
             self.__correlate = util.Set(list(self.__correlate) + [fromclause])
 
     def append_column(self, column, copy_collection=True):
+        """append the given column expression to the columns clause of this select() construct."""
+        
         column = _literal_as_column(column)
 
         if isinstance(column, _ScalarSelect):
             self._raw_columns = self._raw_columns + [column]
 
     def append_prefix(self, clause, copy_collection=True):
+        """append the given columns clause prefix expression to this select() construct."""
+        
         clause = _literal_as_text(clause)
         if not copy_collection:
             self._prefixes.append(clause)
             self._prefixes = self._prefixes + [clause]
 
     def append_whereclause(self, whereclause):
+        """append the given expression to this select() construct's WHERE criterion.
+        
+        The expression will be joined to existing WHERE criterion via AND.
+        """
+        
         if self._whereclause  is not None:
             self._whereclause = and_(self._whereclause, _literal_as_text(whereclause))
         else:
             self._whereclause = _literal_as_text(whereclause)
 
     def append_having(self, having):
+        """append the given expression to this select() construct's HAVING criterion.
+        
+        The expression will be joined to existing HAVING criterion via AND.
+        """
+        
         if self._having is not None:
             self._having = and_(self._having, _literal_as_text(having))
         else: