ResponsesModule
This module contains code that fetches responses from the server stream and return objects representing them.
Exceptions
MemoryError
, IOError
, NetworkError
, ParameterError
,
HandleError
, InternalError
, BusyError
, FileFormatError
,
corresponding to the error types returned from the
pgserver. ServerError
is an abstract exception class, and all the
exceptions above are subclasses of ServerError
.
Dead
, raised when the code hits an error while reading from the
server stream (for example, the connection could have been closed).
And Error
, the parent class of both Dead
and ServerError
(so
that you can write except responses.Error
).
The Data
class
When the packet from the server contains data longer than 32 bits
(response type 4), it is returned as an object of class Data
. This
object is callable; to convert it to a python object, just call it,
giving as argument a string in the format expected by the struct
module (http://python.org/doc/current/lib/module-struct.html), which
should usually start with an exclamation mark "!"
for network byte
order. For example: mydata("!L")
returns a long integer,
mydata("!40s")
returns a string of at most 40 characters.
Utility methods
The Data
class also has some utility methods for all response
data structures defined by version 14 of the protocol:
-
fstyle()
- for replies to
getfstyle
requests. These replies represent a font style. Return a tuple with 4 elements. Element 0 is a string with the font family name, 1 is an int for the size (if the font is bitmapped), 2 is an int for the fontrep and 3 is a long for the flags. FIXME document fontrep and flags? -
modeinfo
- for replies to
getmode
, containing information on the video mode. Return a tuple of 6 elements:flags
,xres
,yres
,lxres
,lyres
,bpp
, whereflags
is long and everything else is int. Note: the "interesting" values for resolution arelxres
andlyres
, whilexres
andyres
represent the physical resolution before any rotation.
Events
Event responses generate Event
objects. See EventsModule.
Module functions
Finally, the external API of this module consists of two functions:
get()
and next()
. They are both equivalent - in fact, next()
calls get()
- except that get()
returns exception objects in
case of errors, while next()
raises them in the standard python
way. (So, in usual python code you'll want to use next()
.) Also,
get()
returns a pair where the first element is the response id
(or None), while next()
discards this information. So, if you want
to check ids you'll have to use get()
and check for exceptions
yourself.
(but if your connection
object - see below - allows setattr, then
get()
will set a last_id
attribute on it. Also, Data and
ProtocolError? objects store the id internally, in the attribute
id
.)
Both functions expect a single parameter, representing the
server. This object can implement either a read()
or a recv()
function, which will be called with a numeric argument for the
number of bytes to be read. This means you can use objects that
implement the file protocol (file objects, StringIO, and the result
of socket.makefile()
) and plain socket objects.