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.