--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/pyams_zmq/doctests/README.txt Wed Mar 04 22:40:07 2015 +0100
@@ -0,0 +1,100 @@
+=================
+pyams_zmq package
+=================
+
+PyAMS 'ZMQ' package can be used to build wrapper around ØMQ (or ZeroMQ) library to exchange
+messages following all ØMQ possible usages.
+
+At least two components are required to build a ØMQ based application:
+
+- a ØMQ server
+
+- a ØMQ client
+
+The way client and server communicate depends on used ØMQ protocol.
+
+We will take example on the medias conversion utility provided by 'pyams_media' package, which allows you
+to automatically convert medias files (videos...) asynchronously as soon as they are uploaded. The conversion
+process is a background process so doesn't return any result.
+
+The conversion process is a simple ØMQ process:
+
+ >>> converter_address = '127.0.0.1:5555'
+
+ >>> from pyams_zmq.process import ZMQProcess, process_exit_func
+ >>>
+ >>> class MediasConversionProcess(ZMQProcess):
+ ... """Medias conversion process"""
+
+ >>> from multiprocessing import Process
+ >>>
+ >>> class ConversionProcess(Process):
+ ... """Conversion manager process"""
+ ...
+ ... def __init__(self, settings, group=None, target=None, name=None, *args, **kwargs):
+ ... Process.__init__(self, group=group, target=target, name=name, args=args, kwargs=kwargs)
+ ... self.settings = settings
+ ...
+ ... def run(self):
+ ... settings = self.settings
+ ... path = settings['path']
+ ... format = settings['format']
+ ... # just image you're doing anything you want with these settings!
+
+To be sure to run asynchronously, this process is managed by a thread:
+
+ >>> import time
+ >>> from threading import Thread
+ >>>
+ >>> class ConversionThread(Thread):
+ ... """Conversion thread"""
+ ...
+ ... def __init__(self, process):
+ ... Thread.__init__(self)
+ ... self.process = process
+ ...
+ ... def run(self):
+ ... self.process.start()
+ ... self.process.join()
+
+The conversion handler is the simple class to which conversion is delegated:
+
+ >>> class ConversionHandler(object):
+ ... """Conversion handler"""
+ ...
+ ... def convert(self, data):
+ ... ConversionThread(ConversionProcess(data)).start()
+ ... return [200, 'OK']
+
+The message handler receives the message and handle it:
+
+ >>> from pyams_zmq.handler import ZMQMessageHandler
+ >>>
+ >>> class ConversionMessageHandler(ZMQMessageHandler):
+ ...
+ ... handler = ConversionHandler
+
+The ØMQ process is generally started on application startup:
+
+ >>> import atexit
+ >>>
+ >>> process = MediasConversionProcess(converter_address, ConversionMessageHandler)
+ >>> process.start()
+ >>> time.sleep(2)
+ >>> if process.is_alive():
+ ... atexit.register(process_exit_func, process=process)
+ <function process_exit_func at 0x...>
+
+Once all these elements are in place, you just have to create a ØMQ client context, open a connection and send a
+message:
+
+ >>> import zmq
+ >>> settings = {'path': '/this/is/my/path',
+ ... 'format': 'JPEG'}
+ >>> message = ['convert', settings]
+ >>> context = zmq.Context()
+ >>> socket = context.socket(zmq.REQ)
+ >>> socket.connect('tcp://' + converter_address)
+ >>> socket.send_json(message)
+ >>> socket.recv_json()
+ [200, 'OK']