Technologies¶

micala is mainly written in Python, version 2.7. All the processing scripts and the monitoring web interface are written in Python. The flash player to play lectures is written using Flex framework. The database currently in production is MySQL, but it is possible to use any other one (if compatible with MySQL queries syntax).

Version control¶

We are currently using GIT as version control system (Why GIT?). The project is hosted on SourceForge.

Configuring GIT

1. Exclude file patterns

Find the .git directory (e.g. micalaHomemicala.git or micalaHome/micala/micala/.git). In GNU/Linux, you’ll need to list hidden files to see it, e.g. ls -a

Edit the file .git/info/exclude, adding configuration files and any other patterns you want git to ignore. You can just copy/paste the following lines into the end of the exclude file:

# you should definitely put these lines in, to keep local configuration and build files separate from the code
doc/conf.py
doc/_build/
etc/conf.py
etc/processing.conf
etc/Micala-Common/Makefile
etc/Micala-Common/blib/
etc/Micala-Common/pm_to_blib
monitoring/web_interface/js/jquery-1.4.2.min.js
monitoring/web_interface/js/jquery-1.5.min.js
monitoring/web_interface/js/jquery-ui-1.8.6.custom.min.js
monitoring/web_interface/js/jquery.tools.min.js
monitoring/web_interface/css/jquery-ui-css/
monitoring/web_interface/admin/web.config
monitoring/web_interface/monitor/web.config
monitoring/db_init/micala_init.bat
recording/windows_adobe/www/encoder_conf.py
recording/windows_adobe/www/jquery-1.4.2.min.js
*.pyc

# these lines are recommended; they tell git to ignore emacs
# temp/backup, MS Word temp/backup files and Eclipse project files.
# If your editor generates temporary/backup files, make sure to
# include patterns for those, so they don't get added to the code repository.
*~
\#*
~*
.project
.pydevproject

2. User info

If you want to submit code to the micala project, you’ll need to set up your user info in git.

In GNU/Linux: Edit the file ~/.gitconfig (in Windows this is probably to be found in C:Usersslickwillie.gitconfig), adding the following section (optionally add the aliases if you want them):

[user]
    email = slickwillie@example.com
    name = Slick Willie
[alias]
    st = status
    ci = commit
    co = checkout
    br = branch
    df = diff
    lg = log -p

In Windows: Open the Git GUI from the Start menu

Click on Edit -> Options...

An Options window will appear. There are two columns, “micala repository” and “Global (all repositories)”. At the top of each column, you should enter your user name (“Your Name”) and email address youremail!@server.com.

Also, you need to sign up for a sourceforge account and request to join the project. Join to micala development!

3. Remote repositories

Log into the sourceforge shell service and create a “bare” git repository:

cd userweb/htdocs
git init --bare micala-slickwillie.git

Now add the following section to .git/config:

[remote "slickwillie-public"]
    url = ssh://slickwillie,micala@shell.sourceforge.net/~/userweb/htdocs/micala-slickwillie.git
    fetch = +refs/heads/*:refs/remotes/slickwillie-public/*

Programming practices¶

1. Removing trailing spaces

• Please, don’t commit any trailing white spaces! If using Eclipse, AnyEditTools can help to remove trailing white spaces in all kind of test files.

To remove trailing whitespaces, which give a lot of problems when integrating branches in git, install AnyEditTools. You can do this by using the http://andrei.gmxhome.de/eclipse/ URL in Help > Install New Software. There’s a lot of packages: search for the AnyEditTools package with the highest version number.

• Use always 4 white spaces instead of TABs!

2. Comment and variables

• If it’s not obvious, add a comment
• Comment always your classes and methods, even if they look trivial for you.
• Use consistent names for variables, don’t use acronyms.

Design Patterns¶

micala is an object oriented software. We are currently working to move everything to objects. The best idea is to use design pattern for a good implementation: the code is split using Model-View/Template-Controller for the monitoring web interface but the model is widely used by each processing script. There is also a Proxy design pattern to abstract from the way on how to transfer files and folders between serves.

Inside the etc folder you can find two important directories: model and mapper. Every class which represent an object in micala is inside the model dir. These classes are also following the database structure and vice-versa. If you want to query the database, you should use/edit the relative mapper: a mapper find, edit, insert, delete objects in the database. Try to find any example around the code if it is not clear the first time.

We ask you to keep this structure when adding/editing/deleting classes for a better maintainability of the source code.

ProxyIO

This library is created to abstract the way how to transmit files and folder. The idea is that you can have several different server, unix, win, mac and they have to interoperate together. After setting up in the conf file which operative system is running in a particular machine, and after configuring correctly the parameters in the machines page using the web interface, this class is able to adapt it self to transmit files with normal copy, or using scp if for example a win machine as to work with a unix machine. The idea is that you can extend this class and implement your way of transferring data, adding for example a class for FTP. For more information, please refer to the source code.

Helpers¶

Every class which is static and is created as helper should be put inside etchelpers folder. You can already find some classes, for example to send email, to manage xml files or as interface for the DB.

Output¶

1. Common.pr and Common.debug

Instead of using the print statement, you should use the classmethods pr and debug from the class Common for all output, e.g.:

Common.pr(1, "Starting processing for lecture %s\n" % LOID)

For debug output:

Common.debug(1, "Last known status is %s" % status)

2. Output levels

Every time you use pr and debug, you must specify a verbosity or debug level, which indicates its importance. Lower levels are more important.

• Level 0: for errors
• Level 1: important messages that should always be displayed, even in quiet mode.
• Level 2: normal messages that should always be displayed on the console but not in the log file.
• Level 3+: messages that should only be displayed if the user wants more verbosity.

The following variables are defined in conf.py:

• DEBUG_LEVEL (default value is 0)

  Every debug statement of this level or lower will be displayed

• DEBUG_LEVEL_LOGGING (default value is 0)

  Every debug statement of this level or lower will be appended to the log file

• VERBOSITY_LEVEL (default value is 1)

  Every pr statement of this level or lower will be displayed

These are the default values and the ones we use for production. If you want to see more messages, you can raise the appropriate level. But please keep in mind that if you are running the daemon with elevated output levels, your log files will grow very big very quickly! You can also run scripts individually, and for most of them you can set the verbosity/debug levels from the command line, e.g.:

webcast2lectureobject.py --verbosity=3 --debug=5

In this example, Common.pr(n, message) (where n <= 3) will get displayed, and Common.debug(n, message) (where n <= 5) will get displayed.

It is not currently possible to set the DEBUG_LEVEL_LOGGING from the command line for any scripts.

3. Errors

To print an error message, use pr with verbosity level 0:

Common.pr(0, "corrupt file.\n")