pyxmpp2.streambase.StreamBase

Package pyxmpp2 :: Module streambase :: Class StreamBase |
[hide private]

# Class StreamBase

Base class for a generic XMPP stream.

Responsible for establishing connection, parsing the stream, dispatching received stanzas to apopriate handlers and sending application's stanzas. This doesn't provide any authentication or encryption (both required by the XMPP specification) and is not usable on its own.

Whenever we say "stream" here we actually mean two streams (incoming and outgoing) of one connections, as defined by the XMPP specification.

Nested Classes | [hide private]
Inherited from `mainloop.interfaces.TimeoutHandler`: `__metaclass__`

Instance Methods | [hide private]
__init__(self, stanza_namespace, handlers, settings=None) Initialize StreamBase object |
initiate(self, transport, to=None) Initiate an XMPP connection over the transport. |
_initiate(self) Initiate an XMPP connection over a connected transport. |
receive(self, transport, myname) Receive an XMPP connection over the transport. |
_setup_stream_element_handlers(self) Set up stream element handlers. |
disconnect(self) Gracefully close the connection. |
event(self, event) Handle a stream event. |
transport_connected(self) Called when transport has been connected. |
close(self) Forcibly close the connection and clear the stream state. |
stream_start(self, element) Process <stream:stream> (stream start) tag received from peer. |
stream_end(self) Process </stream:stream> (stream end) tag received from peer. |
stream_eof(self) Process stream EOF. |
stream_element(self, element) Process first level child element of the stream). |
stream_parse_error(self, descr) Called when an error is encountered in the stream. |
_send_stream_start(self, stream_id=None, stream_to=None) Send stream start tag. |
send_stream_error(self, condition) Send stream error element. |
_send_stream_error(self, condition) Same as send_stream_error, but expects lock acquired. |
_restart_stream(self) Restart the stream as needed after SASL and StartTLS negotiation. |
`ElementTree.Element` |
_make_stream_features(self) Create the <features/> element for the stream. |
_send_stream_features(self) Send stream <features/>. |
write_element(self, element) Write XML `element` to the stream. |
_write_element(self, element) Same as write_element but with lock already acquired. |
send(self, stanza) Write stanza to the stream. |
_send(self, stanza) Same as send but assume lock is acquired. |
`int` |
regular_tasks(self) Do some housekeeping (cache expiration, timeout handling). |
_process_element(self, element) Process first level element of the stream. |
process_stream_error(self, error) Process stream error element received. |
check_to(self, to) Check "to" attribute of received stream header. |
generate_id(self) Generate a random and unique stream ID. |
_got_features(self, features) Process incoming <stream:features/> element. |
is_connected(self) Check if stream is is_connected and stanzas may be sent. |
set_peer_authenticated(self, peer, restart_stream=False) Mark the other side of the stream authenticated as peer |
set_authenticated(self, me, restart_stream=False) Mark stream authenticated as me. |
Inherited from `stanzaprocessor.StanzaProcessor`: `fix_in_stanza`, `fix_out_stanza`, `process_iq`, `process_message`, `process_presence`, `process_stanza`, `route_stanza`, `set_response_handlers`, `setup_stanza_handlers` Inherited from `stanzaprocessor.StanzaProcessor` (private): `_get_iq_handler`, `_process_handler_result`, `_process_iq_response`, `_set_response_handlers` Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__setattr__`, `__sizeof__`, `__str__`, `__subclasshook__`

Class Variables | [hide private]
Inherited from `mainloop.interfaces.TimeoutHandler`: `__abstractmethods__` Inherited from `mainloop.interfaces.TimeoutHandler` (private): `_abc_cache`, `_abc_negative_cache`, `_abc_negative_cache_version`, `_abc_registry`

Instance Variables | [hide private]
`dict` | _element_handlers mapping from stream element names to lists of methods handling them
`unicode` | _input_state `None`, "open" (<stream:stream> has been received) "restart" or "closed" (</stream:stream> or EOF has been received)
`unicode` | _output_state `None`, "open" (<stream:stream> has been received) "restart" or "closed" (</stream:stream> or EOF has been received)
`unicode` | _stanza_namespace_p qname prefix of the stanza namespace
`list` of StreamFeatureHandler | _stream_feature_handlers stream features handlers
`bool` | authenticated `True` if local entity has authenticated to peer
`ElementTree.Element` | features stream features as annouced by the receiver.
`list` | handlers handlers for stream elements and stanza payload
`bool` | initiator `True` if local stream endpoint is the initiating entity.
`threading.RLock` | lock lock object used to synchronize access to the StanzaProcessor object.
JID | me local JID.
JID | peer remote stream endpoint JID.
`bool` | peer_authenticated `True` if the peer has authenticated to us
`unicode` | peer_language language of human-readable stream content selected by the peer
`bool` | process_all_stanzas when `True` then all stanzas received are considered local.
XMPPSettings | settings stream settings
`unicode` | stanza_namespace default namespace of the stream
`bool` | tls_established `True` when the stream is protected by TLS
transport.XMPPTransport | transport transport used by this stream
(`int`, `int`) tuple | version Negotiated version of the XMPP protocol.

Properties | [hide private]
Inherited from `object`: `__class__`

Method Details | [hide private]

### __init__(self, stanza_namespace, handlers, settings=None) (Constructor) |
Initialize StreamBase object Parameters: `stanza_namespace` (`unicode`) - stream's default namespace URI ("jabber:client" for client, "jabber:server" for server, etc.) `handlers` (`list` of objects) - objects to handle the stream events and elements `settings` (XMPPSettings) - extra settings Overrides: object.__init__

### initiate(self, transport, to=None) |
Initiate an XMPP connection over the transport. Parameters: `transport` - an XMPP transport instance `to` - peer name

### _initiate(self) |
Initiate an XMPP connection over a connected transport. [ called with lock acquired ]

### receive(self, transport, myname) |
Receive an XMPP connection over the transport. Parameters: `transport` - an XMPP transport instance `myname` - local stream endpoint name.

### _setup_stream_element_handlers(self) |
Set up stream element handlers. Scans the handlers list for StreamFeatureHandler instances and updates _element_handlers mapping with their methods decorated with @`stream_element_handler`

### event(self, event) |
Handle a stream event. Called when connection state is changed. Should not be called with self.lock acquired!

### transport_connected(self) |
Called when transport has been connected. Send the stream head if initiator.

### stream_start(self, element) |
Process <stream:stream> (stream start) tag received from peer. lock is acquired when this method is called. Parameters: `element` - root element (empty) created by the parser Overrides: xmppparser.XMLStreamHandler.stream_start

### stream_end(self) |
Process </stream:stream> (stream end) tag received from peer. Overrides: xmppparser.XMLStreamHandler.stream_end

### stream_eof(self) |
Process stream EOF. Overrides: xmppparser.XMLStreamHandler.stream_eof

### stream_element(self, element) |
Process first level child element of the stream). Parameters: `element` - stanza's full XML Overrides: xmppparser.XMLStreamHandler.stream_element

### stream_parse_error(self, descr) |
Called when an error is encountered in the stream. Parameters: `descr` (`unicode`) - description of the error Overrides: xmppparser.XMLStreamHandler.stream_parse_error

### send_stream_error(self, condition) |
Send stream error element. Parameters: `condition` - stream error condition name, as defined in the XMPP specification.

### _make_stream_features(self) |
Create the <features/> element for the stream. [receving entity only] Returns: `ElementTree.Element` new <features/> element

### _send_stream_features(self) |
Send stream <features/>. [receiving entity only]

### write_element(self, element) |
Write XML `element` to the stream. Parameters: `element` (`ElementTree.Element`) - Element node to send.

### send(self, stanza) |
Write stanza to the stream. Parameters: `stanza` (pyxmpp2.stanza.Stanza) - XMPP stanza to send. Overrides: stanzaprocessor.StanzaProcessor.send

### regular_tasks(self) |
Do some housekeeping (cache expiration, timeout handling). This method should be called periodically from the application's main loop. Returns: `int` suggested delay (in seconds) before the next call to this method. Decorators: `@timeout_handler(1)`

### _process_element(self, element) |
Process first level element of the stream. The element may be stream error or features, StartTLS request/response, SASL request/response or a stanza. Parameters: `element` (`ElementTree.Element`) - XML element

### process_stream_error(self, error) |
Process stream error element received. Parameters: `error` (StreamErrorElement) - error received

### check_to(self, to) |
Check "to" attribute of received stream header. Should be overriden in derived classes which require other logic for handling that attribute. Returns: `to` if it is equal to me, None otherwise. Overrides: stanzaprocessor.StanzaProcessor.check_to

### generate_id(self) |
Generate a random and unique stream ID. Returns: the id string generated.

### _got_features(self, features) |
Process incoming <stream:features/> element. [initiating entity only] The received features node is available in features.

### is_connected(self) |
Check if stream is is_connected and stanzas may be sent. Returns: True if stream connection is active.

### set_peer_authenticated(self, peer, restart_stream=False) |
Mark the other side of the stream authenticated as peer Parameters: `peer` (JID) - local JID just authenticated `restart_stream` (`bool`) - `True` when stream should be restarted (needed after SASL authentication)

### set_authenticated(self, me, restart_stream=False) |
Mark stream authenticated as me. Parameters: `me` (JID) - local JID just authenticated `restart_stream` (`bool`) - `True` when stream should be restarted (needed after SASL authentication)

Instance Variable Details | [hide private]

### version Negotiated version of the XMPP protocol. (0,9) for the legacy (pre-XMPP) Jabber protocol. Type: (`int`, `int`) tuple