pyUSIrest package

Submodules

pyUSIrest.auth module

Created on Thu May 24 15:46:37 2018

@author: Paolo Cozzi <cozzi@ibba.cnr.it>

class pyUSIrest.auth.Auth(user=None, password=None, token=None)

Bases: object

Deal with EBI AAP tokens. Starts from a token object or by providing user credentials. It parse token and provide methods like checking expiration times.

auth_url

Default url for EBI AAP.

Type:str

expire

when token expires

Type:datetime.datetime

issued

when token was requested

Type:datetime.datetime

header

token header read by python_jwt.process_jwt

Type:dict

claims

token claims read by python_jwt.process_jwt

Type:dict

__init__(user=None, password=None, token=None)

Instantiate a new python EBI AAP Object. You can generate a new object providing both user and password, or by passing a valid token string

Parameters:

• user (str) – your aap username
• password (str) – your password
• token (str) – a valid EBI AAP jwt token

auth_url = None

get_domains()

Returns a list of domain managed by this object

Returns:a list of managed domains Return type:list

get_duration()

Get token remaining time before expiration

Returns:remaining time as timedelta object Return type:datetime.timedelta

is_expired()

Return True if token is exipired, False otherwise

Returns:True if token is exipired Return type:bool

token

Get/Set token as a string

pyUSIrest.client module

Created on Thu Dec 19 16:28:46 2019

@author: Paolo Cozzi <paolo.cozzi@ibba.cnr.it>

class pyUSIrest.client.Client(auth)

Bases: object

A class to deal with EBI submission API. It perform request modelling user token in request headers. You need to call this class after instantiating an Auth object:

import getpass
from pyUSIrest.auth import Auth
from pyUSIrest.client import Client
auth = Auth(user=<you_aap_user>, password=getpass.getpass())
client = Client(auth)
response = client.get("https://submission-test.ebi.ac.uk/api/")

headers

default headers for requests

Type:dict

last_response

last response object read by this class

Type:requests.Response

last_satus_code

last status code read by this class

Type:int

session

a session object

Type:request.Session

auth

a pyUSIrest Auth object

Type:Auth

__init__(auth)

Instantiate the class

Parameters:auth (Auth) – a valid Auth object

auth

Get/Set Auth object

check_headers(headers=None)

Checking headers and token

Parameters:headers (dict) – custom header for request Returns:an update headers tocken Return type:headers (dict)

check_status(response, expected_status=200)

Check response status. See HTTP status codes

Parameters:

• response (requests.Reponse) – the reponse returned by requests
• method –

delete(url, headers={}, params={})

Generic DELETE method

Parameters:

• url (str) – url to request
• headers (dict) – custom header for request
• params (dict) – custom params for request

Returns:

a response object

Return type:

requests.Response

get(url, headers={}, params={})

Generic GET method

Parameters:

• url (str) – url to request
• headers (dict) – custom headers for get request
• params (dict) – custom params for get request

Returns:

a response object

Return type:

requests.Response

headers = {'Accept': 'application/hal+json', 'User-Agent': 'pyUSIrest 0.3.1'}

patch(url, payload={}, headers={}, params={})

Generic PATCH method

Parameters:

• url (str) – url to request
• payload (dict) – data to send
• headers (dict) – custom header for request
• params (dict) – custom params for request

Returns:

a response object

Return type:

requests.Response

post(url, payload={}, headers={}, params={})

Generic POST method

Parameters:

• url (str) – url to request
• payload (dict) – data to send
• headers (dict) – custom header for request
• params (dict) – custom params for request

Returns:

a response object

Return type:

requests.Response

put(url, payload={}, headers={}, params={})

Generic PUT method

Parameters:

• url (str) – url to request
• payload (dict) – data to send
• params (dict) – custom params for request
• headers (dict) – custom header for request

Returns:

a response object

Return type:

requests.Response

class pyUSIrest.client.Document(auth=None, data=None)

Bases: pyUSIrest.client.Client

Base class for pyUSIrest classes. It models common methods and attributes by calling Client and reading json response from biosample API

_link

_links data read from USI response

Type:dict

_embeddedd

_embedded data read from USI response

Type:dict

page

page data read from USI response

Type:dict

name

name of this object

Type:str

data

data from USI read with response.json()

Type:dict

__init__(auth=None, data=None)

Instantiate the class

Parameters:auth (Auth) – a valid Auth object

classmethod clean_url(url)

Remove stuff like {?projection} from url

Parameters:url (str) – a string url Returns:the cleaned url Return type:str

follow_self_url()

Follow self url and update class attributes. For instance:

document.follow_self_url()

will reload document instance by requesting with Client.get() using document.data['_links']['self']['href'] as url

follow_tag(tag, force_keys=True)

Pick a url from data attribute relying on tag, perform a request and returns a document object. For instance:

document.follow_tag('userSubmissions')

will return a document instance by requesting with Client.get() using document._links['userSubmissions']['href'] as url

Parameters:

• tag (str) – a key from USI response dictionary
• force_keys (bool) – set a new class attribute if not present

Returns:

a document object

Return type:

Document

get(url, force_keys=True)

Override the Client.get method and read data into object:

document = Document(auth)
document.get(settings.ROOT_URL + "/api/")

Parameters:

• url (str) – url to request
• force_keys (bool) – If True, define a new class attribute from data keys

Returns:

a response object

Return type:

requests.Response

paginate()

Follow all the pages. Return an iterator of document objects

Parameters:response (requests.Response) – a response object Yields:Document – a new Document instance

read_data(data, force_keys=False)

Read data from a dictionary object and set class attributes

Parameters:

• data (dict) – a data dictionary object read with response.json()
• force_keys (bool) – If True, define a new class attribute from data keys

classmethod read_url(auth, url)

Read a url and returns a Document object

Parameters:

• auth (Auth) – an Auth object to pass to result
• url (str) – url to request

Returns:

a document object

Return type:

Document

pyUSIrest.client.is_date(string, fuzzy=False)

Return whether the string can be interpreted as a date.

Parameters:

• string – str, string to check for date
• fuzzy – bool, ignore unknown tokens in string if True

pyUSIrest.exceptions module

Created on Fri Jan 10 16:44:49 2020

@author: Paolo Cozzi <paolo.cozzi@ibba.cnr.it>

exception pyUSIrest.exceptions.NotReadyError

Bases: RuntimeError

Raised when doing stuff on not ready data (ex finalizing a Submission after validation)

exception pyUSIrest.exceptions.TokenExpiredError

Bases: RuntimeError

Raised when token expires while using pyUSIrest

exception pyUSIrest.exceptions.USIConnectionError

Bases: ConnectionError

Deal with connection issues with API

exception pyUSIrest.exceptions.USIDataError

Bases: Exception

Deal with issues in USI data format

pyUSIrest.settings module

Created on Mon Nov 18 11:47:42 2019

@author: Paolo Cozzi <paolo.cozzi@ibba.cnr.it>

pyUSIrest.usi module

Created on Thu May 24 16:41:31 2018

@author: Paolo Cozzi <cozzi@ibba.cnr.it>

class pyUSIrest.usi.Domain(auth, data=None)

Bases: pyUSIrest.client.Document

A class to deal with AAP domain objects

name

domain name

Type:str

data

data (dict): data from AAP read with response.json()

Type:dict

domainName

AAP domainName

Type:str

domainDesc

AAP domainDesc

Type:str

domainReference

AAP domainReference

Type:str

link

links data read from AAP response

Type:dict

__init__(auth, data=None)

Instantiate the class

Parameters:

• auth (Auth) – a valid Auth object
• data (dict) – instantiate the class from a dictionary of user data

create_profile(attributes={})

Create a profile for this domain

Parameters:attributes (dict) – a dictionary of attributes

users

Get users belonging to this domain

class pyUSIrest.usi.Root(auth)

Bases: pyUSIrest.client.Document

Models the USI API Root endpoint

api_root

The base URL for API endpoints

Type:str

__init__(auth)

Instantiate the class

Parameters:auth (Auth) – a valid Auth object

api_root = None

get_submission_by_name(submission_name)

Got a specific submission object by providing its name

Parameters:submission_name (str) – input submission name Returns:The desidered submission as instance Return type:Submission

get_team_by_name(team_name)

Get a Team object by name

Parameters:team_name (str) – the name of the team Returns:a team object Return type:Team

get_user_submissions(status=None, team=None)

Follow the userSubmission url and returns all submission owned by the user

Parameters:

• status (str) – filter user submissions using this status
• team (str) – filter user submissions belonging to this team

Returns:

A list of Submission objects

Return type:

list

get_user_teams()

Follow userTeams url and returns all teams belonging to user

Yields:Team – a team object

class pyUSIrest.usi.Sample(auth, data=None)

Bases: pyUSIrest.usi.TeamMixin, pyUSIrest.client.Document

A class to deal with USI Samples

alias

The sample alias (used to reference the same object)

Type:str

team

team data

Type:dict

title

sample title

Type:str

description

sample description

Type:str

attributes

sample attributes

Type:dict

sampleRelationships

relationship between samples

Type:list

taxonId

taxon id

Type:int

taxon

taxon name

Type:str

releaseDate

when this sample will be relased to public

Type:str

createdDate

created date

Type:str

lastModifiedDate

last modified date

Type:str

createdBy

user_id who create this sample

Type:str

lastModifiedBy

last user_id who modified this sample

Type:str

accession

the biosample_id after submission to USI

Type:str

__init__(auth, data=None)

Instantiate the class

Parameters:

• auth (Auth) – a valid Auth object
• data (dict) – instantiate the class from a dictionary of user data

delete()

Delete this instance from a submission

get_validation_result()

Return validation results for submission

Returns:the ValidationResult of this sample Return type:ValidationResult

has_errors(ignorelist=[])

Return True if validation results throw an error

Parameters:ignorelist (list) – ignore errors in these databanks Returns:True if sample has an errors in one or more databank Return type:bool

patch(sample_data)

Update sample by patching data with Client.patch()

Parameters:sample_data (dict) – sample data to update

read_data(data, force_keys=False)

Read data from a dictionary object and set class attributes

Parameters:

• data (dict) – a data dictionary object read with response.json()
• force_keys (bool) – If True, define a new class attribute from data keys

reload()

call Document.follow_self_url() and reload class attributes

class pyUSIrest.usi.Submission(auth, data=None)

Bases: pyUSIrest.usi.TeamMixin, pyUSIrest.client.Document

A class to deal with USI Submissions

id

submission id (name() for compatibility)

Type:str

createdDate

created date

Type:str

lastModifiedDate

last modified date

Type:str

lastModifiedBy

last user_id who modified this submission

Type:str

submissionStatus

submission status

Type:str

submitter

submitter data

Type:dict

createdBy

user_id who create this submission

Type:str

submissionDate

date when this submission is submitted to biosample

Type:str

__init__(auth, data=None)

Instantiate the class

Parameters:

• auth (Auth) – a valid Auth object
• data (dict) – instantiate the class from a dictionary of user data

check_ready()

Test if a submission can be submitted or not (Must have completed validation processes)

Returns:True if ready for submission Return type:bool

create_sample(sample_data)

Create a sample from a dictionary

Parameters:sample_data (dict) – a dictionary of data Returns:a Sample object Return type:Sample

delete()

Delete this submission instance from USI

finalize(ignorelist=[])

Finalize a submission to insert data into biosample

Parameters:ignorelist (list) – ignore samples with errors in these databanks Returns:output of finalize submission as a Document object Return type:Document

get_samples(status=None, has_errors=None, ignorelist=[])

Returning all samples as a list. Can filter by errors and error types:

# returning samples with errors in other checks than Ena
submission.get_samples(has_errors=True, ignorelist=['Ena'])

# returning samples which validation is still in progress
submission.get_samples(status='Pending')

Get all sample with errors in other fields than Ena databank

Parameters:

• status (str) – filter samples by validation status (Pending, Complete)
• has_errors (bool) – filter samples with errors or none
• ingnore_list (list) – a list of errors to ignore

Yields:

Sample – a Sample object

get_status()

Count validation statues for submission

Returns:A counter object for different validation status Return type:collections.Counter

get_validation_results()

Return validation results for submission

Yields:ValidationResult – a ValidationResult object

has_errors(ignorelist=[])

Count sample errors for a submission

Parameters:ignorelist (list) – ignore samples with errors in these databanks Returns:A counter object for samples with errors and with no errors Return type:collections.Counter

name

Get/Set Submission id

read_data(data, force_keys=False)

Read data from a dictionary object and set class attributes

Parameters:

• data (dict) – a data dictionary object read with response.json()
• force_keys (bool) – If True, define a new class attribute from data keys

reload()

call Document.follow_self_url() and reload class attributes

status

Return submissionStatus attribute. Follow submissionStatus link and update attribute is such attribute is None

Returns:submission status as a string Return type:str

update_status()

Update submissionStatus attribute by following submissionStatus link

class pyUSIrest.usi.Team(auth, data=None)

Bases: pyUSIrest.client.Document

A class to deal with USI Team objects

name

team name

Type:str

data

data (dict): data from USI read with response.json()

Type:dict

__init__(auth, data=None)

Instantiate the class

Parameters:

• auth (Auth) – a valid Auth object
• data (dict) – instantiate the class from a dictionary of user data

create_submission()

Create a new submission

Returns:the new submission as an instance Return type:Submission

get_submissions(status=None)

Follows submission url and get submissions from this team

Parameters:status (str) – filter submission using status Returns:A list of Submission objects Return type:list

class pyUSIrest.usi.TeamMixin

Bases: object

__init__()

Instantiate the class

team

Get/Set team name

class pyUSIrest.usi.User(auth, data=None)

Bases: pyUSIrest.client.Document

Deal with EBI AAP endpoint to get user information

name

Output of Auth.claims['nickname']

Type:str

data

data (dict): data from AAP read with response.json()

Type:dict

userName

AAP username

Type:str

email

AAP email

Type:str

userReference

AAP userReference

Type:str

__init__(auth, data=None)

Instantiate the class

Parameters:

• auth (Auth) – a valid Auth object
• data (dict) – instantiate the class from a dictionary of user data

add_user_to_team(user_id, domain_id)

Add a user to a team

Parameters:

• user_id (str) – the required user_id
• domain_id (str) –

Returns:

the updated Domain object

Return type:

Domain

create_team(description, centreName)

Create a new team

Parameters:

• description (str) – team description
• centreName (str) – team center name

Returns:

the new team as a Team instance

Return type:

Team

classmethod create_user(user, password, confirmPwd, email, full_name, organisation)

Create another user into biosample AAP and return its ID

Parameters:

• user (str) – the new username
• password (str) – the user password
• confirmPwd (str) – the user confirm password
• email (str) – the user email
• full_name (str) – Full name of the user
• organisation (str) – organisation name

Returns:

the new user_id as a string

Return type:

str

get_domain_by_name(domain_name)

Get a domain by name

Parameters:domain_name (str) – the required team Returns:the desidered Domain instance Return type:Domain

get_domains()

Get domains belonging to this instance

Returns:a list of Domain objects Return type:list

get_my_id()

Get user id using own credentials, and set userReference attribute

Returns:the user AAP reference as a string Return type:str

get_team_by_name(team_name)

Get a team by name

Parameters:team_name (str) – the required team Returns:the desidered Team instance Return type:Team

get_teams()

Get teams belonging to this instance

Returns:a list of Team objects Return type:list

get_user_by_id(user_id)

Get a User object by user_id

Parameters:user_id (str) – the required user_id Returns:a user object Return type:User

user_url = None

class pyUSIrest.usi.ValidationResult(auth, data=None)

Bases: pyUSIrest.client.Document

__init__(auth, data=None)

Instantiate the class

Parameters:

• auth (Auth) – a valid Auth object
• data (dict) – instantiate the class from a dictionary of user data

has_errors(ignorelist=[])

Return True if validation has errors

Parameters:ignorelist (list) – ignore errors in these databanks Returns:True if sample has errors for at least one databank Return type:bool

pyUSIrest.usi.check_relationship(sample_data, team)

Check relationship and add additional fields if missing

pyUSIrest.usi.check_releasedate(sample_data)

Add release date to sample data if missing

Module contents

Top-level package for Python EBI submission REST API.