Package intermine :: Module webservice :: Class Service
[hide private]
[frames] | no frames]

Class Service

source code

object --+
         |
        Service

A class representing connections to different InterMine WebServices

The intermine.webservice.Service class is the main interface for the user. It will provide access to queries and templates, as well as doing the background task of fetching the data model, and actually requesting the query results.

SYNOPSIS

example:

 from intermine.webservice import Service
 service = Service("http://www.flymine.org/query/service")

 template = service.get_template("Gene_Pathways")
 for row in template.results(A={"value":"zen"}):
   do_something_with(row)
   ...

 query = service.new_query()
 query.add_view("Gene.symbol", "Gene.pathway.name")
 query.add_constraint("Gene", "LOOKUP", "zen")
 for row in query.results():
   do_something_with(row)
   ...

OVERVIEW

The two methods the user will be most concerned with are:

TERMINOLOGY

Query is the term for an arbitrarily complex structured request for data from the webservice. The user is responsible for specifying the structure that determines what records are returned, and what information about each record is provided.

Template is the term for a predefined "Query", ie: one that has been written and saved on the webservice you will access. The definition of the query is already done, but the user may want to specify the values of the constraints that exist on the template. Templates are accessed by name, and while you can easily introspect templates, it is assumed you know what they do when you use them


See Also: intermine.query

Instance Methods [hide private]
 
__init__(self, root, username=None, password=None)
Construct a connection to a webservice:
source code
 
new_query(self)
This is the standard method for instantiating new Query objects.
source code
 
get_template(self, name)
Tries to retrieve a template of the given name from the webservice.
source code
 
get_results(self, path, params, rowformat, view)
This method is called internally by the query objects when they are called to get results.
source code
 
get_results_list(self, path, params, rowformat, view)
This method is called internally by the query objects when they are called to get results.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Variables [hide private]
  QUERY_PATH = '/query/results'
  MODEL_PATH = '/model'
  TEMPLATES_PATH = '/templates/xml'
  TEMPLATEQUERY_PATH = '/template/results'
  VERSION_PATH = '/version'
  USER_AGENT = 'WebserviceInterMinePerlAPIClient'
  LIST_PATH = '/lists/xml'
  SAVEDQUERY_PATH = '/savedqueries/xml'
  RELEASE_PATH = '/version/release'
  SCHEME = 'http://'
Properties [hide private]
int version
The version specifies what capabilities a specific webservice provides.
string release
Service.release → string
dict templates
Service.templates → dict(intermine.query.Template|string)
intermine.model.Model model
Service.model → intermine.model.Model

Inherited from object: __class__

Method Details [hide private]

__init__(self, root, username=None, password=None)
(Constructor)

source code 

Constructor

Construct a connection to a webservice:

   service = Service("http://www.flymine.org/query/service")
Parameters:
  • root - the root url of the webservice (required)
  • username - your login name (optional)
  • password - your password (required if a username is given)
Raises:
  • ServiceError - if the version cannot be fetched and parsed
  • ValueError - if a username is supplied, but no password
Overrides: object.__init__

new_query(self)

source code 

Construct a new Query object for the given webservice

This is the standard method for instantiating new Query objects. Queries require access to the data model, as well as the service itself, so it is easiest to access them through this factory method.

Returns:
intermine.query.Query

get_template(self, name)

source code 

Returns a template of the given name

Tries to retrieve a template of the given name from the webservice. If you are trying to fetch a private template (ie. one you made yourself and is not available to others) then you may need to authenticate

Parameters:
  • name (string) - the template's name
Returns:
intermine.query.Template
Raises:

get_results(self, path, params, rowformat, view)

source code 

Return an Iterator over the rows of the results

This method is called internally by the query objects when they are called to get results. You will not normally need to call it directly

Parameters:
  • path (string) - The resource path (eg: "/query/results")
  • params (dict) - The query parameters for this request as a dictionary
  • rowformat (string) - One of "dict", "list", "tsv", "csv", "jsonrows", "jsonobjects"
  • view (list) - The output columns
Returns:
intermine.webservice.ResultIterator
Raises:

get_results_list(self, path, params, rowformat, view)

source code 

Return a list of the rows of the results

This method is called internally by the query objects when they are called to get results. You will not normally need to call it directly

Parameters:
  • path (string) - The resource path (eg: "/query/results")
  • params (dict) - The query parameters for this request as a dictionary
  • rowformat (string) - One of "dict", "list", "tsv", "csv", "jsonrows", "jsonobjects"
  • view (list) - The output columns
Returns:
a list of rows of data
Raises:

Property Details [hide private]

version

Returns the webservice version

The version specifies what capabilities a specific webservice provides. The most current version is 3

may raise ServiceError: if the version cannot be fetched

Get Method:
unreachable.version(self) - The version specifies what capabilities a specific webservice provides.
Type:
int

release

Returns the datawarehouse release

Service.release → string

The release is an arbitrary string used to distinguish releases of the datawarehouse. This usually coincides with updates to the data contained within. While a string, releases usually sort in ascending order of recentness (eg: "release-26", "release-27", "release-28"). They can also have less machine readable meanings (eg: "beta")

Get Method:
unreachable.release(self) - Service.release → string
Type:
string

templates

The dictionary of templates from the webservice

Service.templates → dict(intermine.query.Template|string)

For efficiency's sake, Templates are not parsed until they are required, and until then they are stored as XML strings. It is recommended that in most cases you would want to use Service.get_template.

You can use this property however to test for template existence though:

if name in service.templates:
   template = service.get_template(name)
Get Method:
unreachable.templates(self) - Service.templates → dict(intermine.query.Template|string)
Type:
dict

model

The data model for the webservice you are querying

Service.model → intermine.model.Model

This is used when constructing queries to provide them with information on the structure of the data model they are accessing. You are very unlikely to want to access this object directly.

raises ModelParseError: if the model cannot be read

Get Method:
unreachable.model(self) - Service.model → intermine.model.Model
Type:
intermine.model.Model