[SQL-CVS] r2244 - SQLObject/docs

[<sub...@co...>]

Author: phd
Date: 2007-01-29 08:19:34 -0700 (Mon, 29 Jan 2007)
New Revision: 2244

Added:
   SQLObject/docs/sqlobject-architecture.txt
Modified:
   SQLObject/docs/index.txt
   SQLObject/docs/rebuild
Log:
Added a brief description of SQLObject architecture.


Modified: SQLObject/docs/index.txt
===================================================================
--- SQLObject/docs/index.txt	2007-01-26 19:18:17 UTC (rev 2243)
+++ SQLObject/docs/index.txt	2007-01-29 15:19:34 UTC (rev 2244)
@@ -21,6 +21,7 @@
 * `Main SQLObject documentation <SQLObject.html>`_
 * `Frequently Asked Questions <FAQ.html>`_
 * `sqlbuilder documentation <SQLBuilder.html>`_
+* `A brief description of SQLObject architecture <sqlobject-architecture.html>`_
 * `sqlobject-admin documentation <sqlobject-admin.html>`_
 * `Inheritance <Inheritance.html>`_
 * `Versioning <Versioning.html>`_

Modified: SQLObject/docs/rebuild
===================================================================
--- SQLObject/docs/rebuild	2007-01-26 19:18:17 UTC (rev 2243)
+++ SQLObject/docs/rebuild	2007-01-29 15:19:34 UTC (rev 2244)
@@ -8,7 +8,7 @@
 NORMAL="Authors DeveloperGuide FAQ Inheritance News SQLBuilder
         SQLObject TODO Versioning
         web/index web/links web/repository web/community
-        index community sqlobject-admin"
+        index community sqlobject-architecture sqlobject-admin"
 
 for NAME in $NORMAL ; do
     if [ -e "$NAME.html" -a ! "$NAME.html" -ot "$NAME.txt" ] ; then

Added: SQLObject/docs/sqlobject-architecture.txt
===================================================================
--- SQLObject/docs/sqlobject-architecture.txt	                        (rev 0)
+++ SQLObject/docs/sqlobject-architecture.txt	2007-01-29 15:19:34 UTC (rev 2244)
@@ -0,0 +1,35 @@
+| > SomeTable.select(SomeTable.q.Foo > 30)
+| >
+| > Why doesn't the inner parameter, SomeTable.q.Foo > 30, get evaluated to some boolean value?
+
+.q is an object that returns special attributes of type
+sqlbuilder.SQLExpression. SQLExpression is a special class that overrides
+almost all Python magic methods and upon any operation it, instead of
+evaluating, it constructs another instance of SQLExpression that remembers
+what operation it has to do. A kind of symbolic algebra. Example:
+
+   SQLExpression("foo") > 30
+
+produces SQLExpression("foo", ">", 30) (well, it really produces
+SQLExpression(SQLExpression("foo")...))
+
+| > How does the select(...) method know what to do?
+
+In short, .select() recusively evaluates the top-most SQLExpression to a
+string:
+
+   SQLExpression("foo", ">", 30) => "foo > 30"
+
+and passes the result as a string to the SQL backend.
+
+The longer but more detailed and correct explanation is that .select()
+produces an instance of SelectResults class that upon being iterated over
+produces an instance of Iteration class that upon calling its .next()
+method (it is iterator!) construct the SQL query string, passes it to the
+backend, fetches the results and passes them back to the user.
+
+For the details of the implementation see sqlobject/main.py for SQLObject,
+sqlbuilder.py for SQLExpression, sqlobject/dbconnection.py for DBConnection
+class (that constructs the query strings) and Iteration class, and
+different subdirectories of sqlobject for concrete implementations of
+connection classes - different backends require different query strings.