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 a **specific sender**
        * register for **broadcast events** triggered by **any sender**
        * register for **channel events** triggered by **some senders**
        * register listeners without depending on the sender registration
    * supports firing **requests** to connected senders, for accessing data instantly
    * 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 TCP carrier for TCP/IP networks
    * 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.

Authors
*******

Library develop and maintained by **Alex Mircescu**.