mirror of
https://github.com/psycopg/psycopg2.git
synced 2025-10-30 23:37:29 +03:00
Showing the points where Psycopg diverges from the DB API.
This commit is contained in:
Daniele Varrazzo
Federico Di Gregorio
parent
5417d7153d
commit
5cb07685ca
|
|
@ -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()`).
|
||||
|
||||
|
||||
.. 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.
|
||||
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.
|
||||
|
||||
|
|
|
|||
139
doc/cursor.rst
139
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,12 +117,22 @@ 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)
|
||||
|
||||
Prepare a database operation (query or command) and then execute it
|
||||
|
|
@ -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)
|
||||
|
||||
Return the message returned by the last command::
|
||||
This method is exported in compliance with the |DBAPI|. It currently
|
||||
does nothing but it is safe to call it.
|
||||
|
||||
>>> 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
|
||||
|
|
@ -294,6 +311,7 @@ The ``cursor`` class
|
|||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user