circuits.protocols.line module

Line Protocol

This module implements the basic Line protocol.

This module can be used in both server and client implementations.

circuits.protocols.line.splitLines(s, buffer) → lines, buffer

Append s to buffer and find any new lines of text in the string splitting at the standard IRC delimiter CRLF. Any new lines found, return them as a list and the remaining buffer for further processing.

class circuits.protocols.line.line(*args, **kwargs)

Bases: Event

line Event

An event is a message send to one or more channels. It is eventually dispatched to all components that have handlers for one of the channels and the event type.

All normal arguments and keyword arguments passed to the constructor of an event are passed on to the handler. When declaring a handler, its argument list must therefore match the arguments used for creating the event.

Every event has a name attribute that is used for matching the event with the handlers.

Variables

• channels –

  an optional attribute that may be set before firing the event. If defined (usually as a class variable), the attribute specifies the channels that the event should be delivered to as a tuple. This overrides the default behavior of sending the event to the firing component’s channel.

  When an event is fired, the value in this attribute is replaced for the instance with the channels that the event is actually sent to. This information may be used e.g. when the event is passed as a parameter to a handler.

• value – this is a circuits.core.values.Value object that holds the results returned by the handlers invoked for the event.

• success – if this optional attribute is set to True, an associated event success (original name with “_success” appended) will automatically be fired when all handlers for the event have been invoked successfully.

• success_channels – the success event is, by default, delivered to same channels as the successfully dispatched event itself. This may be overridden by specifying an alternative list of destinations using this attribute.

• complete – if this optional attribute is set to True, an associated event complete (original name with “_complete” appended) will automatically be fired when all handlers for the event and all events fired by these handlers (recursively) have been invoked successfully.

• complete_channels – the complete event is, by default, delivered to same channels as the initially dispatched event itself. This may be overridden by specifying an alternative list of destinations using this attribute.

class circuits.protocols.line.Line(*args, **kwargs)

Bases: BaseComponent

Line Protocol

Implements the Line Protocol.

Incoming data is split into lines with a splitter function. For each line of data processed a Line Event is created. Any unfinished lines are appended into an internal buffer.

A custom line splitter function can be passed to customize how data is split into lines. This function must accept two arguments, the data to process and any left over data from a previous invocation of the splitter function. The function must also return a tuple of two items, a list of lines and any left over data.

Parameters

splitter (function) – a line splitter function

This Component operates in two modes. In normal operation it’s expected to be used in conjunction with components that expose a Read Event on a “read” channel with only one argument (data). Some builtin components that expose such events are: - circuits.net.sockets.TCPClient - circuits.io.File

The second mode of operation works with circuits.net.sockets.Server components such as TCPServer, UNIXServer, etc. It’s expected that two arguments exist in the Read Event, sock and data. The following two arguments can be passed to affect how unfinished data is stored and retrieved for such components:

Parameters

getBuffer (function) – function to retrieve the buffer for a client sock

This function must accept one argument (sock,) the client socket whoose buffer is to be retrieved.

Parameters

updateBuffer (function) – function to update the buffer for a client sock

This function must accept two arguments (sock, buffer,) the client socket and the left over buffer to be updated.

@note: This Component must be used in conjunction with a Component that

exposes Read events on a “read” Channel.

initializes x; see x.__class__.__doc__ for signature