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.