# HG changeset patch
# User Aurelien Campeas <aurelien.campeas@logilab.fr>
# Date 1271421582 -7200
# Node ID 34dc384563768005481bb8f584b5ed462ca23105
# Parent  f24c00325c4d13280a96309c6fa7f61d29317c78
[doc/book] talk a bit of the Result Set class

diff -r f24c00325c4d -r 34dc38456376 doc/book/en/development/devcore/dbapi.rst
--- a/doc/book/en/development/devcore/dbapi.rst	Fri Apr 16 11:40:33 2010 +0200
+++ b/doc/book/en/development/devcore/dbapi.rst	Fri Apr 16 14:39:42 2010 +0200
@@ -1,6 +1,6 @@
 .. _dbapi:
 
-API Python/RQL
+Python/RQL API
 ~~~~~~~~~~~~~~
 
 The Python API developped to interface with RQL is inspired from the standard db-api,
@@ -9,7 +9,7 @@
 
 .. sourcecode:: python
 
-  execute(rqlstring, args=None, cachekey=None, build_descr=True)
+  execute(rqlstring, args=None, build_descr=True)
 
 :rqlstring: the RQL query to execute (unicode)
 :args: if the query contains substitutions, a dictionary containing the values to use
@@ -21,6 +21,7 @@
 however useful in other contexts such as tests or custom controllers.
 
 .. note::
+
   While executing update queries (SET, INSERT, DELETE), if a query generates
   an error related to security, a rollback is automatically done on the current
   transaction.
@@ -79,10 +80,38 @@
 the orm.
 
 
+The `ResultSet` API
+~~~~~~~~~~~~~~~~~~~
+
+ResultSet instances are a very commonly manipulated object. They have
+a rich API as seen below, but we would like to highlight a bunch of
+methods that are quite useful in day-to-day practice:
+
+* `__str__()` (applied by `print`) gives a very useful overview of both
+  the underlying RQL expression and the data inside; unavoidable for
+  debugging purposes
+
+* `printable_rql()` produces back a well formed RQL expression as a
+  string; it is very useful to build views
+
+* `entities()` returns a generator on all entities of the result set
+
+* `get_entity(row, col)` gets the entity at row, col coordinates; one
+  of the most used result set method
+
+.. autoclass:: cubicweb.rset.ResultSet
+   :members:
+
+
 The `Cursor` API
 ~~~~~~~~~~~~~~~~
 
 The whole cursor API is developped below.
 
+.. note:
+
+  In practice we use the `.execute` method on the _cw object of
+  appobjects. Usage of other methods is quite rare.
+
 .. autoclass:: cubicweb.dbapi.Cursor
    :members:
diff -r f24c00325c4d -r 34dc38456376 doc/book/en/development/devweb/views/breadcrumbs.rst
--- a/doc/book/en/development/devweb/views/breadcrumbs.rst	Fri Apr 16 11:40:33 2010 +0200
+++ b/doc/book/en/development/devweb/views/breadcrumbs.rst	Fri Apr 16 14:39:42 2010 +0200
@@ -8,7 +8,7 @@
 ~~~~~~~
 
 Breadcrumbs are displayed by default in the header section (see
-:ref:`the_main_template_sections chapter`).  With the default main
+:ref:`the_main_template_sections`).  With the default main
 template, the header section is composed by the logo, the application
 name, breadcrumbs and, at the most right, the login box. Breadcrumbs
 are displayed just next to the application name, thus breadcrumbs
diff -r f24c00325c4d -r 34dc38456376 doc/book/en/tutorials/base/create-cube.rst
--- a/doc/book/en/tutorials/base/create-cube.rst	Fri Apr 16 11:40:33 2010 +0200
+++ b/doc/book/en/tutorials/base/create-cube.rst	Fri Apr 16 14:39:42 2010 +0200
@@ -69,10 +69,6 @@
   cubicweb-ctl newcube --directory=~/src/cubes blog
 
 
-
-
-
-
 .. _DefineDataModel:
 
 Define your data model
diff -r f24c00325c4d -r 34dc38456376 rset.py
--- a/rset.py	Fri Apr 16 11:40:33 2010 +0200
+++ b/rset.py	Fri Apr 16 14:39:42 2010 +0200
@@ -1,4 +1,4 @@
-"""The `ResultSet` class which is returned as result of a rql query
+"""The `ResultSet` class which is returned as result of an rql query
 
 :organization: Logilab
 :copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
@@ -15,7 +15,7 @@
 
 
 class ResultSet(object):
-    """a result set wrap a RQL query result. This object implements a partial
+    """A result set wraps a RQL query result. This object implements a partial
     list protocol to allow direct use as a list of result rows.
 
     :type rowcount: int
@@ -204,7 +204,7 @@
         return rset
 
     def split_rset(self, keyfunc=None, col=0, return_dict=False):
-        """Splits the result set in multiple result set according to a given key
+        """splits the result set in multiple result set according to a given key
 
         :type keyfunc: callable(entity or FinalType)
         :param keyfunc: