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

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

Add full support for PostgreSQL array types

At the core of this patch is a fast parser for the peculiar syntax of
literal array expressions in PostgreSQL that was added to the C module.
This is not trivial, because PostgreSQL arrays can be multidimensional
and the syntax is different from Python and SQL expressions.

The Python pg and pgdb modules make use of this parser so that they can
return database columns containing PostgreSQL arrays to Python as lists.
Also added quoting methods that allow passing PostgreSQL arrays as lists
to insert()/update() and execute/executemany(). These methods are simpler
and were implemented in Python but needed support from the regex module.

The patch also adds makes getresult() in pg automatically return bytea
values in unescaped form as bytes strings. Before, it was necessary to
call unescape_bytea manually. The pgdb module did this already.

The patch includes some more refactorings and simplifications regarding
the quoting and casting in pg and pgdb.

Some references to antique PostgreSQL types that are not used any more
in the supported PostgreSQL versions have been removed.

Also added documentation and tests for the new features.

File size: 3.9 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
67Note that since PyGreSQL 5.0 this will return the values of array type
68columns as Python lists.
69
70.. versionadded:: 4.1
71
72listfields -- list fields names of previous query result
73--------------------------------------------------------
74
75.. method:: Query.listfields()
76
77    List fields names of previous query result
78
79    :returns: field names
80    :rtype: list
81    :raises TypeError: too many parameters
82
83This method returns the list of names of the fields defined for the
84query result. The fields are in the same order as the result values.
85
86fieldname, fieldnum -- field name/number conversion
87---------------------------------------------------
88
89.. method:: Query.fieldname(num)
90
91    Get field name from its number
92
93    :param int num: field number
94    :returns: field name
95    :rtype: str
96    :raises TypeError: invalid connection, bad parameter type, or too many parameters
97    :raises ValueError: invalid field number
98
99This method allows to find a field name from its rank number. It can be
100useful for displaying a result. The fields are in the same order as the
101result values.
102
103.. method:: Query.fieldnum(name)
104
105    Get field number from its name
106
107    :param str name: field name
108    :returns: field number
109    :rtype: int
110    :raises TypeError: invalid connection, bad parameter type, or too many parameters
111    :raises ValueError: unknown field name
112
113This method returns a field number from its name. It can be used to
114build a function that converts result list strings to their correct
115type, using a hardcoded table definition. The number returned is the
116field rank in the result values list.
117
118ntuples -- return number of tuples in query object
119--------------------------------------------------
120
121.. method:: Query.ntuples()
122
123    Return number of tuples in query object
124
125    :returns: number of tuples in :class:`Query`
126    :rtype: int
127    :raises TypeError: Too many arguments.
128
129This method returns the number of tuples found in a query.
Note: See TracBrowser for help on using the repository browser.