source: trunk/docs/contents/pg/query.rst @ 901

Last change on this file since 901 was 901, checked in by cito, 3 years ago

Improve creation of named tuples in Python 2.6 and 3.0

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