Package: hein
.. hein.. image:: http://img.shields.io/badge/license-GPLv3-blue.svg?style=flat:target: https://github.com/ceyzeriat/hein/blob/master/LICENSE:Name: hein:Website: https://github.com/ceyzeriat/hein:Author: Guillaume Schworer:Version: 0.2Hein: Advanced Subscriber-Publisher Socket Communication. Fully compatible python2 and 3.The native TPC/IP sockets implement a N-to-1 communication scheme: many clients (e.g. browsers) talk to a unique server (e.g. internet provider server) and engage a 1-to-1 communication (e.g. url request) with the server from which they will all get their own individual answers (e.g. web page). In this particular case, the server is passive: the only thing it does is answer the clients in a 1-to-1 communication.If there is no client, the server does nothing. If there is no server, the client returns an error.Now let's imagine the reverse case where one wants to broadcast the same message to N listeners (each of them in a perfectly separate and independent environment/process/namespace), where N is subject to changing with time, and no matter if some of the listeners are launched, not launched (yet), or dropped.This is a typical case where one needs a unique client to talk to several listening servers... and where the servers did themselves the "connection step" towards the broadcasting client... and where the client is broadcasting its messages even if no server is actually listening.Well, my friend, you are stuck.Actually not, because this is exactly what `hein` does: 1-Publisher to N-Subscriber ashynchronous socket communication, turn-key - check the example below.NB: ``PyDispatcher``, ``Dispatch``, ``PyPubSub``, ``smokesignal`` or other similar libraries will get you to the point where several threads can talk to each other - that is great for some applications, but threads are not processes and you will be required to share the publisher object among subscribers: this is not an option when subscribers run in separate processes, possibly on different machines. ``ZeroMQ`` will get you to the point where you can talk between processes. However, all of the asynchronous heavy logistics is left for you to implement, and the socket connections will crash when a subscriber drops (unless you cover this case in your own implementation as well). Both of these tweaks are natively covered in ``hein``: minimal effort. Also, hein requires no deamon to be run.Example=======Straight to the point: launch 3 terminals in which you should start an interactive python interpreter (not an IDE).In the first terminal (listener 1), type:.. code-block:: pythonfrom hein import SocReceiverr = SocReceiver(port=50007, name="Captain")in the second one (transmitter), type:.. code-block:: pythonfrom hein import SocTransmittert = SocTransmitter(port=50007, nreceivermax=2)You will instantly see the transmitter terminal wishing a hearful welcome to its first listener.In in the third one (listener 2), type:.. code-block:: pythonfrom hein import SocReceiverr = SocReceiver(port=50007, name="Kirk")Here again, the transmitter terminal acknoledges the connection of the second listener. Now type in the transmitter terminal:.. code-block:: pythont.tell_raw('hello!')And you will see the message appear in both listening terminals.Now close one listener and type:.. code-block:: pythont.ping()Only one listener is listed with the True (is connected) flag. Now let's try another one that keeps the type of the inputs:.. code-block:: pythonfrom datetime import datetimeimport pytzt.tell_json({'string': 'hello', 'integer': 34, 'float': 13.4, 'd': datetime(2017, 12, 3, tzinfo=pytz.UTC)})The receiver will get exactly the same thing:.. code-block:: python{'integer': 34, 'float': 13.4, 'string': 'hello', 'd': datetime.datetime(2017, 12, 3, 0, 0, tzinfo=<UTC>)}Obviously, the behavior at connection and reception is driven by callback functions, which by default only print the listener's names or the message transmitted.All you will need now is write your own functions to replace these default callbacks.That's it.Note that, as you probably have seen when running the example/teaser, that the communication are natively non-blocking and asynchronous: no need to do the ennoying threading work yourself, `hein` library is turnkey solution (unlike ZeroMQ).The best typical example of the use of hein is having several applications talking to each other: they are all busy doing their own things but still get messages from each other at the time their are sent (i.e. async, not at the time they are not busy anymore to process them).Documentation=============Refer to this page for detailed API documentation, http://pythonhosted.org/hein/hein.htmlRequirements============Hein requires the following Python packages:* socket: Really?* threading, select: for threading and port-reading* json: for unpacking the message* time, os, re: for basic stuff* byt: to handle chains of bytes identically no matter the python version* pytz: optional, for handling datetime-timezonesInstallation============The easiest and fastest way for you to get the package and run is to install hein through pip::$ pip install heinYou can also download Hein source from GitHub and type::$ python setup.py installDependency on byt will be installed automatically. Refer to the requirements section. If you have a standard install of python (or any fancier distribution like anaconda), you should be good to go.Contributing============Code writing------------Code contributions are welcome! Just send a pull request on GitHub and we will discuss it. In the `issue tracker`_ you may find pending tasks.Bug reporting-------------If you think you've found one please refer to the `issue tracker`_ on GitHub... _`issue tracker`: https://github.com/ceyzeriat/hein/issuesAdditional options------------------You can either send me an e-mail or add it to the issues/wishes list on GitHub.Citing======If you use Hein on your project, please`drop me a line <mailto:{my first name}.{my family name}@gmail.com>`, you will get fixes and additional options earlier.License=======Hein is released under the GNU General Public License v3 or later (GPLv3+). Please refer to the LICENSE file.Changelog---------0.2.3 (2018-04-27)+++++++++++++++++++- Renamed tell_json to tell- Fixed strict=False in json.loads to accept all bytes- Fixed support for python2, specifically json.loads rejecting bytes0.2.0 (2018-04-26)+++++++++++++++++++- Deprecated all "tell_*" methods of soctransmitter except tell_raw and tell_json- Both tell_raw and tell_json take an optional tag (str) to indicate what kind of message is transmitted- tell_json method automatically conserves the type of the value passed- tell_json method takes an optional unpack (bool, default True) argument that allows to not automatically unpack the message upon reception0.1.13 (2017-12-17)+++++++++++++++++++- Added tell_json and tell_json_ext which are able to pass any data structure, and keep the type information.- tell_json is a convenience method that uses a pure-json implementation of the serializer, which means that python3 will not be able to serialize bytes.- tell_json_ext is a custom serializer that is cross-consistent between python 2 and 3, and will deal properly with bytes as well as datetime objects.- fix README0.1.9 (2017-11-12)++++++++++++++++++- Added tell_list_type and tell_dict_type which keep the type of the data over transmission (works for int, float, bool, None, Byt, datetime.datetime, datetime.date, datetime.time, str, unicode (Pyt2), and bytes (Pyt3))- Modified 'tell' methods to accept unicode characters. Python3 built-in 'str' and Pyhton2 built-in 'unicode' are encoded as "utf-8", Python2 built-in 'str' and Python2/3 'bytes' are encoded as "ascii" (i.e. "latin-1").0.1.8 (2017-10-28)++++++++++++++++++- Added tell_list- Fixed infinite connection looping when adding two socreceivers with same name0.1.7 (2017-04-04)++++++++++++++++++- Implemented connect parameter in SocReceiver- Fixed bug on key being compared to instance Byt- Fixed bug with 'key' keyword in tell_key0.1.4 (2017-04-03)++++++++++++++++++- Added hostname to SocReceiver- Added tell_key method to SocTransmitter to send any key-type of dictionary0.1.2 (2017-03-22)++++++++++++++++++- Made timeout parameter of acknowledgement of receipt accessible0.1.1 (2017-03-09)++++++++++++++++++- Improved high-frequency management of communications- Changed maximum communication frequency to 100 Hz; faster communications are merged0.1.0 (2017-03-05)++++++++++++++++++- Initial release