PyDIM Documentation

v1r3.2

PyDIM

PyDIM is a Python interface to DIM. PyDIM could be used to create DIM clients and servers, using an API very similar to the one that is used for C.

Requirements

DIM

As the name suggest, the package relies on the DIM package.

PyDIM has been developed using the v16rXX, v17rXX and v18r0 DIM versions and works with any. It has not been tested with older versions but I believe it has good chances to work. It does not depend on the DIM internals but only on DIM's API. This is why it should be compatible with a wide range of DIM versions.

Python

PyDIM has been tested with Python 2.3, 2.4 and 2.5.

Note: The package has been developed on both 32 and 64 bits architectures.

Installation

Getting the source code:

The source code is hosted in the CERN Central Subversion Service. There are several ways for accessing it:

• There is a web interface for browsing the code.
• You can get a local working copy for reading or, if you have access, making modifications to the code. To get a read-only copy use the following command:
  svn co https://svnweb.cern.ch/guest/lhcbonline/PyDIM/trunk
• Within CERN you can get write access using SSH authentication:
  svn co svn+ssh://svn/reps/lhcbonline/PyDIM/trunk

Building the package from scratch and installing it:

1. Install DIM. It is suggested to place the DIM libraries and header files in /usr/local/lib and /usr/local/include respectively. Please make the necessary changes so that the run-time linker finds libdim.so (basically add an entry in /etc/ld.so.conf that points to the DIM library directory). Make sure that the DIM library is built using the same compiler and architecture as the Python installation you want to use.
2. Get the latest version of PyDIM from SVN (as above)
3. cd to the PyDIM directory and execute "sudo make install".

In the general case this should take care of building the library.

If the DIM libraries are not installed in the usual locations, the install script will look for an environment variable with the actual location. The variables that can be used are:

• DIMDIR
• DIMHOME
• DIM_HOME

Remember to point that variable to the main DIM installation directory, i.e. the one that contains the sub-directories dim and the specific one for your operating system, e.g. linux.

For building on Windows you will need the same compiler (the same cl version) as the one used to build DIM. At this point, the default DIM C compiler is included in the Microsoft .Net 2003 framework. Ideally the Python interpreter should be build using the same compiler (any Python version > 2.3 should do the job).

Windows does not come by default with any SVN or CVS clients so you might want to install the Cygwin linux like environment for convenience. In this case make sure that the .Net paths are still correctly set.

RPM Installation and building instructions

PyDIM comes already built as and RPM package with a dependency on the DIM RPM. In this manner the PyDIM libraries can be deployed more easily on all the machines inside the Online system using rpm, yum or quattor. These RPMs (including the DIM ones) can be found on AFS under:

/afs/cern.ch/lhcb/project/web/online/online-rpm-repo/

The RPMs are for both i386 and x86_64 architectures and are compiled gcc 3.4.X against Python 2.3 (these are the standard Python, gcc versions for SLC 4.6).

There are two dependencies for building the package: python-devel and dim-devel. Those packages contains the header files for Python and DIM respectively.

RPMs packages are build using the distutils module, this can be done by running the setup script with command bdist_rpm:

    $ python setup.py bdist_rpm

The bdist_rpm command will create binary and source packages in the dist directory. The command provides options for the process, such as creating only the .spec file:

    $ python setup.py bdist_rpm --spec-only

Or building only the RPM source package:

    $ python setup.py bdist_rpm --source-only

The full list of the options can be displayed with the help command:

    $ python setup.py --help bdist_rpm

Building RPMs packages in SLC5

Builing RPM packages with distutils in SLC5 can be tricky. Check this guide with the description of the problem and a workaround.

MSI Installation and building instructions

PyDIM can be also be build as an MSI package or as a Windows installer. In the most simple scenario a simple "make msi" will do the job. This relies on the following assumption that the .Net environment is set up properly as described in the building instructions. The *.msi and *.exe packages will be found in the PyDIM/dist directory.

Summary of make targets

• build -> only builds the package
• install -> builds and install the package in /usr/lib/pythonXX (requires root). It does not include the documentation.
• doc -> builds the documentation using doxygen. You will require a version >= 1.5.XX. The typical SLC installation has doxygen 1.3.XX and this has poor support for parsing Python sources. You can use an older version but the documentation will be malformed.
• rpm -> creates a RPM. See also the pydim.spec file. Might require root privileges.
• msi -> creates a MSI installer package in the PyDIM/dist directory.

Usage

1. In case you have PyDIM installed as a RPM (recommended) then just set up the DIM_DNS_NODE and say "import pydim" from Python.
2. In case you have your own local installation you have to set up your environment properly to point to the appropriate libraries and scripts.

The setup/setup.sh is provided for bash shells as an environment setup template. It tries to set up the DIM_DNS_NODE, adds the PyDIM/python directory to your PYTHONPATH, LD_LIBRARY_PATH.

You can execute some tests/examples from the 'tests' directory. Those scripts can be used as examples of the package's functionality.

Examples

The following example shows to run a server with two simple services.

    import sys, time
    import pydim

    def service_callback(tag):
      """
      Service callbacks are functions (in general, Python callable objects)
      that take one argument: the DIM tag used when the service was added,
      and returns a tuple with the values that corresponds to the service
      parameters definition in DIM.
      """
      # Calculate the value of the server
      # ...
      val1 = 3.11
      val2 = 42
      return (val1, val2)

    def callback2(tag):
      # Calculate the value
      # ...
      # Remember, the callback function must return a tuple
      return ( "hello world", )

    # The function dis_add_service is used to register the service in DIM
    svc = pydim.dis_add_service('test service 1', "F:1;I:1;", service_callback, 1)

    # Register another service
    svc2 = pydim.dis_add_service('another service', "C", callback2, 2)

    # The return value is the service identifier. It can be used to check
    # if the service was registered correctly.
    if not svc2:
      sys.stderr.write("An error occurred while registering the service\n")
      sys.exit(1)

    # A service must be updated before using it.
    pydim.dis_update_service(svc)
    pydim.dis_update_service(svc2)

    # Start the DIM server
    pydim.dis_start_serving('server-name')

    while True:
      # Update the service periodically
      pydim.dis_update_service(svc)
      time.sleep(5)

Contact

This module was originally developed by Radu Stoica.

Now it's maintained by Niko Neufeld and Juan Manuel Caicedo.

Feel free to send your questions and bugfixes.

---