Added documentation for database large objects.

doc/src/connection.rst

@@ -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
+        :param oid: The OID of the object to read or write. 0 to create
-        lobjects by passing a class different from the default. Note that the
+            a new large object and and have its OID assigned automatically.
-        new class *should* be a sub-class of
+        :param mode: Access mode to the object: can be ``r``, ``w``,
-        :class:`psycopg2.extensions.lobject`.
+            ``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

doc/src/cursor.rst

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

doc/src/extensions.rst

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

doc/src/usage.rst

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