source: branches/4.x/docs/contents/pg/query.rst @ 695

Last change on this file since 695 was 695, checked in by cito, 4 years ago

Reorganize and improve the Sphinx docs

The Sphinx HTML docs can now also serve as home page for the project.
They can be built with the mkdocs script and can then be found in the
docs/_build/html directory (this needs sphinx and the cloud_sptheme).

The "actual" core docs can be found in docs/contents. The layout has
been modified to only show these pages with the typical documentation
relbars; the other pages of the homepage use a simpler layout. The
pg and pgdb documentation has been cut in chunks and can now be found
in docs/contents/pg and docs/contents/pgdb.

File size: 3.6 KB
Line 
1pgqueryobject methods
2=====================
3
4.. class:: pgqueryobject
5
6The :class:`pgqueryobject` returned by :meth:`pgobject.query` and
7:meth:`DB.query` provides the following methods for accessing
8the results of the query:
9
10getresult -- get query values as list of tuples
11-----------------------------------------------
12
13.. method:: pgqueryobject.getresult()
14
15    Get query values as list of tuples
16
17    :returns: result values as a list of tuples
18    :rtype: list
19    :raises TypeError: too many (any) parameters
20    :raises MemoryError: internal memory error
21
22This method returns the list of the values returned by the query.
23More information about this result may be accessed using
24:meth:`pgqueryobject.listfields`, :meth:`pgqueryobject.fieldname`
25and :meth:`pgqueryobject.fieldnum` methods.
26
27dictresult -- get query values as list of dictionaries
28------------------------------------------------------
29
30.. method:: pgqueryobject.dictresult()
31
32    Get query values as list of dictionaries
33
34    :returns: result values as a list of dictionaries
35    :rtype: list
36    :raises TypeError: too many (any) parameters
37    :raises MemoryError: internal memory error
38
39This method returns the list of the values returned by the query
40with each tuple returned as a dictionary with the field names
41used as the dictionary index.
42
43namedresult -- get query values as list of named tuples
44-------------------------------------------------------
45
46.. method:: pgqueryobject.namedresult()
47
48    Get query values as list of named tuples
49
50    :returns: result values as a list of named tuples
51    :rtype: list
52    :raises TypeError: too many (any) parameters
53    :raises TypeError: named tuples not supported
54    :raises MemoryError: internal memory error
55
56This method returns the list of the values returned by the query
57with each row returned as a named tuple with proper field names.
58
59listfields -- list fields names of previous query result
60--------------------------------------------------------
61
62.. method:: pgqueryobject.listfields()
63
64    List fields names of previous query result
65
66    :returns: field names
67    :rtype: list
68    :raises TypeError: too many parameters
69
70This method returns the list of names of the fields defined for the
71query result. The fields are in the same order as the result values.
72
73fieldname, fieldnum -- field name/number conversion
74---------------------------------------------------
75
76.. method:: pgqueryobject.fieldname(num)
77
78    Get field name from its number
79
80    :param int num: field number
81    :returns: field name
82    :rtype: str
83    :raises TypeError: invalid connection, bad parameter type, or too many parameters
84    :raises ValueError: invalid field number
85
86This method allows to find a field name from its rank number. It can be
87useful for displaying a result. The fields are in the same order as the
88result values.
89
90.. method:: pgqueryobject.fieldnum(name)
91
92    Get field number from its name
93
94    :param str name: field name
95    :returns: field number
96    :rtype: int
97    :raises TypeError: invalid connection, bad parameter type, or too many parameters
98    :raises ValueError: unknown field name
99
100This method returns a field number from its name. It can be used to
101build a function that converts result list strings to their correct
102type, using a hardcoded table definition. The number returned is the
103field rank in the result values list.
104
105ntuples -- return number of tuples in query object
106--------------------------------------------------
107
108.. method:: pgqueryobject.ntuples()
109
110    Return number of tuples in query object
111
112    :returns: number of tuples in :class:`pgqueryobject`
113    :rtype: int
114    :raises TypeError: Too many arguments.
115
116This method returns the number of tuples found in a query.
Note: See TracBrowser for help on using the repository browser.