equal
deleted
inserted
replaced
1 .. _dbapi: |
1 .. _dbapi: |
2 |
2 |
3 API Python/RQL |
3 Python/RQL API |
4 ~~~~~~~~~~~~~~ |
4 ~~~~~~~~~~~~~~ |
5 |
5 |
6 The Python API developped to interface with RQL is inspired from the standard db-api, |
6 The Python API developped to interface with RQL is inspired from the standard db-api, |
7 with a Connection object having the methods cursor, rollback and commit essentially. |
7 with a Connection object having the methods cursor, rollback and commit essentially. |
8 The most important method is the `execute` method of a cursor. |
8 The most important method is the `execute` method of a cursor. |
9 |
9 |
10 .. sourcecode:: python |
10 .. sourcecode:: python |
11 |
11 |
12 execute(rqlstring, args=None, cachekey=None, build_descr=True) |
12 execute(rqlstring, args=None, build_descr=True) |
13 |
13 |
14 :rqlstring: the RQL query to execute (unicode) |
14 :rqlstring: the RQL query to execute (unicode) |
15 :args: if the query contains substitutions, a dictionary containing the values to use |
15 :args: if the query contains substitutions, a dictionary containing the values to use |
16 |
16 |
17 The `Connection` object owns the methods `commit` and `rollback`. You |
17 The `Connection` object owns the methods `commit` and `rollback`. You |
19 interface based on the *CubicWeb* framework as it determines the end |
19 interface based on the *CubicWeb* framework as it determines the end |
20 of the transaction depending on the query execution success. They are |
20 of the transaction depending on the query execution success. They are |
21 however useful in other contexts such as tests or custom controllers. |
21 however useful in other contexts such as tests or custom controllers. |
22 |
22 |
23 .. note:: |
23 .. note:: |
|
24 |
24 While executing update queries (SET, INSERT, DELETE), if a query generates |
25 While executing update queries (SET, INSERT, DELETE), if a query generates |
25 an error related to security, a rollback is automatically done on the current |
26 an error related to security, a rollback is automatically done on the current |
26 transaction. |
27 transaction. |
27 |
28 |
28 Executing RQL queries from a view or a hook |
29 Executing RQL queries from a view or a hook |
77 :ref:`FetchAttrs`) eventually defined on the class element, which says |
78 :ref:`FetchAttrs`) eventually defined on the class element, which says |
78 which attributes must be also loaded when the entity is loaded through |
79 which attributes must be also loaded when the entity is loaded through |
79 the orm. |
80 the orm. |
80 |
81 |
81 |
82 |
|
83 The `ResultSet` API |
|
84 ~~~~~~~~~~~~~~~~~~~ |
|
85 |
|
86 ResultSet instances are a very commonly manipulated object. They have |
|
87 a rich API as seen below, but we would like to highlight a bunch of |
|
88 methods that are quite useful in day-to-day practice: |
|
89 |
|
90 * `__str__()` (applied by `print`) gives a very useful overview of both |
|
91 the underlying RQL expression and the data inside; unavoidable for |
|
92 debugging purposes |
|
93 |
|
94 * `printable_rql()` produces back a well formed RQL expression as a |
|
95 string; it is very useful to build views |
|
96 |
|
97 * `entities()` returns a generator on all entities of the result set |
|
98 |
|
99 * `get_entity(row, col)` gets the entity at row, col coordinates; one |
|
100 of the most used result set method |
|
101 |
|
102 .. autoclass:: cubicweb.rset.ResultSet |
|
103 :members: |
|
104 |
|
105 |
82 The `Cursor` API |
106 The `Cursor` API |
83 ~~~~~~~~~~~~~~~~ |
107 ~~~~~~~~~~~~~~~~ |
84 |
108 |
85 The whole cursor API is developped below. |
109 The whole cursor API is developped below. |
86 |
110 |
|
111 .. note: |
|
112 |
|
113 In practice we use the `.execute` method on the _cw object of |
|
114 appobjects. Usage of other methods is quite rare. |
|
115 |
87 .. autoclass:: cubicweb.dbapi.Cursor |
116 .. autoclass:: cubicweb.dbapi.Cursor |
88 :members: |
117 :members: |