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.

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.