Using the SAM Python API

Introduction

You can write your own programs in python that use the SAM API. SAM comes with its own version of python (this is to avoid clashes with any other version of python you might be using at the same time). The executable is called sampy. As a simple example, the API equivalent of sam locate foo is:

  > setup sam
  > sampy
  Welcome to SAM
  sampy using Python 2.4.2 (#1, Dec  2 2005, 11:17:28) 
  [GCC 3.4.3] on linux2
  >>> from Sam import sam
  >>> sam.locate(args=['foo'])
  Traceback (most recent call last):
    File "", line 1, in ?
    File "sam_common_pylib/SamCommand/BlessedCommandInterfacePlaceHolder.py", line 81, in __call__
    File "sam_common_pylib/SamCommand/CommandInterface.py", line 251, in __call__
    File "sam_common_pylib/SamCommand/SamCommandInterface.py", line 243, in apiWrapper
    File "sam_user_pyapi/src/samLocate.py", line 75, in implementation
    File "sam_common_pylib/SamCorba/SamServerProxy.py", line 257, in _callRemoteMethod
    File "sam_common_pylib/SamCorba/SamServerProxyRetryHandler.py", line 266, in handleCall
  DataFileNotFound: Datafile with name 'foo' not found.

Most, but not all, of the python standard library is included with sampy.

Alternatively, the sam libraries can be used with a normal python interpreter. The python version must match the major version used to make the sam release, which currently is python 2.4. To use it:

  > setup sam -O python
  > setup python v2_4_2_sam [or another 2.4 version]
  > python
  Python 2.4.2 (#1, Dec  2 2005, 11:17:28) 
  [GCC 3.4.3] on linux2
  Type "help", "copyright", "credits" or "license" for more information.
  >>> from Sam import sam

With this method the entire python standard library is available.

Using the API

What to import

All sam commands are available as API functions. There is a separate command object for each of sam, samadmin and sammis.

	Import statement
sam	from Sam import sam
samadmin	from SamAdmin import samadmin
sammis	from SamMis import sammis

The SAM exceptions all live in the SamException.SamExceptions module.

Passing arguments

The commands all expect their arguments to be passed as keywords, where the keywords are the same as the command line options for that command. Option synonyms are not supported. For example: sam.getMetadata(fileName='foo'). The eqivalent of the non-option command line arguments is a keyword named args, which must be a list of strings.

An example

#! /usr/bin/env sampy

import sys
from Sam import sam
from SamException import SamExceptions

def main():

    try:
        filename=sys.argv[1]
    except IndexError:
        return 'No filename given'

    try:
        md = sam.getMetadata(fileName=filename)
    except SamExceptions.DataFileNotFound:
        return 'No file in SAM named %s' % filename
    except SamExceptions.SamException, x:
        return 'SAM failed: %s' % str(x)

    print '%s has parents: %s' % (filename, md.getParents())

if __name__ == '__main__':
    sys.exit(main())