Index: docs/contents/pg/large_objects.rst =================================================================== --- docs/contents/pg/large_objects.rst (revision 1017) +++ docs/contents/pg/large_objects.rst (working copy) @@ -5,23 +5,24 @@ .. class:: LargeObject -Objects that are instances of the class :class:`LargeObject` are used to handle +Instances of the :class:`LargeObject` class handle all the requests concerning a PostgreSQL large object. These objects embed -and hide all the "recurrent" variables (object OID and connection), exactly +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 but dereferencing the +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. +`large object interface +<https://www.postgresql.org/docs/current/largeobjects.html>`_. + open -- open a large object --------------------------- @@ -34,8 +35,8 @@ :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 +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 +51,7 @@ :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,7 +61,7 @@ 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, @@ -68,7 +69,7 @@ :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 +This function allows reading data from a large object, starting at the current position. .. method:: LargeObject.write(string) @@ -80,7 +81,7 @@ :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,7 +96,7 @@ 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. +This method updates the position offset of 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`). @@ -109,7 +110,7 @@ :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 in the large object. .. method:: LargeObject.unlink() @@ -135,7 +136,7 @@ :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 +153,14 @@ 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 in a very simple +way. The exported file is created on the host running the PyGreSQL client +library, not 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 @@ -176,8 +177,8 @@ .. 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 + 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 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.
_______________________________________________ PyGreSQL mailing list PyGreSQL@Vex.Net https://mail.vex.net/mailman/listinfo/pygresql
