1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
LargeObject -- Large Objects
============================
.. py:currentmodule:: pg
.. class:: LargeObject
Objects that are instances of the class :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 :class:`Connection` instances do, thus only keeping significant
parameters in function calls. The :class:`LargeObject` instance keeps a
reference to the :class:`Connection` object used for its creation, sending
requests though with its parameters. Any modification but dereferencing the
:class:`Connection` object will thus affect the :class:`LargeObject` instance.
Dereferencing the initial :class:`Connection` object is not a problem since
Python won't deallocate it before the :class:`LargeObject` instance
dereferences it. All functions return a generic error message on call error,
whatever the exact error was. The :attr:`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
---------------------------
.. method:: LargeObject.open(mode)
Open a large object
:param int mode: open mode definition
:rtype: None
:raises TypeError: invalid connection, bad parameter type, or too many parameters
:raises 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 :mod:`pg` module (:const:`INV_READ`, :const:`INV_WRITE`).
close -- close a large object
-----------------------------
.. method:: LargeObject.close()
Close a large object
:rtype: None
:raises TypeError: invalid connection
:raises TypeError: too many parameters
:raises 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
------------------------------------------------------------------
.. method:: LargeObject.read(size)
Read data from large object
:param int size: maximal size of the buffer to be read
:returns: the read buffer
:rtype: bytes
:raises TypeError: invalid connection, invalid object,
bad parameter type, or too many parameters
:raises ValueError: if `size` is negative
:raises IOError: object is not opened, or read error
This function allows to read data from a large object, starting at current
position.
.. method:: LargeObject.write(string)
Read data to large object
:param bytes string: string buffer to be written
:rtype: None
:raises TypeError: invalid connection, bad parameter type, or too many parameters
:raises IOError: object is not opened, or write error
This function allows to write data to a large object, starting at current
position.
.. method:: LargeObject.seek(offset, whence)
Change current position in large object
:param int offset: position offset
:param int whence: positional parameter
:returns: new position in object
:rtype: int
:raises TypeError: invalid connection or invalid object,
bad parameter type, or too many parameters
:raises 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
:mod:`pg` module (:const:`SEEK_SET`, :const:`SEEK_CUR`, :const:`SEEK_END`).
.. method:: LargeObject.tell()
Return current position in large object
:returns: current position in large object
:rtype: int
:raises TypeError: invalid connection or invalid object
:raises TypeError: too many parameters
:raises IOError: object is not opened, or seek error
This method allows to get the current position in the large object.
.. method:: LargeObject.unlink()
Delete large object
:rtype: None
:raises TypeError: invalid connection or invalid object
:raises TypeError: too many parameters
:raises IOError: object is not closed, or unlink error
This methods unlinks (deletes) the PostgreSQL large object.
size -- get the large object size
---------------------------------
.. method:: LargeObject.size()
Return the large object size
:returns: the large object size
:rtype: int
:raises TypeError: invalid connection or invalid object
:raises TypeError: too many parameters
:raises 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
---------------------------------------
.. method:: LargeObject.export(name)
Export a large object to a file
:param str name: file to be created
:rtype: None
:raises TypeError: invalid connection or invalid object,
bad parameter type, or too many parameters
:raises 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
-----------------
:class:`LargeObject` objects define a read-only set of attributes that allow
to get some information about it. These attributes are:
.. attribute:: LargeObject.oid
the OID associated with the large object (int)
.. attribute:: LargeObject.pgcnx
the :class:`Connection` object associated with the large object
.. attribute:: LargeObject.error
the last warning/error message of the connection (str)
.. warning::
In multi-threaded environments, :attr:`LargeObject.error` may be modified by
another thread using the same :class:`Connection`. Remember these object
are shared, not duplicated. You should provide some locking to be able
if you want to check this. The :attr:`LargeObject.oid` attribute is very
interesting, because it allows you to reuse the OID later, creating the
:class:`LargeObject` object with a :meth:`Connection.getlo` method call.
|
