CLAM Client API

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.

class clam.common.client.CLAMClient(url, user=None, password=None, oauth=False, oauth_access_token=None, verify=None, loadmetadata=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")
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")
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)
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.

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