3.5.1 Python/RQL API
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.
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
The Connection object owns the methods commit and rollback. You should never need to use them during the devel-opment 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 or custom controllers.
Note: If a query generates an error related to security (Unauthorized) or to integrity (ValidationError), the transaction can still continue but you won’t be able to commit it, a rollback will be necessary to start a new transaction.
Also, a rollback is automatically done if an error occurs during commit.
Note: A ValidationError has a entity attribute. In CubicWeb, this atttribute is set to the entity’s eid (not a reference to the entity itself).
3.5.2 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:
rset = self._cw.execute(rqlstring, kwargs)
Similarly, on the server side (eg in hooks), there is no db-api connexion (since you’re directly inside the data-server), so you’ll have to use the execute method of the session object.
3.5.3 Proper usage of .execute
Let’s say you want to get T which is in configuration C, this translates to:
self._cw.execute(’Any T WHERE T in_conf C, C eid %s’ % entity.eid)
But it must be written in a syntax that will benefit from the use of a cache on the RQL server side:
self._cw.execute(’Any T WHERE T in_conf C, C eid %(x)s’, {’x’: entity.eid})
The syntax tree is built once for the “generic” RQL and can be re-used with a number of different eids. There rql IN operator is an exception to this rule.
self._cw.execute(’Any T WHERE T in_conf C, C name IN (%s)’
% ’,’.join([’foo’, ’bar’]))
Alternativelly, some of the common data related to an entity can be obtained from the entity.related() method (which is used under the hood by the orm when you use attribute access notation on an entity to get a relation. The initial request would then be translated to:
entity.related(’in_conf’, ’object’)
Additionnaly this benefits from the fetch_attrs policy (seeLoaded attributes and default sorting management) eventu-ally defined on the class element, which says which attributes must be also loaded when the entity is loaded through the orm.
3.5.4 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 class cubicweb.rset.ResultSet(results, rql, args=None, description=None, rqlst=None)
A result set wraps a RQL query result. This object implements partially the list protocol to allow direct use as a list of result rows.
Parameters
• rowcount (int) – number of rows in the result
• rows (list) – list of rows of result
• description (list) – result’s description, using the same structure as the result itself
• rql (str or unicode) – the original RQL query string column_types(*args, **kwargs)
return the list of different types in the column with the given col Parameters col (int) – the index of the desired column Return type list
Returns the different entities type found in the column complete_entity(row, col=0, skip_bytes=True)
short cut to get an completed entity instance for a particular row (all instance’s attributes have been fetched) description_struct(*args, **kwargs)
return a list describing sequence of results with the same description, e.g. : [[0, 4, (‘Bug’,)] [[0, 4, (‘Bug’,), [5, 8, (‘Story’,)] [[0, 3, (‘Project’, ‘Version’,)]]
entities(col=0)
iter on entities with eid in the col column of the result set filtered_rset(filtercb, col=0)
filter the result set according to a given filtercb Parameters
• filtercb (callable(entity)) – a callable which should take an entity as argument and return False if it should be skipped, else True
• col (int) – the column index Return type ResultSet
get_entity(*args, **kwargs)
convenience method for query retrieving a single entity, returns a partially initialized Entity instance.
Warning: Due to the cache wrapping this function, you should NEVER give row as a named param-eter (i.e. rset.get_entity(0, 1) is OK but rset.get_entity(row=0, col=1) isn’t)
Parameters row,col (int, int) – row and col numbers localizing the entity among the result’s table
Returns the partially initialized Entity instance
iter_rows_with_entities()
iterates over rows, and for each row eids are converted to plain entities limit(limit, offset=0, inplace=False)
limit the result set to the given number of rows optionaly starting from an index different than 0 Parameters
• limit (int) – the maximum number of results
• offset (int) – the offset index
• inplace (bool) – if true, the result set is modified in place, else a new result set is returned and the original is left unmodified
Return type ResultSet limited_rql()
returns a printable rql for the result set associated to the object, with limit/offset correctly set according to maximum page size and currently displayed page when necessary
one(col=0)
Retrieve exactly one entity from the query.
If the result set is empty, raises NoResultError. If the result set has more than one row, raises MultipleResultsError.
Parameters col (int) – The column localising the entity in the unique row Returns the partially initialized Entity instance
printable_rql(encoded=False)
return the result set’s origin rql as a string, with arguments substitued related_entity(*args, **kwargs)
given an cell of the result set, try to return a (entity, relation name) tuple to which this cell is linked.
This is especially useful when the cell is an attribute of an entity, to get the entity to which this attribute belongs to.
searched_text(*args, **kwargs)
returns the searched text in case of full-text search
Returns searched text or None if the query is not a full-text query sorted_rset(keyfunc, reverse=False, col=0)
sorts the result set according to a given keyfunc Parameters
• keyfunc (callable(entity)) – a callable which should take an entity as argument and return the value used to compare and sort
• reverse (bool) – if the result should be reversed
• col (int) – the column index. if col = -1, the whole row are used Return type ResultSet
split_rset(keyfunc=None, col=0, return_dict=False)
splits the result set in multiple result sets according to a given key Parameters
• keyfunc (callable(entity or FinalType)) – a callable which should take a value of the rset in argument and return the value used to group the value. If not define, raw value of the specified columns is used.
• col (int) – the column index. if col = -1, the whole row are used
• return_dict (Boolean) – If true, the function return a mapping (key -> rset) instead of a list of rset
Return type List of ResultSet or mapping of ResultSet syntax_tree(*args, **kwargs)
return the syntax tree (rql.stmts.Union) for the originating query. You can expect it to have solutions computed and it will be properly annotated.
transformed_rset(transformcb)
the result set according to a given column types Parameters
• transformcb – a callable which should take a row and its type description as parameters, and return the transformed row and type description.
• col (int) – the column index Return type ResultSet
3.5.5 The Cursor and Connection API
The whole cursor API is developped below.
Note: In practice you’ll usually use the .execute method on the _cw object of appobjects. Usage of other methods is quite rare.
3.5.6 Request and ResultSet methods
Those are methods you’ll find on both request objects and on repository session.
Request methods
URL handling:
• build_url(*args, **kwargs), returns an absolute URL based on the given arguments. The controller supposed to handle the response, can be specified through the first positional parameter (the connection is theoretically done automatically :).
Data formatting:
• format_date(date, date_format=None, time=False) returns a string for a date time according to instance’s con-figuration
• format_time(time) returns a string for a date time according to instance’s configuration And more...:
• tal_render(template, variables), renders a precompiled page template with variables in the given dictionary as context
Result set methods
• get_entity(row, col), returns the entity corresponding to the data position in the result set
• complete_entity(row, col, skip_bytes=True), is equivalent to get_entity but also call the method complete() on the entity before returning it