mirror of
https://github.com/psycopg/psycopg2.git
synced 2024-11-26 02:43:43 +03:00
Added documentation for database large objects.
This commit is contained in:
Daniele Varrazzo
parent
d08d9ab199
commit
9ba6102f66
|
|
@ -293,13 +293,23 @@ The ``connection`` class
|
|||
|
||||
.. method:: lobject([oid [, mode [, new_oid [, new_file [, lobject_factory]]]]])
|
||||
|
||||
Return a new database large object.
|
||||
Return a new database large object. See :ref:`large-objects` for an
|
||||
overview.
|
||||
|
||||
The ``lobject_factory`` argument can be used to create non-standard
|
||||
lobjects by passing a class different from the default. Note that the
|
||||
new class *should* be a sub-class of
|
||||
:class:`psycopg2.extensions.lobject`.
|
||||
:param oid: The OID of the object to read or write. 0 to create
|
||||
a new large object and and have its OID assigned automatically.
|
||||
:param mode: Access mode to the object: can be ``r``, ``w``,
|
||||
``rw`` or ``n`` (meaning don't open it).
|
||||
:param new_oid: Create a new object using the specified OID. The
|
||||
function raises :exc:`OperationalError` if the OID is already in
|
||||
use. Default is 0, meaning assign a new one automatically.
|
||||
:param new_file: The name of a file to be imported in the the database
|
||||
(using the |lo_import|_ function)
|
||||
:param lobject_factory: Subclass of
|
||||
:class:`~psycopg2.extensions.lobject` to be instantiated.
|
||||
:rtype: :obj:`~psycopg2.extensions.lobject`
|
||||
|
||||
.. todo:: conn.lobject details
|
||||
.. |lo_import| replace:: :func:`!lo_import`
|
||||
.. _lo_import: http://www.postgresql.org/docs/8.4/static/lo-interfaces.html#AEN36307
|
||||
|
||||
.. versionadded:: 2.0.8
|
||||
|
|
|
|||
|
|
@ -421,6 +421,16 @@ The ``cursor`` class
|
|||
The :meth:`fileno` method is a Psycopg extension to the |DBAPI|.
|
||||
|
||||
|
||||
.. attribute:: tzinfo_factory
|
||||
|
||||
The time zone factory used to handle data types such as
|
||||
:sql:`TIMESTAMP WITH TIME ZONE`. It should be a |tzinfo|_ object.
|
||||
See also the :mod:`psycopg2.tz` module.
|
||||
|
||||
.. |tzinfo| replace:: :class:`!tzinfo`
|
||||
.. _tzinfo: http://docs.python.org/library/datetime.html#tzinfo-objects
|
||||
|
||||
|
||||
|
||||
.. rubric:: COPY-related methods
|
||||
|
||||
|
|
@ -498,12 +508,3 @@ The ``cursor`` class
|
|||
|
||||
.. versionadded:: 2.0.6
|
||||
|
||||
|
||||
.. attribute:: tzinfo_factory
|
||||
|
||||
The time zone factory used to handle data types such as
|
||||
:sql:`TIMESTAMP WITH TIME ZONE`. It should be a |tzinfo|_ object.
|
||||
See also the :mod:`psycopg2.tz` module.
|
||||
|
||||
.. |tzinfo| replace:: :class:`!tzinfo`
|
||||
.. _tzinfo: http://docs.python.org/library/datetime.html#tzinfo-objects
|
||||
|
|
|
|||
|
|
@ -34,12 +34,64 @@ functionalities defined by the |DBAPI|_.
|
|||
|
||||
For a complete description of the class, see :class:`cursor`.
|
||||
|
||||
.. class:: lobject
|
||||
.. class:: lobject(conn [, oid [, mode [, new_oid [, new_file ]]]])
|
||||
|
||||
.. todo:: class lobject
|
||||
Wrapper for a PostgreSQL large object. See :ref:`large-objects` for an
|
||||
overview.
|
||||
|
||||
The class can be subclassed: see the :meth:`connection.lobject` to know
|
||||
how to specify a :class:`!lobject` subclass.
|
||||
|
||||
.. versionadded:: 2.0.8
|
||||
|
||||
.. attribute:: oid
|
||||
|
||||
Database OID of the object.
|
||||
|
||||
.. attribute:: mode
|
||||
|
||||
The mode the database was open (``r``, ``w``, ``rw`` or ``n``).
|
||||
|
||||
.. method:: read(bytes=-1)
|
||||
|
||||
Read a chunk of data from the current file position. If -1 (default)
|
||||
read all the remaining data.
|
||||
|
||||
.. method:: write(str)
|
||||
|
||||
Write a string to the large object. Return the number of bytes
|
||||
written.
|
||||
|
||||
.. method:: export(file_name)
|
||||
|
||||
Export the large object content to the file system.
|
||||
|
||||
The method uses the efficient |lo_export|_ libpq function.
|
||||
|
||||
.. |lo_export| replace:: :func:`!lo_export`
|
||||
.. _lo_export: http://www.postgresql.org/docs/8.4/static/lo-interfaces.html#AEN36330
|
||||
|
||||
.. method:: seek(offset, whence=0)
|
||||
|
||||
Set the lobject current position.
|
||||
|
||||
.. method:: tell()
|
||||
|
||||
Return the lobject current position.
|
||||
|
||||
.. method:: close()
|
||||
|
||||
Close the object.
|
||||
|
||||
.. attribute:: closed
|
||||
|
||||
Boolean attribute specifying if the object is closed.
|
||||
|
||||
.. method:: unlink()
|
||||
|
||||
Close the object and remove it from the database.
|
||||
|
||||
|
||||
|
||||
.. _sql-adaptation-objects:
|
||||
|
||||
|
|
|
|||
|
|
@ -63,37 +63,6 @@ The main entry point of Psycopg are:
|
|||
|
||||
|
||||
|
||||
.. index:: Transaction, Begin, Commit, Rollback, Autocommit
|
||||
|
||||
.. _transactions-control:
|
||||
|
||||
Transactions control
|
||||
--------------------
|
||||
|
||||
In Psycopg transactions are handled by the :class:`connection` class. By
|
||||
default, every time a command is sent to the database (using one of the
|
||||
:class:`cursor`\ s created by the connection), a new transaction is created.
|
||||
The following database commands will be executed in the context of the same
|
||||
transaction -- not only the commands issued by the first cursor, but the ones
|
||||
issued by all the cursors created by the same connection. Should any command
|
||||
fail, the transaction will be aborted and no further command will be executed
|
||||
until a call to the :meth:`connection.rollback` method.
|
||||
|
||||
The connection is responsible to terminate its transaction, calling either the
|
||||
:meth:`~connection.commit` or :meth:`~connection.rollback` method. Committed
|
||||
changes are immediately made persistent into the database. Closing the
|
||||
connection using the :meth:`~connection.close` method or destroying the
|
||||
connection object (calling :meth:`!__del__` or letting it fall out of scope)
|
||||
will result in an implicit :meth:`!rollback` call.
|
||||
|
||||
It is possible to set the connection in *autocommit* mode: this way all the
|
||||
commands executed will be immediately committed and no rollback is possible. A
|
||||
few commands (e.g. :sql:`CREATE DATABASE`) require to be run outside any
|
||||
transaction: in order to be able to run these commands from Psycopg, the
|
||||
session must be in autocommit mode. Read the documentation for
|
||||
:meth:`connection.set_isolation_level` to know how to change the commit mode.
|
||||
|
||||
|
||||
.. index::
|
||||
pair: Query; Parameters
|
||||
|
||||
|
|
@ -397,6 +366,38 @@ the connection or globally: see the function
|
|||
|
||||
|
||||
|
||||
.. index:: Transaction, Begin, Commit, Rollback, Autocommit
|
||||
|
||||
.. _transactions-control:
|
||||
|
||||
Transactions control
|
||||
--------------------
|
||||
|
||||
In Psycopg transactions are handled by the :class:`connection` class. By
|
||||
default, every time a command is sent to the database (using one of the
|
||||
:class:`cursor`\ s created by the connection), a new transaction is created.
|
||||
The following database commands will be executed in the context of the same
|
||||
transaction -- not only the commands issued by the first cursor, but the ones
|
||||
issued by all the cursors created by the same connection. Should any command
|
||||
fail, the transaction will be aborted and no further command will be executed
|
||||
until a call to the :meth:`connection.rollback` method.
|
||||
|
||||
The connection is responsible to terminate its transaction, calling either the
|
||||
:meth:`~connection.commit` or :meth:`~connection.rollback` method. Committed
|
||||
changes are immediately made persistent into the database. Closing the
|
||||
connection using the :meth:`~connection.close` method or destroying the
|
||||
connection object (calling :meth:`!__del__` or letting it fall out of scope)
|
||||
will result in an implicit :meth:`!rollback` call.
|
||||
|
||||
It is possible to set the connection in *autocommit* mode: this way all the
|
||||
commands executed will be immediately committed and no rollback is possible. A
|
||||
few commands (e.g. :sql:`CREATE DATABASE`) require to be run outside any
|
||||
transaction: in order to be able to run these commands from Psycopg, the
|
||||
session must be in autocommit mode. Read the documentation for
|
||||
:meth:`connection.set_isolation_level` to know how to change the commit mode.
|
||||
|
||||
|
||||
|
||||
.. index::
|
||||
pair: Server side; Cursor
|
||||
pair: Named; Cursor
|
||||
|
|
@ -480,3 +481,30 @@ examples.
|
|||
.. __: http://www.postgresql.org/docs/8.4/static/sql-copy.html
|
||||
|
||||
|
||||
|
||||
.. index::
|
||||
single: Large objects
|
||||
|
||||
.. _large-objects:
|
||||
|
||||
Access to PostgreSQL large objects
|
||||
----------------------------------
|
||||
|
||||
PostgreSQL offers support to `large objects`__, which provide stream-style
|
||||
access to user data that is stored in a special large-object structure. They
|
||||
are useful with data values too large to be manipulated conveniently as a
|
||||
whole.
|
||||
|
||||
.. __: http://www.postgresql.org/docs/8.4/static/largeobjects.html
|
||||
|
||||
Psycopg allows access to the large object using the
|
||||
:class:`~psycopg2.extensions.lobject` class. Objects are generated using the
|
||||
:meth:`connection.lobject` factory method.
|
||||
|
||||
Psycopg large object support efficient import/export with file system files
|
||||
using the |lo_import|_ and |lo_export|_ libpq functions.
|
||||
|
||||
.. |lo_import| replace:: :func:`!lo_import`
|
||||
.. _lo_import: http://www.postgresql.org/docs/8.4/static/lo-interfaces.html#AEN36307
|
||||
.. |lo_export| replace:: :func:`!lo_export`
|
||||
.. _lo_export: http://www.postgresql.org/docs/8.4/static/lo-interfaces.html#AEN36330
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user