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
184
185
186
|
LargeObject -- Large Objects
============================
.. currentmodule:: pg
.. class:: LargeObject
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 recurring variables (object OID and connection), 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
through with its parameters. Any modification other than 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 error.
The exact error message is provided by the object's :attr:`error` attribute.
See also the PostgreSQL documentation for more information about the
`large object interface`__.
__ https://www.postgresql.org/docs/current/largeobjects.html
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 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 :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 a similar manner as
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: maximum 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 reading data from a large object, starting at the
current position.
.. method:: LargeObject.write(string)
Write data to large object
:param bytes data: buffer of bytes 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 writing data to a large object, starting at the 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 updates the position offset 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 returns the current position offset 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 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
---------------------------------------
.. 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 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
-----------------
:class:`LargeObject` objects define a read-only set of attributes exposing
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
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 :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.
|
