Clients

CLAM is designed as a RESTful webservice. This means a client communicates with CLAM through the four HTTP verbs (GET/POST/PUT/DELETE) on pre-defined URLs, effectively manipulating various resources. The webservice will in turn respond with standard HTTP response codes and, where applicable, a body in CLAM XML format.

When writing a client for a CLAM webservice, Python users benefit greatly from the CLAM Client API, which in addition to the CLAM Data API provides a friendly high-level interface for communication with a CLAM webservice and the handling of its data. Both are shipped as an integral part of CLAM by default. Using this API greatly facilitates writing a client for your webservice in a limited amount of time, so it is an approach to be recommended. Nevertheless, there are many valid reasons why one might wish to write a client from scratch, not least as this allows you to use any programming language of your choice, or better integrate a CLAM webservice as a part of an existing application.

The RESTful API specification provides the full technical details necessary for an implementation of a client. Moreover, each CLAM service offers an automatically tailored RESTful specification specific to the service, and example client code in Python, by pointing your browser to your service on the path /info/.

Users of the CLAM Client API can study the example client provided with CLAM: clam/clients/textstats.py. This client is heavily commented.

There is also a generic CLAM Client, clamclient, which offers a command line interface to any CLAM service. The CLAM Client API enables users to quickly write clients to interact with CLAM webservices of any kind. It is an abstraction layer over all lower-level network communication. Consult also the CLAM Data API, as responses returned by the webservice are almost always instantiated as CLAMData objects in the client.

Client API Reference

class clam.common.client.CLAMClient(url, user=None, password=None, oauth=False, oauth_access_token=None, verify=None, loadmetadata=False, basicauth=False)
abort(project)

aborts AND deletes a project (alias of delete() ):

client.abort(“myprojectname”)

action(action_id, **kwargs)

Query an action, specify the parameters for the action as keyword parameters. An optional keyword parameter method=’GET’ (default) or method=’POST’ can be set. The character set encoding of the response can be configured using the encoding keyword parameter (defaults to utf-8 by default)

addinput(project, inputtemplate, contents, **kwargs)

Add an input file to the CLAM service. Explictly providing the contents as a string. This is not suitable for large files as the contents are kept in memory! Use addinputfile() instead for large files.

project - the ID of the project you want to add the file to. inputtemplate - The input template you want to use to add this file (InputTemplate instance) contents - The contents for the file to add (string)

Keyword Arguments:
 
  • filename - the filename on the server (*) –
  • metadata - A metadata object. (*) –
  • metafile - A metadata file (*) –

Any other keyword arguments will be passed as metadata and matched with the input template’s parameters.

Example:

client.addinput("myproject", "someinputtemplate", "This is a test.", filename="test.txt")

With metadata, assuming such metadata parameters are defined:

client.addinput("myproject", "someinputtemplate", "This is a test.", filename="test.txt", parameter1="blah", parameterX=3.5))
addinputfile(project, inputtemplate, sourcefile, **kwargs)

Add/upload an input file to the CLAM service. Supports proper file upload streaming.

project - the ID of the project you want to add the file to. inputtemplate - The input template you want to use to add this file (InputTemplate instance) sourcefile - The file you want to add: string containing a filename (or instance of file)

Keyword arguments (optional but recommended!):
  • filename - the filename on the server (will be same as sourcefile if not specified)
  • metadata - A metadata object.
  • metafile - A metadata file (filename)

Any other keyword arguments will be passed as metadata and matched with the input template’s parameters.

Example:

client.addinputfile("myproject", "someinputtemplate", "/path/to/local/file")

With metadata, assuming such metadata parameters are defined:

client.addinputfile("myproject", "someinputtemplate", "/path/to/local/file", parameter1="blah", parameterX=3.5)
create(project)

Create a new project:

client.create(“myprojectname”)

delete(project)

aborts AND deletes a project:

client.delete(“myprojectname”)

download(project, filename, targetfilename, loadmetadata=None)

Download an output file

downloadarchive(project, targetfile, archiveformat='zip')

Download all output files as a single archive:

  • targetfile - path for the new local file to be written
  • archiveformat - the format of the archive, can be ‘zip’,’gz’,’bz2’

Example:

client.downloadarchive("myproject","allresults.zip","zip")
downloadstorage(file_id, targetfile=None, targetdir='./')

Download a file from public storage. If targetfile is set to None, the name will be automatically determined. Returns the target file name

get(project)

Query the project status. Returns a CLAMData instance or raises an exception according to the returned HTTP Status code

getinputfilename(inputtemplate, filename)

Determine the final filename for an input file given an inputtemplate and a given filename.

Example:

filenameonserver = client.getinputfilename("someinputtemplate","/path/to/local/file")
getroot()

This calls the root of the webservice, providing either the index or the porch, depending whether or not authentication is necessary and credentials are passed.

It it better to explicitly call either index() or porch().

index()

Get index of projects. Returns a CLAMData instance. Use CLAMData.projects for the index of projects.

initauth()

Initialise authentication, for internal use

initrequest(data=None)
porch()

Get the porch page, basically a stripped-down response that works without authentication.

register_custom_formats(custom_formats)

custom_formats is a list of Python classes holding custom formats the webservice may use. These must be registered with the client before the client can be used.

register_custom_viewers(custom_viewers)

custom_formats is a list of Python classes holding custom viewers the webservice may use. These must be registered with the client before the client can be used.

request(url='', method='GET', data=None, parse=True, encoding=None)

Issue a HTTP request and parse CLAM XML response, this is a low-level function called by all of the higher-level communication methods in this class, use those instead

start(project, **parameters)

Start a run. project is the ID of the project, and parameters are keyword arguments for the global parameters. Returns a CLAMData object or raises exceptions. Note that no exceptions are raised on parameter errors, you have to check for those manually! (Use startsafe instead if want Exceptions on parameter errors):

response = client.start("myprojectname", parameter1="blah", parameterX=4.2)
startsafe(project, **parameters)

Start a run. project is the ID of the project, and parameters are keyword arguments for the global parameters. Returns a CLAMData object or raises exceptions. This version, unlike start(), raises Exceptions (ParameterError) on parameter errors.

response = client.startsafe(“myprojectname”, parameter1=”blah”, parameterX=4.2)
upload(project, inputtemplate, sourcefile, **kwargs)

Alias for addinputfile()

clam.common.client.donereadingupload(encoder)

Called when the uploaded file has been read