About

Pysig is a framework designed to manage event dispatching between two or more registered endpoints. The main philosophy behind a signaling framework, like pysig is, is to simplify the process by whitch a certain endpoint receives notifications or events from another, in an efficient and simple way.

One of the most interesting features of pysig is that it has the ability to dispatch messages over network, between different machines or different processes running on the same machine.

Feature set

To make a very short summary of what pysig can do, we could list the followings:

  • it enables subscription mechanisms that are able to
    • register for a specific event triggered by a specific sender
    • register for broadcast events triggered by any event fired by a specific sender
    • register for broadcast events triggered by any event of any sender
    • register for channel events triggered by those senders that share same event
    • register listeners without depending on the sender registration
  • supports firing requests to connected senders, for accessing data on reply
  • stateful sender connection, automatically firing connect and diconnect events
  • distribute events intra-process, inter-process or over a given network
  • built-in server and client implementation
  • built-in support for transporting messages via TCP
  • permits custom transport carrier implementation for dispatching events over different communication mediums (like serial connections) or for transporting them under a different format
  • permits custom data encoding (default is JSON encoding)

Terminology

Several terms are used in the context of this library and their meaning will be described here:

Router

Creates and manages the list of senders and listeners.

When run over a certain network, the router connects itself to a given carrier in order to transport messages and also comes in two flavors:

  • the server that is responsible with managing with the flow of events for all registered listeners or senders
  • the client that is responsible with communicating with the server for the purpose of registering listeners, senders or events

Sender

Represents the endpoint that signals the events.

It is also the endpoint that is optionaly capable of responding to requests.

Listener

Represents the endpoint that registers itself for receiving signaled events.

Event

Represents the object that stores the list of registered listeners.

An event is identified by its given name and is attached to a specific sender.

There are many types of events supported by pysig:
  • specific events
  • broadcast events
  • channel events

Signal

Represents the object responsible with triggering the events.

The signal carries out the list of events it knows it must fire when invoked.

Carrier

Represents the object in charge with transporting data over a given communication medium.

pysig comes with a list of built-in carriers, described later on in this documentation.

Logging support

Before using the library, it will be good to know that is supports logging. The default ‘logging’ library from python, can be connected to pysig, in the following manner:

import logging
import sig

# prepare logger object
logging.basicConfig()
logger = logging.getLogger('sig')

# setup sig logger
sig.setup_logger(logger)

If by any means, the logging library is not acceptable, pysig has its own logging utility called SimpleLogger. This utility will use print to output the logs, and inspect module in order to trace source line number and caller function. It will be described later in detail. (TBD)

import sig

# prepare logger
logger = sig.SimpleLogger(tag= "[sig]", level= sig.LOG_LEVELS.LEVEL_INFO)

# setup sig logger
sig.setup_logger(logger)

A glance of how the log will look like:

[sig][1713][             connect][    info]-[TCP_CL] Connecting to localhost:3000
[sig][1607][     _thread_receive][    info]-[TCP_CL] Started receive thread for localhost:3000
[sig][1653][     _thread_receive][    info]-[TCP_CL] Receive thread terminated

Roadmap

The current version of pysig is 0.7.1.

Until pysig reaches it’s first stable version, which will be 1.0, the author reserves the right of changing the API if it’s necessary. From version 1.0 all the versions of pysig sharing the same major number will be API compatible.

The modifications targeted for 1.0 version are:

  • improve coverage of unit-tests
  • improve multi-threading support
  • improve ServerRouter and ClientRouter implementation
  • improve CarrierTCPClient and CarrierTCPServer implementation
  • improve examples
  • improve overall documentation structure
  • refactor design for direct requests
  • add validation of communication protocol between ServerRouter and ClientRouter
  • add SSL support to built-in TCP carriers
  • add support for using multiple carriers at once for the very same server

Far fetched objectives:

  • add ACL (Access Control List) support, for allowing access only to some listeners

Authors

Library develop and maintained by Alex Mircescu.

For feature requests or comments please address to mircescu [at] gmail.com.