Minor changes in the large objects documentation (#30)

docs/contents/changelog.rst

@@ -24,6 +24,9 @@ Version 5.2 (to be released)
       be passed on to the COPY command. Contributed by Justin Pryzby (#24).
     - The `DBTypes` class now also includes the `typlen` attribute with
       information about the size of the type (contributed by Justin Pryzby).
+    - Large objects on the server are not closed any more when they are
+      deallocated as Python objects, since this could cause several problems.
+      Bug report and analysis by Justin Pryzby (#30).
 
 - Changes to the DB-API 2 module (pgdb):
     - When using Python 2, errors are now derived from StandardError

docs/contents/pg/large_objects.rst

@@ -5,22 +5,23 @@ LargeObject -- Large Objects
 
 .. class:: LargeObject
 
-Objects that are instances of the class :class:`LargeObject` are used to handle
-all the requests concerning a PostgreSQL large object. These objects embed
-and hide all the "recurrent" variables (object OID and connection), exactly
-in the same way :class:`Connection` instances do, thus only keeping significant
-parameters in function calls. The :class:`LargeObject` instance keeps a
-reference to the :class:`Connection` object used for its creation, sending
-requests though with its parameters. Any modification but dereferencing the
+Instances of the class :class:`LargeObject` are used to handle all the
+requests concerning a PostgreSQL large object. These objects embed and hide
+all the recurring variables (object OID and connection), in the same way
+:class:`Connection` instances do, thus only keeping significant parameters
+in function calls. The :class:`LargeObject` instance keeps a reference to
+the :class:`Connection` object used for its creation, sending requests
+though with its parameters. Any modification other than dereferencing the
 :class:`Connection` object will thus affect the :class:`LargeObject` instance.
 Dereferencing the initial :class:`Connection` object is not a problem since
 Python won't deallocate it before the :class:`LargeObject` instance
-dereferences it. All functions return a generic error message on call error,
-whatever the exact error was. The :attr:`error` attribute of the object allows
-to get the exact error message.
+dereferences it. All functions return a generic error message on error.
+The exact error message is provided by the object's :attr:`error` attribute.
 
-See also the PostgreSQL programmer's guide for more information about the
-large object interface.
+See also the PostgreSQL documentation for more information about the
+`large object interface`__.
+
+__ https://www.postgresql.org/docs/current/largeobjects.html
 
 open -- open a large object
 ---------------------------
@@ -34,9 +35,10 @@ open -- open a large object
     :raises TypeError: invalid connection, bad parameter type, or too many parameters
     :raises IOError: already opened object, or open error
 
-This method opens a large object for reading/writing, in the same way than the
-Unix open() function. The mode value can be obtained by OR-ing the constants
-defined in the :mod:`pg` module (:const:`INV_READ`, :const:`INV_WRITE`).
+This method opens a large object for reading/writing, in a similar manner as
+the Unix open() function does for files. The mode value can be obtained by
+OR-ing the constants defined in the :mod:`pg` module (:const:`INV_READ`,
+:const:`INV_WRITE`).
 
 close -- close a large object
 -----------------------------
@@ -50,7 +52,7 @@ close -- close a large object
     :raises TypeError: too many parameters
     :raises IOError: object is not opened, or close error
 
-This method closes a previously opened large object, in the same way than
+This method closes a previously opened large object, in a similar manner as
 the Unix close() function.
 
 read, write, tell, seek, unlink -- file-like large object handling
@@ -60,16 +62,16 @@ read, write, tell, seek, unlink -- file-like large object handling
 
     Read data from large object
 
-    :param int size: maximal size of the buffer to be read
+    :param int size: maximum size of the buffer to be read
     :returns: the read buffer
     :rtype: bytes
     :raises TypeError: invalid connection, invalid object,
      bad parameter type, or too many parameters
     :raises ValueError: if `size` is negative
     :raises IOError: object is not opened, or read error
 
-This function allows to read data from a large object, starting at current
-position.
+This function allows reading data from a large object, starting at the
+current position.
 
 .. method:: LargeObject.write(string)
 
@@ -80,7 +82,7 @@ position.
     :raises TypeError: invalid connection, bad parameter type, or too many parameters
     :raises IOError: object is not opened, or write error
 
-This function allows to write data to a large object, starting at current
+This function allows writing data to a large object, starting at the current
 position.
 
 .. method:: LargeObject.seek(offset, whence)
@@ -95,9 +97,9 @@ position.
      bad parameter type, or too many parameters
     :raises IOError: object is not opened, or seek error
 
-This method allows to move the position cursor in the large object.
-The valid values for the whence parameter are defined as constants in the
-:mod:`pg` module (:const:`SEEK_SET`, :const:`SEEK_CUR`, :const:`SEEK_END`).
+This method updates the position offset in the large object. The valid values
+for the whence parameter are defined as constants in the :mod:`pg` module
+(:const:`SEEK_SET`, :const:`SEEK_CUR`, :const:`SEEK_END`).
 
 .. method:: LargeObject.tell()
 
@@ -109,7 +111,7 @@ The valid values for the whence parameter are defined as constants in the
     :raises TypeError: too many parameters
     :raises IOError: object is not opened, or seek error
 
-This method allows to get the current position in the large object.
+This method returns the current position offset in the large object.
 
 .. method:: LargeObject.unlink()
 
@@ -135,7 +137,7 @@ size -- get the large object size
     :raises TypeError: too many parameters
     :raises IOError: object is not opened, or seek/tell error
 
-This (composite) method allows to get the size of a large object. It was
+This (composite) method returns the size of a large object. It was
 implemented because this function is very useful for a web interfaced
 database. Currently, the large object needs to be opened first.
 
@@ -152,14 +154,14 @@ export -- save a large object to a file
      bad parameter type, or too many parameters
     :raises IOError: object is not closed, or export error
 
-This methods allows to dump the content of a large object in a very simple
-way. The exported file is created on the host of the program, not the
-server host.
+This methods allows saving the content of a large object to a file in a
+very simple way. The file is created on the host running the PyGreSQL
+interface, not on the server host.
 
 Object attributes
 -----------------
-:class:`LargeObject` objects define a read-only set of attributes that allow
-to get some information about it. These attributes are:
+:class:`LargeObject` objects define a read-only set of attributes exposing
+some information about it. These attributes are:
 
 .. attribute:: LargeObject.oid
 
@@ -175,9 +177,10 @@ to get some information about it. These attributes are:
 
 .. warning::
 
-    In multi-threaded environments, :attr:`LargeObject.error` may be modified by
-    another thread using the same :class:`Connection`. Remember these object
-    are shared, not duplicated. You should provide some locking to be able
-    if you want to check this. The :attr:`LargeObject.oid` attribute is very
+    In multi-threaded environments, :attr:`LargeObject.error` may be modified
+    by another thread using the same :class:`Connection`. Remember these
+    objects are shared, not duplicated. You should provide some locking if you
+    want to use this information in a program in which it's shared between
+    multiple threads. The :attr:`LargeObject.oid` attribute is very
     interesting, because it allows you to reuse the OID later, creating the
     :class:`LargeObject` object with a :meth:`Connection.getlo` method call.