# LargeObject – Large Objects

class pg.LargeObject

Instances of the 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 `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 through with its parameters. Any modification other than 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 error. The exact error message is provided by the object’s `error` attribute.

See also the PostgreSQL documentation 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 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 `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 a similar manner as 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) – maximum 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 reading data from a large object, starting at the current position.

LargeObject.write(string)

  Write data to large object

  Parameters:

    data (bytes) – buffer of bytes 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 writing data to a large object, starting at the 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 updates the position offset 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 returns the current position offset 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 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.

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

`LargeObject` objects define a read-only set of attributes exposing 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 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 `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.