From 2cde9033acdcdea86da1c161e0aaec8f9bf441a9 Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Wed, 5 Jan 2011 00:05:29 +0000
Subject: [PATCH] Added documentation for Unicode support in large object

Not implemented yet!
---
 doc/src/connection.rst | 29 ++++++++++++++++++++++++-----
 doc/src/extensions.rst | 16 ++++++++++++++--
 doc/src/usage.rst      |  3 ++-
 3 files changed, 40 insertions(+), 8 deletions(-)

diff --git a/doc/src/connection.rst b/doc/src/connection.rst
index bf6a6f26..d0f5e1a9 100644
--- a/doc/src/connection.rst
+++ b/doc/src/connection.rst
@@ -490,13 +490,14 @@ The ``connection`` class
 
     .. method:: lobject([oid [, mode [, new_oid [, new_file [, lobject_factory]]]]])
 
-        Return a new database large object. See :ref:`large-objects` for an
-        overview.
+        Return a new database large object as a `~psycopg2.extensions.lobject`
+        instance.
+
+        See :ref:`large-objects` for an overview.
 
         :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 mode: Access mode to the object, see below.
         :param new_oid: Create a new object using the specified OID. The
             function raises `OperationalError` if the OID is already in
             use. Default is 0, meaning assign a new one automatically.
@@ -504,13 +505,31 @@ The ``connection`` class
             (using the |lo_import|_ function)
         :param lobject_factory: Subclass of
             `~psycopg2.extensions.lobject` to be instantiated.
-        :rtype: `~psycopg2.extensions.lobject`
 
         .. |lo_import| replace:: `!lo_import()`
         .. _lo_import: http://www.postgresql.org/docs/9.0/static/lo-interfaces.html#LO-IMPORT
 
+        Available values for *mode* are:
+
+        ======= =========
+        *mode*  meaning
+        ======= =========
+        ``r``   Open for read only
+        ``w``   Open for write only
+        ``rw``  Open for read/write
+        ``n``   Don't open the file
+        ``b``   Don't decode read data (return data as `str` in Python 2 or `bytes` in Python 3)
+        ``t``   Decode read data according to `connection.encoding` (return data as `unicode` in Python 2 or `str` in Python 3)
+        ======= =========
+
+        ``b`` and ``t`` can be specified together with a read/write mode. If
+        neither ``b`` nor ``t`` is specified, the default is ``b`` in Python 2
+        and ``t`` in Python 3.
+
         .. versionadded:: 2.0.8
 
+        .. versionchanged:: 2.3.3 added ``b`` and ``t`` mode and unicode
+            support.
 
 
     .. rubric:: Methods related to asynchronous support.
diff --git a/doc/src/extensions.rst b/doc/src/extensions.rst
index 73b05db1..8fee890e 100644
--- a/doc/src/extensions.rst
+++ b/doc/src/extensions.rst
@@ -51,17 +51,29 @@ functionalities defined by the |DBAPI|_.
 
     .. attribute:: mode
 
-        The mode the database was open (``r``, ``w``, ``rw`` or ``n``).
+        The mode the database was open. See `connection.lobject()` for a
+        description of the available modes.
 
     .. method:: read(bytes=-1)
 
         Read a chunk of data from the current file position. If -1 (default)
         read all the remaining data.
 
+        The result is an Unicode string (decoded according to
+        `connection.encoding`) if the file was open in ``t`` mode, a bytes
+        string for ``b`` mode.
+
+        .. versionchanged:: 2.3.3
+            added Unicode support.
+
     .. method:: write(str)
 
         Write a string to the large object. Return the number of bytes
-        written.
+        written. Unicode strings are encoded in the `connection.encoding`
+        before writing.
+
+        .. versionchanged:: 2.3.3
+            added Unicode support.
 
     .. method:: export(file_name)
 
diff --git a/doc/src/usage.rst b/doc/src/usage.rst
index a5efaa45..36bd36be 100644
--- a/doc/src/usage.rst
+++ b/doc/src/usage.rst
@@ -574,7 +574,8 @@ whole.
 
 Psycopg allows access to the large object using the
 `~psycopg2.extensions.lobject` class. Objects are generated using the
-`connection.lobject()` factory method.
+`connection.lobject()` factory method. Data can be retrieved either as bytes
+or as Unicode strings.
 
 Psycopg large object support efficient import/export with file system files
 using the |lo_import|_ and |lo_export|_ libpq functions.