pglarge – Large Objects¶
-
class
pg.
pglarge
¶
Objects that are instances of the class pglarge
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 pgobject
instances do, thus only keeping significant
parameters in function calls. The pglarge
object keeps a reference
to the pgobject
used for its creation, sending requests though with
its parameters. Any modification but dereferencing the pgobject
will thus affect the pglarge
object. Dereferencing the initial
pgobject
is not a problem since Python won’t deallocate it before
the pglarge
object 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¶
-
pglarge.
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¶
-
pglarge.
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¶
-
pglarge.
read
(size)¶ Read data from large object
Parameters: size (int) – maximal size of the buffer to be read
Returns: the read buffer
Return type: str
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.
-
pglarge.
write
(string)¶ Read data to large object
Parameters: string (str) – 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.
-
pglarge.
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
).
-
pglarge.
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.
-
pglarge.
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¶
-
pglarge.
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¶
-
pglarge.
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¶
pglarge
objects define a read-only set of attributes that allow
to get some information about it. These attributes are:
-
pglarge.
oid
¶ the OID associated with the object (int)
-
pglarge.
error
¶ the last warning/error message of the connection
Warning
In multi-threaded environments, pglarge.error
may be modified by
another thread using the same pgobject
. Remember these object
are shared, not duplicated. You should provide some locking to be able
if you want to check this. The pglarge.oid
attribute is very
interesting, because it allows you to reuse the OID later, creating the
pglarge
object with a pgobject.getlo()
method call.