Package ivy
[hide private]
[frames] | no frames]

Source Code for Package ivy

  1  """ 
  2  Ivy is a lightweight software bus for quick-prototyping protocols. It 
  3  allows applications to broadcast information through text messages, with a 
  4  subscription mechanism based on regular expressions. 
  5   
  6  If you're used to the standard Ivy API, you probably want to look at the 
  7  `std_api` module. 
  8   
  9  .. attention:: Version 2.0 broke backward compatibility.  If you are upgrading 
 10    from ivy-python v1.x, be sure to read the `v2.0 compatibility notes`_, 
 11    below. 
 12   
 13  Introduction 
 14  ------------ 
 15   
 16  The Ivy software bus was designed at the French Centre d'Etudes de la 
 17  Navigation Aerienne (CENA).  The original work: sofware, documentation, 
 18  papers, credits can be found on the `Ivy Home Page`_; it contains all the 
 19  necessary materials needed to understand Ivy. 
 20   
 21  This package is the Python library; Ivy librairies are also available for 
 22  numerous languages, among wich: C, C#, C++, Java, Perl --see the `Ivy Download 
 23  Page <http://www.tls.cena.fr/products/ivy/download/index.html>`_ for details. 
 24   
 25  This python library is a full rewrite of the original software, and it is 
 26  written in pure python.  Note that another python implementation is available 
 27  at the `Ivy downloads page`_, which is built by `SWIG <http://www.swig.org/>`_ 
 28  on top of the Ivy C library. 
 29   
 30   
 31   
 32  Understanding the package 
 33  ------------------------- 
 34   
 35  This Ivy package is made of two modules: `ivy` and `std_api`. 
 36   
 37  In order to understand the way it works, we highly suggest that you read the 
 38  materials available from the `Ivy Home Page`_.  Within the documentation of 
 39  this python package we suppose that you are already familiar with the way an 
 40  ivy bus works, and with how the corresponding framework is organized. 
 41   
 42  `ivy.std_api` 
 43  ~~~~~~~~~~~~~ 
 44  Once familiar with the ivy framework, you'll find in the `std_api` module the 
 45  exact API you're expecting (see for example the  `The Ivy C library`_). 
 46   
 47  An example of use, directly taken from the original swig-base python release, 
 48  is included with the package, see ``examples/pyhello.py``. 
 49   
 50  .. important:: One big difference with the original implementation is that 
 51     there is nothing like a "main loop": the server is activated as soon as the 
 52     method `ivy.std_api.IvyStart` is called, and the `ivy.std_api.IvyMainLoop` method simply 
 53     waits for the server to terminate (the server is in fact  
 54   
 55  `ivy.ivy` 
 56  ~~~~~~~~~ 
 57   
 58  It's where the "magic" goes: the module `std_api` is built on top of it. 
 59   
 60  You'll be interested in using this package if for example, you want to manage 
 61  more than one ivy-bus in an application.  We won't give here much hint on how 
 62  to use it, since the code of the `ivy` odule itself serves as a perfect 
 63  example of use! 
 64   
 65  Logging 
 66  ------- 
 67   
 68    The module issues messages through python's standard ``logging`` module: 
 69     
 70      - logger's name: ``'Ivy'`` 
 71      - default level: ``logging.INFO`` 
 72      - default handler: a ``logging.StreamHandler`` logging messages to the 
 73        standard error stream. 
 74   
 75    For example, if you need to see all messages issued by the package, including 
 76    debug messages, use the following code excerpt: 
 77   
 78    .. python:: 
 79      import logging 
 80      logging.getLogger('Ivy').setLevel(logging.DEBUG) 
 81   
 82    Further details can be found in the `Python standard documentation 
 83    <http://docs.python.org/lib/module-logging.html>`_. 
 84   
 85  v2.0 compatibility notes 
 86  ------------------------ 
 87   
 88  Version 2.0 broke the backward compatibility with former versions 1.x: every 
 89  callback methods now receives an `ivy.IvyClient` object as its first 
 90  parameter. 
 91   
 92  This makes it possible for the receiving code to know which agent on the bus 
 93  sends the corresponding event. Unfortunately, this breaks backward 
 94  compatibility and callback methods must be adapted to the new scheme. 
 95   
 96  For example, suppose you're binding a regexp to the callback ``on_msg``: 
 97   
 98  .. python:: 
 99    IvyBindMsg(onhello, "^hello=([^ ]*) from=([^ ]*)") 
100   
101  In ivy-python 1.x, you used to declare the callback as follows 
102   
103  .. python:: 
104        def onhello(*arg): 
105            print "Got hello message: %s from: %s"% (arg[0], arg[1]) 
106   
107  or: 
108     
109  .. python:: 
110        def onhello(message, from): 
111            print "Got hello message: %s from: %s"% (message, from) 
112   
113   
114  In version 2.0, your callbacks also get the agent triggering the event as the 
115  1st parameter; the previous callbacks should be rewritten this way: 
116   
117  .. python:: 
118        def onhello(*arg): 
119            print "Got hello message: %s from: %s (coming from ivy agent: %r)"% (arg[1], arg[2], arg[0]) 
120   
121  or: 
122   
123  .. python:: 
124        def onhello(agent, message, from): 
125            print "Got hello message: %s from: %s (coming from ivy agent: %r)"% (message, from, agent) 
126   
127   
128  Misc. notes 
129  ----------- 
130   
131    - direct msg: to app_name == the last one registered w/ that name (for 
132      example register ivyprobe 3 times and send a direct msg to IVYPROBE from 
133      one of them) 
134   
135    - regexps order and ids: ivyprobe e.g. subscribes regexp in reverse order of 
136      ids.  If two matches -> which one should we choose? Not explicitely 
137      documented. 
138   
139   
140  License 
141  ------- 
142   
143  This software is distributed under the `"new" BSD license 
144  <http://www.opensource.org/licenses/bsd-license.php>`_, 
145   
146  (please refer the file ``LICENSE`` for full legal details) 
147   
148  Copyright (c) 2005-2008 Sebastien Bigaret <sbigaret@users.sourceforge.net> 
149   
150  .. _Ivy Home Page: http://www.tls.cena.fr/products/ivy/ 
151  .. _The Ivy C library: http://www.tls.cena.fr/products/ivy/documentation/ivy-c.pdf 
152  .. _Ivy downloads page: http://www.tls.cena.fr/products/ivy/download/binaries.html 
153  """ 
154  __version__='2.1' 
155