LargeObject – Large Objects — PyGreSQL 5.1

# LargeObject – Large Objects

class `pg.` `LargeObject`

Objects that are instances of the 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 `Connection` instances do, thus only keeping significant parameters in function calls. The `LargeObject` instance keeps a reference to the `Connection` object used for its creation, sending requests though with its parameters. Any modification but dereferencing the `Connection` object will thus affect the `LargeObject` instance. Dereferencing the initial `Connection` object is not a problem since Python won’t deallocate it before the `LargeObject` instance dereferences it. All functions return a generic error message on call error, whatever the exact error was. The `error` attribute of the object allows to get the exact error message.

See also the PostgreSQL programmer’s guide for more information about the large object interface.

## open – open a large object

`LargeObject.` `open`(mode)

  Open a large object

  Parameters: | mode (int) – open mode definition
  Return type: | None
  Raises: | TypeError – invalid connection, bad parameter type, or too many parameters 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 `pg` module (`INV_READ`, `INV_WRITE`).

## close – close a large object

`LargeObject.` `close`()

  Close a large object

  Return type: | None
  Raises: | TypeError – invalid connection TypeError – too many parameters IOError – object is not opened, or close error

This method closes a previously opened large object, in the same way than the Unix close() function.

## read, write, tell, seek, unlink – file-like large object handling

`LargeObject.` `read`(size)

  Read data from large object

  Parameters: | size (int) – maximal size of the buffer to be read
  Returns: | the read buffer
  Return type: | bytes
  Raises: | TypeError – invalid connection, invalid object, bad parameter type, or too many parameters ValueError – if size is negative IOError – object is not opened, or read error

This function allows to read data from a large object, starting at current position.

`LargeObject.` `write`(string)

  Read data to large object

  Parameters: | string (bytes) – string buffer to be written
  Return type: | None
  Raises: | TypeError – invalid connection, bad parameter type, or too many parameters IOError – object is not opened, or write error

This function allows to write data to a large object, starting at current position.

`LargeObject.` `seek`(offset, whence)

  Change current position in large object

  Parameters: | offset (int) – position offset whence (int) – positional parameter
  Returns: | new position in object
  Return type: | int
  Raises: | TypeError – invalid connection or invalid object, bad parameter type, or too many parameters 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 `pg` module (`SEEK_SET`, `SEEK_CUR`, `SEEK_END`).

`LargeObject.` `tell`()

  Return current position in large object

  Returns: | current position in large object
  Return type: | int
  Raises: | TypeError – invalid connection or invalid object TypeError – too many parameters IOError – object is not opened, or seek error

This method allows to get the current position in the large object.

`LargeObject.` `unlink`()

  Delete large object

  Return type: | None
  Raises: | TypeError – invalid connection or invalid object TypeError – too many parameters IOError – object is not closed, or unlink error

This methods unlinks (deletes) the PostgreSQL large object.

## size – get the large object size

`LargeObject.` `size`()

  Return the large object size

  Returns: | the large object size
  Return type: | int
  Raises: | TypeError – invalid connection or invalid object TypeError – too many parameters IOError – object is not opened, or seek/tell error

This (composite) method allows to get 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.

## export – save a large object to a file

`LargeObject.` `export`(name)

  Export a large object to a file

  Parameters: | name (str) – file to be created
  Return type: | None
  Raises: | TypeError – invalid connection or invalid object, bad parameter type, or too many parameters 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.

## Object attributes

`LargeObject` objects define a read-only set of attributes that allow to get some information about it. These attributes are:

`LargeObject.` `oid`

  the OID associated with the large object (int)

`LargeObject.` `pgcnx`

  the `Connection` object associated with the large object

`LargeObject.` `error`

  the last warning/error message of the connection (str)

Warning

In multi-threaded environments, `LargeObject.error` may be modified by another thread using the same `Connection`. Remember these object are shared, not duplicated. You should provide some locking to be able if you want to check this. The `LargeObject.oid` attribute is very interesting, because it allows you to reuse the OID later, creating the `LargeObject` object with a `Connection.getlo()` method call.