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.