psycopg/psycopg2
1
1
Fork 0
mirror of https://github.com/psycopg/psycopg2.git synced 2025-01-31 09:24:07 +03:00
Code Issues Packages Projects Releases Wiki Activity

Showing the points where Psycopg diverges from the DB API.

Browse Source
This commit is contained in:
Daniele Varrazzo 2010-02-09 23:09:48 +00:00 committed by Federico Di Gregorio
parent 5417d7153d
commit 5cb07685ca
3 changed files with 138 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
doc/connection.rst
View File

@ -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.

143
doc/cursor.rst
View File

@ -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

12
doc/module.rst
View File

@ -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