Lims object

class pyclarity_lims.lims.Lims(baseuri, username, password, version='v2')

Bases: object

LIMS interface through which all searches can be performed and Entity instances are retrieved.

Parameters:

• baseuri – Base URI for the GenoLogics server, excluding the ‘api’ or version parts!
• username – The account name of the user to login as.
• password – The password for the user account to login as.
• version – The optional LIMS API version, by default ‘v2’

Example:

Lims('https://claritylims.example.com', 'username' , 'Pa55w0rd')

VERSION = 'v2'

check_version()

Raise ValueError if the version for this interface does not match any of the versions given for the API.

create_batch(klass, list_kwargs)

Create using the batch create endpoint. It is only available for Sample and Container entities.

Parameters:

• klass – The class to use when creating the entity (Sample or Container)
• list_kwargs – A list of dictionary where each dictionary will be used to create a instance of the klass. Elements of the dictionary should match the keyword argument in the create method of Sample or Container

Returns:

A list of the created entities in the same order as the list of kwargs.

get(uri, params={})

GET data from the URI. It checks the status and return the text of response as an ElementTree.

Parameters:

• uri – the uri to query
• params – dict containing the query parameters

Returns:

the text of the response as an ElementTree

get_artifacts(name=None, type=None, process_type=None, artifact_flag_name=None, working_flag=None, qc_flag=None, sample_name=None, samplelimsid=None, artifactgroup=None, containername=None, containerlimsid=None, reagent_label=None, udf={}, udtname=None, udt={}, start_index=None, nb_pages=-1, resolve=False)

Get a list of artifacts, filtered by keyword arguments.

Parameters:

• name – Artifact name, or list of names.
• type – Artifact type, or list of types.
• process_type – Produced by the process type, or list of types.
• artifact_flag_name – Tagged with the genealogy flag, or list of flags.
• working_flag – Having the given working flag; boolean.
• qc_flag – Having the given QC flag: UNKNOWN, PASSED, FAILED.
• sample_name – Related to the given sample name.
• samplelimsid – Related to the given sample id.
• artifactgroup – Belonging to the artifact group (experiment in client).
• containername – Residing in given container, by name, or list.
• containerlimsid – Residing in given container, by LIMS id, or list.
• reagent_label – having attached reagent labels.
• udf – dictionary of UDFs with ‘UDFNAME[OPERATOR]’ as keys.
• udtname – UDT name, or list of names.
• udt – dictionary of UDT UDFs with ‘UDTNAME.UDFNAME[OPERATOR]’ as keys and a string or list of strings as value.
• start_index – first element to retrieve; start at first element if None.
• nb_pages – number of page to iterate over. The page size is 500 by default unless configured otherwise in your LIMS. 0 or negative numbers returns all pages.
• resolve – Send a batch query to the lims to get the content of all artifacts retrieved

get_batch(instances, force=False)

Get the content of a set of instances using the efficient batch call.

Returns the list of requested instances in arbitrary order, with duplicates removed (duplicates=entities occurring more than once in the instances argument).

For Artifacts it is possible to have multiple instances with the same LIMSID but different URI, differing by a query parameter ?state=XX. If state is not given for an input URI, a state is added in the data returned by the batch API. In this case, the URI of the Entity object is not updated by this function (this is similar to how Entity.get() works). This may help with caching.

The batch request API call collapses all requested Artifacts with different state into a single result with state equal to the state of the Artifact occurring at the last position in the list.

Parameters:

• instances – List of instances children of Entity
• force – optional argument to force the download of already cached instances

get_container_types(name=None, start_index=None, nb_pages=-1, add_info=False)

Get a list of container types, filtered by keyword arguments.

Parameters:

• name – name of the container type or list of names.
• start_index – first element to retrieve; start at first element if None.
• nb_pages – number of page to iterate over. The page size is 500 by default unless configured otherwise in your LIMS. 0 or negative numbers returns all pages.
• add_info – Change the return type to a tuple where the first element is normal return and the second is a dict of additional information provided in the query.

get_containers(name=None, type=None, state=None, last_modified=None, udf={}, udtname=None, udt={}, start_index=None, nb_pages=-1, add_info=False)

Get a list of containers, filtered by keyword arguments.

Parameters:

• name – Containers name, or list of names.
• type – Container type, or list of types.
• state – Container state: Empty, Populated, Discarded, Reagent-Only.
• last_modified – Since the given ISO format datetime.
• udf – dictionary of UDFs with ‘UDFNAME[OPERATOR]’ as keys.
• udtname – UDT name, or list of names.
• udt – dictionary of UDT UDFs with ‘UDTNAME.UDFNAME[OPERATOR]’ as keys and a string or list of strings as value.
• start_index – first element to retrieve; start at first element if None.
• nb_pages – number of page to iterate over. The page size is 500 by default unless configured otherwise in your LIMS. 0 or negative numbers returns all pages.
• add_info – Change the return type to a tuple where the first element is normal return and the second is a dict of additional information provided in the query.

get_file_contents(id=None, uri=None, encoding=None, crlf=False, binary=False)

Download and returns the contents of the file of <ID> or <uri>.

Parameters:

• id – the id of the file to retrieve.
• uri – the uri of the file to retrieve.
• encoding – When retrieve text file, this option can specify the encoding of the file.
• crlf – When set to True the text file will be replace \r\n by \n.
• binary – When set to True the file content is returned as a binary stream.

Returns:

The file content in the format specify by the parameters.

get_labs(name=None, last_modified=None, udf={}, udtname=None, udt={}, start_index=None, nb_pages=-1, add_info=False)

Get a list of labs, filtered by keyword arguments.

Parameters:

• name – Lab name, or list of names.
• last_modified – Since the given ISO format datetime.
• udf – dictionary of UDFs with ‘UDFNAME[OPERATOR]’ as keys.
• udtname – UDT name, or list of names.
• udt – dictionary of UDT UDFs with ‘UDTNAME.UDFNAME[OPERATOR]’ as keys and a string or list of strings as value.
• start_index – first element to retrieve; start at first element if None.
• nb_pages – number of page to iterate over. The page size is 500 by default unless configured otherwise in your LIMS. 0 or negative numbers returns all pages.
• add_info – Change the return type to a tuple where the first element is normal return and the second is a dict of additional information provided in the query.

get_process_types(displayname=None, add_info=False)

Get a list of process types with the specified name.

Parameters:

• displayname – The name the process type
• add_info – Change the return type to a tuple where the first element is normal return and the second is a dict of additional information provided in the query.

get_processes(last_modified=None, type=None, inputartifactlimsid=None, techfirstname=None, techlastname=None, projectname=None, udf={}, udtname=None, udt={}, start_index=None, nb_pages=-1)

Get a list of processes, filtered by keyword arguments.

Parameters:

• last_modified – Since the given ISO format datetime.
• type – Process type, or list of types.
• inputartifactlimsid – Input artifact LIMS id, or list of.
• udf – dictionary of UDFs with ‘UDFNAME[OPERATOR]’ as keys.
• udtname – UDT name, or list of names.
• udt – dictionary of UDT UDFs with ‘UDTNAME.UDFNAME[OPERATOR]’ as keys and a string or list of strings as value.
• techfirstname – First name of researcher, or list of.
• techlastname – Last name of researcher, or list of.
• projectname – Name of project, or list of.
• start_index – first element to retrieve; start at first element if None.
• nb_pages – number of page to iterate over. The page size is 500 by default unless configured otherwise in your LIMS. 0 or negative numbers returns all pages.

get_projects(name=None, open_date=None, last_modified=None, udf={}, udtname=None, udt={}, start_index=None, nb_pages=-1, add_info=False)

Get a list of projects, filtered by keyword arguments.

Parameters:

• name – Project name, or list of names.
• open_date – Since the given ISO format date.
• last_modified – Since the given ISO format datetime.
• udf – dictionary of UDFs with ‘UDFNAME[OPERATOR]’ as keys.
• udtname – UDT name, or list of names.
• udt – dictionary of UDT UDFs with ‘UDTNAME.UDFNAME[OPERATOR]’ as keys and a string or list of strings as value.
• start_index – first element to retrieve; start at first element if None.
• nb_pages – number of page to iterate over. The page size is 500 by default unless configured otherwise in your LIMS. 0 or negative numbers returns all pages.
• add_info – Change the return type to a tuple where the first element is normal return and the second is a dict of additional information provided in the query.

get_protocols(name=None, add_info=False)

Get a list of existing protocols on the system.

Parameters:

• name – The name the protocol
• add_info – Change the return type to a tuple where the first element is normal return and the second is a dict of additional information provided in the query.

get_reagent_kits(name=None, start_index=None, nb_pages=-1, add_info=False)

Get a list of reagent kits, filtered by keyword arguments.

Parameters:

• name – reagent kit name, or list of names.
• start_index – first element to retrieve; start at first element if None.
• nb_pages – number of page to iterate over. The page size is 500 by default unless configured otherwise in your LIMS. 0 or negative numbers returns all pages.
• add_info – Change the return type to a tuple where the first element is normal return and the second is a dict of additional information provided in the query.

get_reagent_lots(name=None, kitname=None, number=None, start_index=None, nb_pages=-1)

Get a list of reagent lots, filtered by keyword arguments.

Parameters:

• name – reagent kit name, or list of names.
• kitname – name of the kit this lots belong to
• number – lot number or list of lot number
• start_index – first element to retrieve; start at first element if None.
• nb_pages – number of page to iterate over. The page size is 500 by default unless configured otherwise in your LIMS. 0 or negative numbers returns all pages.

get_reagent_types(name=None, start_index=None, nb_pages=-1, add_info=False)

Get a list of reagent types, filtered by keyword arguments.

Parameters:

• name – Reagent type name, or list of names.
• start_index – first element to retrieve; start at first element if None.
• nb_pages – number of page to iterate over. The page size is 500 by default unless configured otherwise in your LIMS. 0 or negative numbers returns all pages.
• add_info – Change the return type to a tuple where the first element is normal return and the second is a dict of additional information provided in the query.

get_researchers(firstname=None, lastname=None, username=None, last_modified=None, udf={}, udtname=None, udt={}, start_index=None, nb_pages=-1, add_info=False)

Get a list of researchers, filtered by keyword arguments.

Parameters:

• firstname – Researcher first name, or list of names.
• lastname – Researcher last name, or list of names.
• username – Researcher account name, or list of names.
• last_modified – Since the given ISO format datetime.
• udf – dictionary of UDFs with ‘UDFNAME[OPERATOR]’ as keys.
• udtname – UDT name, or list of names.
• udt – dictionary of UDT UDFs with ‘UDTNAME.UDFNAME[OPERATOR]’ as keys and a string or list of strings as value.
• start_index – first element to retrieve; start at first element if None.
• nb_pages – number of page to iterate over. The page size is 500 by default unless configured otherwise in your LIMS. 0 or negative numbers returns all pages.
• add_info – Change the return type to a tuple where the first element is normal return and the second is a dict of additional information provided in the query.

get_sample_number(name=None, projectname=None, projectlimsid=None, udf={}, udtname=None, udt={}, start_index=None, nb_pages=-1)

Gets the number of samples matching the query without fetching every sample, so it should be faster than len(get_samples())

get_samples(name=None, projectname=None, projectlimsid=None, udf={}, udtname=None, udt={}, start_index=None, nb_pages=-1)

Get a list of samples, filtered by keyword arguments.

Parameters:

• name – Sample name, or list of names.
• projectlimsid – Samples for the project of the given LIMS id.
• projectname – Samples for the project of the name.
• udf – dictionary of UDFs with ‘UDFNAME[OPERATOR]’ as keys.
• udtname – UDT name, or list of names.
• udt – dictionary of UDT UDFs with ‘UDTNAME.UDFNAME[OPERATOR]’ as keys and a string or list of strings as value.
• start_index – first element to retrieve; start at first element if None.
• nb_pages – number of page to iterate over. The page size is 500 by default unless configured otherwise in your LIMS. 0 or negative numbers returns all pages.

get_udfs(name=None, attach_to_name=None, attach_to_category=None, start_index=None, nb_pages=-1, add_info=False)

Get a list of udfs, filtered by keyword arguments.

Parameters:

• name – name of udf
• attach_to_name – item in the system, to wich the udf is attached, such as Sample, Project, Container, or the name of a process.
• attach_to_category – If ‘attach_to_name’ is the name of a process, such as ‘CaliperGX QC (DNA)’, then you need to set attach_to_category=’ProcessType’. Must not be provided otherwise.
• start_index – first element to retrieve; start at first element if None.
• nb_pages – number of page to iterate over. The page size is 500 by default unless configured otherwise in your LIMS. 0 or negative numbers returns all pages.
• add_info – Change the return type to a tuple where the first element is normal return and the second is a dict of additional information provided in the query.

get_uri(*segments, **query)

Return the full URI given the path segments and optional query.

Parameters:

• segments – arguments creating the uri
• query – kwargs creating the query

get_workflows(name=None, add_info=False)

Get a list of existing workflows on the system.

Parameters:

• name – The name of the workflow you’re looking for
• add_info – Change the return type to a tuple where the first element is normal return and the second is a dict of additional information provided in the query.

parse_response(response, accept_status_codes=[200])

Parse the XML returned in the response. Raise an HTTP error if the response status is not 200.

post(uri, data, params={})

POST the serialized XML to the given URI. Return the response XML as an ElementTree.

put(uri, data, params={})

PUT the serialized XML to the given URI. Return the response XML as an ElementTree.

put_batch(instances)

Update multiple instances using a single batch request.

Parameters:instances – List of instances children of Entity

route_artifacts(artifact_list, workflow_uri=None, stage_uri=None, unassign=False)

Take a list of artifacts and queue them to the stage specified by the stage uri. If a workflow uri is specified, the artifacts will be queued to the first stage of the workflow.

Parameters:

• artifact_list – list of Artifacts.
• workflow_uri – The uri of the workflow.
• stage_uri – The uri of the stage.
• unassign – If True, then the artifact will be removed from the queue instead of added.

tostring(etree)

Return the ElementTree contents as a UTF-8 encoded XML string.

upload_new_file(entity, file_to_upload)

Upload a file and attach it to the provided entity.

validate_response(response, accept_status_codes=[200])

Parse the XML returned in the response. Raise an HTTP error if the response status is not one of the specified accepted status codes.

write(outfile, etree)

Write the ElementTree contents as UTF-8 encoded XML to the open file.