Chapter 2. Users Guide

Table of Contents

Introduction to Python
Python Basics
Blocks, Functions and Exceptions
Working with modules
A first look on the incoming and idle scripts
The incoming script
The idle script
Used file formats
Format of voice files (inversed A-Law, 8kHz, mono)
Format of fax files (Structured Fax Files)
Tutorial: writing an incoming script
Basics and a really dumb answering machine.
Improving it to a useful (?) state
Using sensible file names
Automatic fax recognition and receiving
Example for an idle script
Structural overview of the default scripts
incoming.py
idle.py
capisuitefax
cs_helpers.py
CapiSuite command reference

In the last chapter you've seen how to use the default scripts distributed with CapiSuite. But the main goal in developing CapiSuite was not to provide a perfect ready-to-use application. I intended to develop a tool where you can write your own applications very easyly. I'll show you how to do this in the next sections.

Introduction to Python

As I thought about the scripting language I wanted to integrate into CapiSuite, my first idea was to develop an own, simple one. But as more as I looked into it, the more I found that a general purpose language will be much more helpful than re-inventing every wheel that I would need. So I looked for some easy to integrate (and to learn) language. The one I liked most was Python - and it also had a nice documentation about embedding, so I chose it and I'm still happy about that decision. :-)

So the first thing you'll have to do is to learn Python. Don't be afraid - it was developed as a beginners language and Guido (Guido van Rossum, the inventor of Python) has done very well in my opinion.

In the next few sections, I'll give you a short introduction to the features of Python you most probably will need for CapiSuite. As this shouldn't be a manual about Python or a tutorial in computer programming, I assume you're already familiar with the basic concepts of todays wide-spread procedural and object-oriented languages.

If not, I would advise you to get and read a book for learning Python - there are many available in different languages. The Python home page on http://www.python.org has also nice and comprehensive manuals and tutorials available for free.

Python Basics

Python supports most features you know from other common languages. Here's the syntax of the basic operations shown in a Python session. A Python session is another fine feature of its interpreter: just start it by typing python in a shell and you'll get a prompt:

gernot@linux:~> python
Python 2.2.1 (#1, Sep 10 2002, 17:49:17)
[GCC 3.2] on linux2
Type "help", "copyright", "credits" or "license" for more
information.
>>>

As you can see, the Python prompt is >>>. If you enter commands that span multiple lines, Python shows a second prompt: ...

>>> if (1==2):
...     print "Now THAT's interesting!"
...

Ok, now let's go on:

>>> # comments start with # at the begin of a line
>>> # now the usual first steps
>>> print "hello world"
hello world
>>> # variables
>>> a=5 # no separate declarations necessary
>>> b=a*2
>>> print b
10
>>> b='hello'
>>> print b,'world'
hello world
>>> # python is very powerful in handling sequences
>>> a=(1,2,3) # defines a tuple (not changeable!)
>>> print a
(1, 2, 3)
>>> a[1]=2  # this must fail
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: object doesn't support item assignment
>>> a=[1,2,3] # defines a list (changeable)
>>> a[1]=7
>>> print a
[1, 7, 3]
>>> # control structures
>>> if (b=='hello'):
...     print "b is hello"
... else:
...     print "????"
...
b is hello
>>> # the for statement can iterate over sequences
>>> for i in a:
...     print i
...
1
7
3
>>> # replace positions 1 to 3 (without 3) with 0
>>> a[1:3]=[0]
>>> a
[1, 0]
>>> # a[-i] is the i-the element counted from the back
>>> a[-1]=7; a[-2]=8
>>> a
[8, 7]

Blocks, Functions and Exceptions

Blocks are grouped only by identation. No begin, end, braces ({, }) or the like are needed. This sounds very uncomfortable at the first sight, but it's really nice - you must always structure your code exactly how you mean it:

>>> for i in [1,2,3]:
...     print 2*i
...
2
4
6
>>> i=0
>>> while (i!=3):
...     print i
...     i+=1
...
0
1
2

Now let's see how to define functions and how to work with exceptions:

>>> def double_it(a):
...     return (2*a)
...
>>> print double_it(9)
18
>>> print double_it("hello")
hellohello
>>>
>>> # let's trigger a exception
>>> a=1/0
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
ZeroDivisionError: integer division or modulo by zero
>>>
>>> # now let's catch it
>>> try:
...     a=1/0
... except ZeroDivisionError,e:
...     print "You divided by zero, message was:",e
...
You divided by zero, message was: integer division or modulo by zero

Working with modules

Modules are a way to group functions together. They must be imported before you can use them and they give you a new object containing all functions. Let's play around with some of them:

>>> import time
>>> # what is in time?
>>> dir(time)
['__doc__', '__file__', '__name__', 'accept2dyear', ...]
>>> # So - what do all these functions do? Python can tell...
>>> print time.__doc__
This module provides various functions to manipulate time values.

[...]

Variables:

[...]

Functions:

time() -- return current time in seconds since the Epoch as a float
ctime() -- convert time in seconds to string
[...]

>>> # Could you please explain ctime in more detail?
>>> print time.ctime.__doc__
ctime(seconds) -> string

Convert a time in seconds since the Epoch to a string in local time.
This is equivalent to asctime(localtime(seconds)). When the time tuple
is not present, current time as returned by localtime() is used.

>>> time.time()
1044380131.186987
>>> time.ctime()
'Tue Feb  4 18:35:36 2003'
>>> import os
>>> os.getuid()
500
>>> import pwd
>>> pwd.getpwuid(500)
('hans', 'x', 500, 100, 'Hans Meier', '/home/hans', '/bin/bash')

Ok, now I hope you got a small idea of Python. Have fun with it. I had... :-)

If you have further questions, I would really advise you to continue with a good book or the documentation on http://www.python.org. Please don't ask general Python questions on the CapiSuite lists...