project pg_pqueue 1.0.1

PostgreSQL PQ protocol modules

PQueue is a package providing low-level PQ protocol classes for interacting with a PostgreSQL database. It supports version 3.0 of the protocol--the current primary version of protocol. The package also provides a basic protocol transaction class. This class keeps the state of the protocol in an interrupt safe manner, and validates the integrity of the communication as messages are received.

In general, you probably will never use this package directly, unless you are writing a driver.


package postgresql.protocol.pqueue

PQ protocol facilities

module postgresql.protocol.pqueue.cbuffer

PQ message stream

module postgresql.protocol.pqueue.element3

PQ version 3.0 elements
imports
import os
import struct
import sys
classes
class ParseError(Exception):
class Message(object):
class methods
def parse(self, data):
methods
def __eq__(self, ob):
def __repr__(self):
def __str__(self):
def serialization(self, writer):
class data
__slots__ = 
()
class Authentication(Message):
Authentication(request, salt)
class methods
def parse(subtype, data):
methods
def __init__(self, request, salt):
def serialize(self):
properties
property salt
property request
class data
type = 
'R'
__slots__ = 
('request', 'salt')
class Bind(Message):
Bind a parsed statement with the given arguments to a Portal
class methods
def parse(subtype, message_data):
methods
def __init__(self, portal, statement, args, rformats):
def serialize(self):
properties
property name
property arguments
property statement
property rformats
class data
__slots__ = 
('name', 'statement', 'arguments', 'rformats')
type = 
'B'
class CopyBegin(Message):
class methods
def parse(subtype, data):
methods
def __init__(self, format, formats):
def serialize(self):
properties
property formats
property format
class data
type = 
None
__slots__ = 
('format', 'formats')
class CopyFromBegin(CopyBegin):
Begin copying from
properties
property format
property formats
class data
__slots__ = 
('format', 'formats')
type = 
'G'
class CopyToBegin(CopyBegin):
Begin copying to
properties
property format
property formats
class data
__slots__ = 
('format', 'formats')
type = 
'H'
class CopyData(Message):
class methods
def parse(subtype, data):
methods
def __init__(self, data):
def serialize(self):
properties
property data
class data
type = 
'd'
__slots__ = 
('data',)
class EmptyMessage(Message):
An abstract message that is always empty
class methods
def parse(self, data):
methods
def serialize(self):
class data
type = 
''
__slots__ = 
()
class BindComplete(EmptyMessage):
Bind reaction
class methods
def __new__(subtype):
class data
__slots__ = 
()
type = 
'2'
class CloseComplete(EmptyMessage):
Close statement or Portal
class methods
def __new__(subtype):
class data
__slots__ = 
()
type = 
'3'
class CopyDone(EmptyMessage):
class methods
def __new__(subtype):
class data
type = 
'c'
__slots__ = 
()
class Disconnect(EmptyMessage):
Close the connection
class methods
def __new__(subtype):
class data
__slots__ = 
()
type = 
'X'
class Flush(EmptyMessage):
Flush
class methods
def __new__(subtype):
class data
__slots__ = 
()
type = 
'H'
class NoData(EmptyMessage):
Null command
class methods
def __new__(subtype):
class data
__slots__ = 
()
type = 
'n'
class Null(EmptyMessage):
Null command
class methods
def __new__(subtype):
class data
__slots__ = 
()
type = 
'I'
class ParseComplete(EmptyMessage):
Parse reaction
class methods
def __new__(subtype):
class data
__slots__ = 
()
type = 
'1'
class Suspension(EmptyMessage):
Portal was suspended, more tuples for reading
class methods
def __new__(subtype):
class data
__slots__ = 
()
type = 
's'
class Synchronize(EmptyMessage):
Synchronize
class methods
def __new__(subtype):
class data
__slots__ = 
()
type = 
'S'
class Execute(Message):
Fetch results from the specified Portal
class methods
def parse(self, data):
methods
def __init__(self, name, max = 
0
):
def serialize(self):
properties
property name
property max
class data
type = 
'E'
__slots__ = 
('name', 'max')
class Function(Message):
Execute the specified function with the given arguments
class methods
def parse(self, data):
methods
def __init__(self, oid, args, rformat = 
'\x00\x00'
):
def serialize(self):
properties
property rformat
property oid
property arguments
class data
type = 
'F'
__slots__ = 
('oid', 'arguments', 'rformat')
class FunctionResult(Message):
Function result value
class methods
def parse(self, data):
methods
def __init__(self, datum):
def serialize(self):
properties
property result
class data
type = 
'V'
__slots__ = 
('result',)
class KillInformation(Message):
Backend cancellation information
class methods
def parse(self, data):
methods
def __init__(self, pid, key):
def serialize(self):
properties
property key
property pid
class data
type = 
'K'
__slots__ = 
('pid', 'key')
class CancelQuery(KillInformation):
Abort the query in the specified backend
class methods
def parse(self, data):
methods
def serialize(self):
properties
property key
property pid
class data
type = 
''
__slots__ = 
('pid', 'key')
class NegotiateSSL(Message):
Discover backend's SSL support
class methods
def __new__(subtype):
def parse(self, data):
methods
def serialize(self):
class data
__slots__ = 
()
packed_version = 
'\x04\xd2\x16/'
type = 
''
class Notify(Message):
Asynchronous notification message
class methods
def parse(self, data):
methods
def __init__(self, pid, relation, parameter = 
''
):
def serialize(self):
properties
property relation
property pid
property parameter
class data
type = 
'A'
__slots__ = 
('pid', 'relation', 'parameter')
class Parse(Message):
Parse a query with the specified argument types
class methods
def parse(self, data):
methods
def __init__(self, name, statement, argtypes):
def serialize(self):
properties
property argtypes
property name
property statement
class data
type = 
'P'
__slots__ = 
('name', 'statement', 'argtypes')
class Ready(Message):
Ready for new query
methods
def __init__(self, data):
def serialize(self):
properties
property xact_state
class data
type = 
'Z'
__slots__ = 
('xact_state',)
class ShowOption(Message):
ShowOption(name, value)
GUC variable information from backend
class methods
def parse(self, data):
methods
def __init__(self, name, value):
def serialize(self):
properties
property value
property name
class data
type = 
'S'
__slots__ = 
('name', 'value')
class Void(Message):
An absolutely empty message. When serialized, it always yields an empty
string.
class methods
def __new__(self, *args):
methods
def __str__(self):
def serialize(self):
class data
type = 
''
__slots__ = 
()
class Close(Message, str):
Generic Close
class methods
def parse(subtype, data):
methods
def __repr__(self):
def serialize(self):
class data
type = 
'C'
__slots__ = 
()
class ClosePortal(Close):
Close the specified Portal
class data
subtype = 
'P'
__slots__ = 
()
class CloseStatement(Close):
Close the specified Statement
class data
subtype = 
'S'
__slots__ = 
()
class Complete(Message, str):
Complete command
class methods
def parse(self, data):
methods
def __repr__(self):
def serialize(self):
class data
type = 
'C'
__slots__ = 
()
class CopyFail(Message, str):
class methods
def parse(self, data):
methods
def __repr__(self):
def serialize(self):
class data
type = 
'f'
__slots__ = 
()
class Describe(Message, str):
Describe a Portal or Prepared Statement
class methods
def parse(subtype, data):
methods
def __repr__(self):
def serialize(self):
class data
type = 
'D'
__slots__ = 
()
class DescribePortal(Describe):
class data
subtype = 
'P'
__slots__ = 
()
class DescribeStatement(Describe):
class data
subtype = 
'S'
__slots__ = 
()
class Password(Message, str):
Password supplement
methods
def __repr__(self):
def serialize(self):
class data
type = 
'p'
__slots__ = 
()
class Query(Message, str):
Execute the query with the given arguments
class methods
def parse(self, data):
methods
def __repr__(self):
def serialize(self):
class data
type = 
'Q'
__slots__ = 
()
class Notice(Message, dict):
Notification message
class methods
def parse(self, data):
methods
def __init__(
self,
severity = 
None
,
message = 
None
,
code = 
None
,
detail = 
None
,
hint = 
None
,
position = 
None
,
internal_position = 
None
,
internal_query = 
None
,
context = 
None
,
file = 
None
,
line = 
None
,
function = 
None

):
def __repr__(self):
def serialize(self):
class data
__slots__ = 
()
type = 
'N'
class Error(Notice):
Incoming error
class data
__slots__ = 
()
type = 
'E'
class Startup(Message, dict):
Initiate a connection
class methods
def parse(self, data):
methods
def __repr__(self):
def serialize(self):
class data
__slots__ = 
()
type = 
''
class AttributeTypes(Message, tuple):
Tuple attribute types
class methods
def parse(self, data):
methods
def __repr__(self):
def serialize(self):
class data
type = 
't'
__slots__ = 
()
class Tuple(Message, tuple):
Incoming tuple
class methods
def parse(self, data):
methods
def __repr__(self):
def serialize(self):
class data
type = 
'D'
__slots__ = 
()
class TupleDescriptor(Message, tuple):
Tuple description
class methods
def parse(self, data):
methods
def __repr__(self):
def serialize(self):
class data
type = 
'T'
__slots__ = 
()
class WireMessage(Message, tuple):
class methods
def __new__(subtype, (type, data)):
def parse(self, data):
methods
def __repr__(self):
def serialize(self):
properties
property data
property type
class data
__slots__ = 
()
functions
def <lambda>(x):
def <lambda>(x):
def str_message_repr(self):
def tuple_message_repr(self):
def dict_message_repr(self):
data
AuthRequest_Cleartext = 
3
AuthRequest_Crypt = 
4
AuthRequest_GSS = 
7
AuthRequest_GSSContinue = 
8
AuthRequest_KRB4 = 
1
AuthRequest_KRB5 = 
2
AuthRequest_MD5 = 
5
AuthRequest_OK = 
0
AuthRequest_Password = 
3
AuthRequest_SCMC = 
6
AuthRequest_SSPI = 
9
BYTE = 
chr
BinaryFormat = 
'\x00\x01'
DictionaryType = 
dict
ObjectType = 
object
StringFormat = 
'\x00\x00'
StringType = 
str
TupleType = 
tuple
UNBYTE = 
ord
unpack = 
struct.unpack

module postgresql.protocol.pqueue.buffer

This is an abstraction module that provides the working buffer implementation.
If a C compiler is not available on the system that built the package, the slower
`postgresql.protocol.pqueue.pbuffer` module can be used in
`postgresql.protocol.pqueue.cbuffer`'s absence.

This provides a convenient place to import the necessary module without
concerning the local code with the details.

module postgresql.protocol.pqueue.client3

PQ version 3.0 client transactions
imports
import postgresql.protocol.pqueue.element3 as element
import sys
classes
class ProtocolError(Exception):
An exception that occurs when an unexpected message was received.
methods
def __init__(self, msg, invalid_message, expected = 
None
):
class Transaction(object):
A transaction object is state machine that is initialized with the request
messages to be sent to the server. It provides the messages to be sent and
takes the response messages for order and integrity validation:

        Transaction([postgresql.protocol.pqueue.element3.Message(), ..])

A message must be one of:

        * `postgresql.protocol.pqueue.element3.Query`
        * `postgresql.protocol.pqueue.element3.Function`
        * `postgresql.protocol.pqueue.element3.Parse`
        * `postgresql.protocol.pqueue.element3.Bind`
        * `postgresql.protocol.pqueue.element3.Describe`
        * `postgresql.protocol.pqueue.element3.Close`
        * `postgresql.protocol.pqueue.element3.Execute`
        * `postgresql.protocol.pqueue.element3.Synchronize`
        * `postgresql.protocol.pqueue.element3.Flush`
methods
def __init__(self, commands):
Initialize a `Transaction` instance using the given commands. Commands are
`postgresql.protocol.pqueue.element3.Message` instances. (Of course,
subclasses thereof.)
def __repr__(self):
def put_copydata(self, messages):
In the context of a copy, `put_copydata` is used as a fast path for
storing `element.CopyData` messages. When a non-`element.CopyData.type`
message is received, it reverts the ``state`` attribute back to
`standard_put` to normally process the message..
def put_tupledata(self, messages):
Fast path used when inside an Execute command. As soon as tuple
data is seen.
def reset(self):
Reset the `Transaction` instance to its initial state. Allows reuse
without recreation.
def reverse(self):
A generator that producing an iterator of completed messages in reverse
order. Last in, first out.
def sent(self):
empty messages and switch state to receiving
def sent_from_stdin(self):
The state method for sending copy data.
def standard_put(self, messages):
Attempt to forward the state of the transaction using the given
messages. "put" messages into the transaction for processing.

If an invalid command is initialized on the `Transaction` object, an
`IndexError` will be thrown.
def standard_sent(self):
empty messages and switch state to receiving
class data
hook = 
{'C': ({'3': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.CloseComplete'>>, None)},), 'B': ({'2': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.BindComplete'>>, None)},), 'E': ({'I': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Null'>>, None), 'H': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.CopyToBegin'>>, 2), 'C': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Complete'>>, None), 'D': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Tuple'>>, 1), 'G': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.CopyFromBegin'>>, 3)}, {'C': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Complete'>>, None), 's': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Suspension'>>, None), 'D': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Tuple'>>, 1)}, {'c': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.CopyDone'>>, 3), 'd': (<function <lambda> at 0x131c1f0>, 2)}, {'C': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Complete'>>, None)}), 'D': ({'t': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.AttributeTypes'>>, 1), 'T': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.TupleDescriptor'>>, None)}, {'T': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.TupleDescriptor'>>, None), 'n': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.NoData'>>, None)}), 'F': ({'V': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.FunctionResult'>>, 1)}, {'Z': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Ready'>>, None)}), 'H': None, 'Q': ({'C': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Complete'>>, 0), 'G': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.CopyFromBegin'>>, 1), 'I': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Null'>>, 0), 'H': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.CopyToBegin'>>, 2), 'T': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.TupleDescriptor'>>, 3), 'Z': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Ready'>>, None)}, {'C': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Complete'>>, 0)}, {'c': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.CopyDone'>>, 1), 'd': (<function <lambda> at 0x131c1b0>, 2)}, {'C': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Complete'>>, 0), 'Z': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Ready'>>, None), 'D': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Tuple'>>, 3)}), 'P': ({'1': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.ParseComplete'>>, None)},), 'S': ({'Z': (<bound method type.parse of <class 'postgresql.protocol.pqueue.element3.Ready'>>, None)},)}
fatal = 
None
state = 
(None, None)
initial_state = 
((), (0, 0), (0, 0))
data
Complete = 
None
Receiving = 
True
Sending = 
False

module postgresql.protocol.pqueue.version

PQ version class
classes
class Version(tuple):
Version((major, minor)) -> Version

Version serializer and parser.
class methods
def __new__(subtype, (major, minor)):
def parse(self, data):
methods
def __int__(self):
def __repr__(self):
def __str__(self):
properties
property major
property minor
data
CancelRequestCode = 
1234.5678
NegotiateSSLCode = 
1234.5679
TupleType = 
tuple
V2_0 = 
2.0
V3_0 = 
3.0
unpack = 
struct.unpack

module postgresql.protocol.pqueue.pbuffer

imports
import struct
classes
class pq_message_stream(object):
provide a message stream from a data stream
methods
def __init__(self):
def __len__(self):
number of messages in buffer
def __next__(self):
def _get_message(self):
def _rtruncate(self, amt = 
None
):
[internal] remove the given amount of data
def has_message(self):
if the buffer has a message available
def next(self):
def next_message(self):
def read(self, num = 
4294967295L
):
def truncate(self):
remove all data in the buffer
def write(self, data):
class data
_block = 
512
_limit = 
2048
data
__all__ = 
['pq_message_stream']