# HG changeset patch # User Aurelien Campeas # Date 1270741837 -7200 # Node ID 84d4587a92bc4a6809cf8a86197beb14f81eb0b9 # Parent 99cdb9608cc147c66ca2f3d6ff7d52ed1bdd238d [doc/book] rql/dbapi cleanup, rip cachekey (prematurely ?) diff -r 99cdb9608cc1 -r 84d4587a92bc doc/book/en/annexes/rql/intro.rst --- a/doc/book/en/annexes/rql/intro.rst Thu Apr 08 17:47:52 2010 +0200 +++ b/doc/book/en/annexes/rql/intro.rst Thu Apr 08 17:50:37 2010 +0200 @@ -5,10 +5,10 @@ Goals of RQL ~~~~~~~~~~~~ -The goal is to have a language emphasizing the way of browsing relations. As -such, attributes will be regarded as cases of special relations (in terms of -implementation, the user should see no difference between an attribute and a -relation). +The goal is to have a language making relations browsing easy. As +such, attributes will be regarded as cases of special relations (in +terms of usage, the user should see no syntactic difference between an +attribute and a relation). Comparison with existing languages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -32,10 +32,10 @@ We should look in more detail, but here are already some ideas for the moment ... Versa_ is the language most similar to what we wanted to do, but the model -underlying data being RDF, there is some number of things such as namespaces or +underlying data being RDF, there are some things such as namespaces or handling of the RDF types which does not interest us. On the functionality level, Versa_ is very comprehensive including through many functions of -conversion and basic types manipulation, which may need to be guided at one time +conversion and basic types manipulation, which we may want to look at one time or another. Finally, the syntax is a little esoteric. diff -r 99cdb9608cc1 -r 84d4587a92bc doc/book/en/development/devcore/dbapi.rst --- a/doc/book/en/development/devcore/dbapi.rst Thu Apr 08 17:47:52 2010 +0200 +++ b/doc/book/en/development/devcore/dbapi.rst Thu Apr 08 17:50:37 2010 +0200 @@ -5,9 +5,10 @@ The Python API developped to interface with RQL is inspired from the standard db-api, with a Connection object having the methods cursor, rollback and commit essentially. -The most important method is the `execute` method of a cursor : +The most important method is the `execute` method of a cursor. -`execute(rqlstring, args=None, cachekey=None, build_descr=True)` +.. sourcecode:: python + execute(rqlstring, args=None, cachekey=None, build_descr=True) :rqlstring: the RQL query to execute (unicode) :args: if the query contains substitutions, a dictionary containing the values to use @@ -18,10 +19,11 @@ through this argument -The `Connection` object owns the methods `commit` and `rollback`. You *should -never need to use them* during the development of the web interface based on -the *CubicWeb* framework as it determines the end of the transaction depending -on the query execution success. +The `Connection` object owns the methods `commit` and `rollback`. You +*should never need to use them* during the development of the web +interface based on the *CubicWeb* framework as it determines the end +of the transaction depending on the query execution success. They are +however useful in other contexts such as tests. .. note:: While executing update queries (SET, INSERT, DELETE), if a query generates @@ -30,6 +32,7 @@ Executing RQL queries from a view or a hook ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + When you're within code of the web interface, the db-api like connexion is handled by the request object. You should not have to access it directly, but use the `execute` method directly available on the request, eg: @@ -50,21 +53,15 @@ self._cw.execute('Any T WHERE T in_conf C, C eid %s' % entity.eid) -But it can also be written in a syntax that will benefit from the use +But it must be written in a syntax that will benefit from the use of a cache on the RQL server side: .. sourcecode:: python - self._cw.execute('Any T WHERE T in_conf C, C eid %(x)s', {'x': entity.eid}, 'x') + self._cw.execute('Any T WHERE T in_conf C, C eid %(x)s', {'x': entity.eid}) -Beside proper usage of the `args` argument, notice the latest argument: this is what's called -the cache key. The cache key should be either a string or a tuple containing the names of keys -in args which are referencing eids. *YOU MUST SET THIS PROPERLY* if you don't want weird result -on queries which have ambigous solutions deambiguified by specifing an eid. So the good habit is: -*always put in the cache key all eid keys*. - -The syntax tree is build once for the "generic" RQL and can be re-used -with a number of different eid. +The syntax tree is built once for the "generic" RQL and can be re-used +with a number of different eids. Alternativelly, some of the common data related to an entity can be obtained from the top-level `entity.related()` method (which is used under the hood by the orm diff -r 99cdb9608cc1 -r 84d4587a92bc doc/book/en/intro/concepts.rst --- a/doc/book/en/intro/concepts.rst Thu Apr 08 17:47:52 2010 +0200 +++ b/doc/book/en/intro/concepts.rst Thu Apr 08 17:50:37 2010 +0200 @@ -339,5 +339,5 @@ .. Note: RQL queries executed in hooks and operations are *unsafe* by default, e.g. the read and write security is deactivated unless explicitly asked. - + .. |cubicweb| replace:: *CubicWeb*