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)
   ...

 new_list = service.create_list("some/file/with.ids", "Gene")
 list_on_server = service.get_list("On server")
 in_both = new_list & list_on_server
 in_both.name = "Intersection of these lists"
 for row in in_both.to_attribute_query().results():
   do_something_with(row)
   ...

OVERVIEW

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

For list management information, see ListManager.

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

List is a saved result set containing a set of objects previously identified in the database. Lists can be created and managed using this client library.


See Also: intermine.query

Instance Methods [hide private]
 
__init__(self, root, username=None, password=None, token=None)
Construct a connection to a webservice:
source code
 
__getattribute__(self, name)
x.__getattribute__('name') <==> x.name
source code
 
__getattr__(self, name) source code
 
__del__(self) source code
 
new_query(self, root=None)
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, cld=None)
This method is called internally by the query objects when they are called to get results.
source code

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

Class Variables [hide private]
  QUERY_PATH = '/query/results'
  QUERY_LIST_UPLOAD_PATH = '/query/tolist/json'
  QUERY_LIST_APPEND_PATH = '/query/append/tolist/json'
  MODEL_PATH = '/model'
  TEMPLATES_PATH = '/templates/xml'
  TEMPLATEQUERY_PATH = '/template/results'
  VERSION_PATH = '/version'
  USER_AGENT = 'WebserviceInterMinePerlAPIClient'
  LIST_PATH = '/lists/json'
  LIST_CREATION_PATH = '/lists/json'
  LIST_RENAME_PATH = '/lists/rename/json'
  LIST_APPENDING_PATH = '/lists/append/json'
  SAVEDQUERY_PATH = '/savedqueries/xml'
  RELEASE_PATH = '/version/release'
  SCHEME = 'http://'
  LIST_MANAGER_METHODS = frozenset(['create_list', 'delete_lists...
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, token=None)
(Constructor)

source code 

Constructor

Construct a connection to a webservice:

   url = "http://www.flymine.org/query/service"

   # An unauthenticated connection - access to all public data
   service = Service(url)

   # An authenticated connection - access to private and public data
   service = Service(url, token="ABC123456")
Parameters:
  • root - the root url of the webservice (required)
  • username - your login name (optional)
  • password - your password (required if a username is given)
  • token - your API access token(optional - used in preference to username and password)
Raises:
  • ServiceError - if the version cannot be fetched and parsed
  • ValueError - if a username is supplied, but no password

    There are two alternative authentication systems supported by InterMine webservices. The first is username and password authentication, which is supported by all webservices. Newer webservices (version 6+) also support API access token authentication, which is the recommended system to use. Token access is more secure as you will never have to transmit your username or password, and the token can be easily changed or disabled without changing your webapp login details.

Overrides: object.__init__

__getattribute__(self, name)

source code 

x.__getattribute__('name') <==> x.name

Overrides: object.__getattribute__
(inherited documentation)

new_query(self, root=None)

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, cld=None)

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 "rr", "dict", "list", "tsv", "csv", "jsonrows", "jsonobjects"
  • view (list) - The output columns
Returns:
intermine.webservice.ResultIterator
Raises:

Class Variable Details [hide private]

LIST_MANAGER_METHODS

Value:
frozenset(['create_list',
           'delete_lists',
           'get_all_list_names',
           'get_all_lists',
           'get_list',
           'get_list_count',
           'l'])

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