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 .. note:: 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-2011 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.2'
155