All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Writing Turbulence's mod-python applications

Introduction

Writing a python application using mod-python module involves the following steps:

  1. Writing an startup application that fulfills a python interface (specially start-file attribute)
  2. Add some configuration to your turbulence server to detect your application (see mod-python configuration)
  3. Use PyVortex (http://www.aspl.es/vortex/py-vortex/html/) and PyTurbulence (http://www.aspl.es/turbulence/py-turbulence/html/) API to handle and issue BEEP messages.

Knowing this general terms, the following is a tutorial to develop BEEP echo profile like using mod-python.

A mod-python application skel

  1. First, we have to create the start up file that will initialize your python application. The following is a basic skel (save content into init.py):

    # import beep services
    import vortex
    import vortex.tls
    import vortex.sasl
    # not required to import tbc module, implicitly included
    def app_init (_tbc):
    """
    Function called to initialize the module. It must return True to signal
    initialization was ok, otherwise False must be returned.
    """
    # return initialization ok
    tbc.msg ("My python module initialized")
    return True
    def app_close ():
    """
    Function called when Turbulence is closing.
    """
    return
    def app_reload ():
    """
    Function called when Turbulence received a command reload.
    """
    return

  2. Now we have to place some initialization code to register our echo profile. For that, extend app_init function to include the following:

    # import beep services
    import vortex
    import vortex.tls
    import vortex.sasl
    # not required to import tbc module, implicitly included
    def app_init (_tbc):
    # register profile urn:aspl.es:beep:profiles:echo and handle
    # all received messages at my_app_received
    vortex.register_profile ("urn:aspl.es:beep:profiles:echo",
    frame_received=my_app_received)
    # return initialization ok
    tbc.msg ("My python module initialized")
    return True
    def my_app_received (conn, channel, frame, data):
    if frame.type == "MSG":
    # received request, just echo
    channel.send_rpy (frame.content, frame.content_size, frame.msg_no)
    return
    def app_close ():
    """
    Function called when Turbulence is closing.
    """
    return
    def app_reload ():
    """
    Function called when Turbulence received a command reload.
    """
    return

  3. Ok, now we have our BEEP profile that echoes all content received over a channel running "urn:aspl.es:beep:profiles:echo", we need to tell Turbulence to load it. This is done by adding the following content into python.conf file. See mod-python administration reference for more details.

    <application name="My echo profile" >
       <location src="/directory/path/to/start-file" 
                 start-file="__init__" 
                 app-init="app_init" 
                 app-close="app_close" 
                 app-reload="app_reload" />
    </application>
    

  4. Now Turbulence will load our application once at the first connection received, registering profile and frame received handler associated. One thing remains: we have to update our profile path policy to allow our profile to be reachable. For example, we could use the following to allow executing our profile only if BEEP client connects from our local network (assuming 192.168.0.0/24):

    <path-def path-name="my profiles" src="192.168.0.*" >
       <allow profile="urn:aspl.es:beep:profiles:echo" />
    </path-def>
    

How to get current profile path working directory

Inside profile path configuration it is possible to define a working directory where the user can place some special files that are loaded especific profile path activated. In many cases it is interesting to get where is this working dir located so the BEEP application can store files using p * current running uid/gid. To do so, you can use the following:

# run this at the application_init python method
working_dir = os.path.dirname (sys.modules[__name__].__file__)