diff --git a/doc/connection.rst b/doc/connection.rst index 67f5a0c7..a6a1dcc7 100644 --- a/doc/connection.rst +++ b/doc/connection.rst @@ -26,6 +26,10 @@ The ``connection`` class cursors. The class returned should be a subclass of :class:`extensions.cursor`. See :ref:`subclassing-cursor` for details. + .. extension:: + + The :obj:`name` and :obj:`cursor_factory` parameters are Psycopg + extensions to the DB API. .. index:: pair: Transaction; Commit @@ -59,15 +63,28 @@ The ``connection`` class selected: see :meth:`connection.set_isolation_level()`). - The above methods are the only ones defined by the |DBAPI|_ protocol. - The Psycopg connection objects exports the following additional methods - and attributes. + .. index:: + single: Exceptions; In the connection class + + .. rubric:: Excetptions as connection class attributes + + The :class:`connection` also exposes the same `Error` classes available in + the :mod:`psycopg2` module as attributes. + + + .. extension:: + + The above methods are the only ones defined by the |DBAPI|_ protocol. + The Psycopg connection objects exports the following additional + methods and attributes. + .. attribute:: closed Read-only attribute reporting whether the database connection is open (0) or closed (1). + .. attribute:: dsn Read-only string containing the connection string used by the @@ -254,9 +271,3 @@ The ``connection`` class .. todo:: describe string_types - .. index:: - single: Exceptions; In the connection class - - The :class:`connection` also exposes the same `Error` classes available in - the :mod:`psycopg2` module as attributes. - diff --git a/doc/cursor.rst b/doc/cursor.rst index e5c49b63..bb43de86 100644 --- a/doc/cursor.rst +++ b/doc/cursor.rst @@ -47,6 +47,7 @@ The ``cursor`` class The type_code can be interpreted by comparing it to the Type Objects specified in the section :ref:`type-objects-and-constructors`. + .. method:: close() Close the cursor now (rather than whenever ``__del__`` is called). @@ -59,21 +60,37 @@ The ``cursor`` class Read-only boolean attribute: specifies if the cursor is closed (``True``) or not (``False``). + .. extension:: + + The :attr:`closed` attribute is a Psycopg extension to the + |DBAPI|. + + .. attribute:: connection Read-only attribute returning a reference to the :class:`connection` object on which the cursor was created. + .. attribute:: name Read-only attribute containing the name of the cursor if it was creates as named cursor by :meth:`connection.cursor`, or ``None`` if it is a client side cursor. See :ref:`server-side-cursors`. + .. extension:: + + The :attr:`name` attribute is a Psycopg extension to the |DBAPI|. + + + .. |execute*| replace:: :obj:`execute*()` .. _execute*: + .. rubric:: Commands execution methods + + .. method:: execute(operation [, parameters] [, async]) Prepare and execute a database operation (query or command). @@ -100,11 +117,21 @@ The ``cursor`` class ready for return via |fetch*|_ methods. See :ref:`asynchronous-queries`. + .. extension:: + + The :obj:`async` parameter is a Psycopg extension to the |DBAPI|. + + .. method:: mogrify(operation [, parameters) Return a query string after arguments binding. The string returned is exactly the one that would be sent to the database running the :meth:`execute()` method or similar. + + .. extension:: + + The :meth:`mogrify` method is a Psycopg extension to the |DBAPI|. + .. method:: executemany(operation, seq_of_parameters) @@ -118,6 +145,7 @@ The ``cursor`` class Parameters are bounded to the query using the same rules described in the :meth:`execute()` method. + .. method:: callproc(procname [, parameters] [, async]) Call a stored database procedure with the given name. The sequence of @@ -135,42 +163,25 @@ The ``cursor`` class ready for return via |fetch*|_ methods. See :ref:`asynchronous-queries`. - .. attribute:: query + .. extension:: - Read-only attribute containing the body of the last query sent to the - backend (including bound arguments). ``None`` if no query has been - executed yet:: + The :obj:`async` parameter is a Psycopg extension to the |DBAPI|. - >>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar')) - >>> cur.query - "INSERT INTO test (num, data) VALUES (42, E'bar')" - .. attribute:: statusmessage + .. method:: setinputsizes(sizes) + + This method is exported in compliance with the |DBAPI|. It currently + does nothing but it is safe to call it. - Return the message returned by the last command:: - - >>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar')) - >>> cur.statusmessage - 'INSERT 0 1' - - .. method:: isready() - - Return ``False`` if the backend is still processing an asynchronous - query or ``True`` if data is ready to be fetched by one of the - |fetch*|_ methods. See :ref:`asynchronous-queries`. - - .. method:: fileno() - - Return the file descriptor associated with the current connection and - make possible to use a cursor in a context where a file object would - be expected (like in a :func:`select()` call). See - :ref:`asynchronous-queries`. .. |fetch*| replace:: :obj:`fetch*()` .. _fetch*: + .. rubric:: Results retrieval methods + + The following methods are used to read data from the database after an :meth:`execute()` call. @@ -188,6 +199,7 @@ The ``cursor`` class (2, None, 'dada') (4, 42, 'bar') + .. method:: fetchone() Fetch the next row of a query result set, returning a single tuple, @@ -201,6 +213,7 @@ The ``cursor`` class to |execute*|_ did not produce any result set or no call was issued yet. + .. method:: fetchmany([size=cursor.arraysize]) Fetch the next set of rows of a query result, returning a list of @@ -231,6 +244,7 @@ The ``cursor`` class is best for it to retain the same value from one :meth:`fetchmany()` call to the next. + .. method:: fetchall() Fetch all (remaining) rows of a query result, returning them as a list @@ -247,6 +261,7 @@ The ``cursor`` class to |execute*|_ did not produce any result set or no call was issued yet. + .. method:: scroll(value[,mode='relative']) Scroll the cursor in the result set to a new position according @@ -265,6 +280,7 @@ The ``cursor`` class The method can be used both for client-side cursors and server-side (named) cursors. + .. attribute:: arraysize This read/write attribute specifies the number of rows to fetch at a @@ -279,6 +295,7 @@ The ``cursor`` class .. todo:: copied from DB API: better specify what psycopg2 does with arraysize + .. attribute:: rowcount This read-only attribute specifies the number of rows that the last @@ -293,7 +310,8 @@ The ``cursor`` class The |DBAPI|_ interface reserves to redefine the latter case to have the object return ``None`` instead of -1 in future versions of the specification. - + + .. attribute:: rownumber This read-only attribute provides the current 0-based index of the @@ -304,6 +322,7 @@ The ``cursor`` class set). The next fetch operation will fetch the row indexed by :attr:`rownumber` in that sequence. + .. index:: oid .. attribute:: lastrowid @@ -330,15 +349,72 @@ The ``cursor`` class This method is not supported (PostgreSQL does not have multiple data sets) and will raise a :exc:`NotSupportedError` exception. - .. method:: setinputsizes(sizes) - - This method currently does nothing but it is safe to call it. .. method:: setoutputsize(size [, column]) - This method currently does nothing but it is safe to call it. + This method is exported in compliance with the |DBAPI|. It currently + does nothing but it is safe to call it. + .. attribute:: query + + Read-only attribute containing the body of the last query sent to the + backend (including bound arguments). ``None`` if no query has been + executed yet:: + + >>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar')) + >>> cur.query + "INSERT INTO test (num, data) VALUES (42, E'bar')" + + .. extension:: + + The :attr:`query` attribute is a Psycopg extension to the |DBAPI|. + + + .. attribute:: statusmessage + + Return the message returned by the last command:: + + >>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar')) + >>> cur.statusmessage + 'INSERT 0 1' + + .. extension:: + + The :attr:`statusmessage` attribute is a Psycopg extension to the + |DBAPI|. + + + .. method:: isready() + + Return ``False`` if the backend is still processing an asynchronous + query or ``True`` if data is ready to be fetched by one of the + |fetch*|_ methods. See :ref:`asynchronous-queries`. + + .. extension:: + + The :meth:`isready` method is a Psycopg extension to the |DBAPI|. + + + .. method:: fileno() + + Return the file descriptor associated with the current connection and + make possible to use a cursor in a context where a file object would + be expected (like in a :func:`select()` call). See + :ref:`asynchronous-queries`. + + .. extension:: + + The :meth:`isready` method is a Psycopg extension to the |DBAPI|. + + + + .. rubric:: COPY-related methods + + .. extension:: + + The ``COPY`` support is a Psycopg extension to the |DBAPI|. + .. method:: copy_from(file, table, sep='\\t', null='\\N', columns=None) Read data *from* the file-like object :obj:`file` appending them to @@ -361,6 +437,7 @@ The ``cursor`` class .. versionchanged:: 2.0.6 added the :obj:`columns` parameter. + .. method:: copy_to(file, table, sep='\\t', null='\\N', columns=None) Write the content of the table named :obj:`table` *to* the file-like object :obj:`file`. :obj:`file` must have a ``write()`` method. See @@ -380,6 +457,7 @@ The ``cursor`` class .. versionchanged:: 2.0.6 added the :obj:`columns` parameter. + .. method:: copy_expert(sql, file [, size]) Submit a user-composed ``COPY`` statement. The method is useful to @@ -401,6 +479,9 @@ The ``cursor`` class .. versionadded:: 2.0.6 + + .. rubric:: Stuff to put elsewhere... + .. attribute:: row_factory .. todo:: cursor.row_factory diff --git a/doc/module.rst b/doc/module.rst index f3a398ad..a4ef75b4 100644 --- a/doc/module.rst +++ b/doc/module.rst @@ -45,6 +45,12 @@ The module interface respects the standard defined in the |DBAPI|_. taking a :obj:`dsn` argument. See :ref:`subclassing-connection` for details. + .. extension:: + + The :obj:`connection_factory` parameter is a Psycopg extension to the + |DBAPI|. + + .. data:: apilevel String constant stating the supported DB API level. For :mod:`psycopg2` is @@ -71,12 +77,6 @@ Exceptions In compliance with the |DBAPI|, the module makes informations about errors available through the following exceptions: -.. todo:: - There are actually a couple of extra extensions defined in _psycopg and - imported in the connection, but not in this module: shouldn't be there - them too? - - .. exception:: Warning Exception raised for important warnings like data truncations while