Author: phd
Date: Wed Dec 15 13:32:33 2010
New Revision: 4300
Log:
Started to document SQLBuilder's public API. First, SQL statements.
Modified:
SQLObject/trunk/docs/SQLBuilder.txt
Modified: SQLObject/trunk/docs/SQLBuilder.txt
==============================================================================
--- SQLObject/trunk/docs/SQLBuilder.txt Wed Dec 15 13:09:56 2010 (r4299)
+++ SQLObject/trunk/docs/SQLBuilder.txt Wed Dec 15 13:32:33 2010 (r4300)
@@ -66,6 +66,31 @@
To pass a constant, use the ``const`` variable which is actually an
alias for func.
+SQL statements
+==============
+
+SQLBuilder implements objects that execute SQL statements. SQLObject
+uses them internally in its `higher-level API`_, but users can use this
+mid-level API to executes SQL queries that aren't supported by the
+high-level API. To use these objects first construct an instance of a
+statement object, then ask the connection to convert the instance to an
+SQL query and finally ask the connection to execute the query and return
+the results. For example, for Select class::
+
+ >>> from sqlobject.sqlbuilder import *
+ >> select = Select(['name', 'AVG(salary)'], staticTables=['employees'],
+ >> groupBy='name') # create an instance
+ >> query = connection.sqlrepr(select) # Convert to SQL string:
+ >> # SELECT name, AVG(salary) FROM employees GROUP BY name
+ >> rows = connection.queryAll(query) # Execute the query
+ >> # and get back the reuslt as a list of rows
+ >> # where every row is a sequence of length 2 (name and average salary)
+
+.. _`higher-level API`: SQLObject.html
+
+Select
+~~~~~~
+
.. image:: http://sflogo.sourceforge.net/sflogo.php?group_id=74338&type=10
:target: http://sourceforge.net/projects/sqlobject
:class: noborder
|
