Getting started

pyclarity-lims is a module that will help you access your Basespace-clarity REST API by parsing the xml the API returns into Python objects.

Lims connection

To create a Lims connection you’ll need to create a Lims object.

from pyclarity_lims.lims import Lims

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

The Lims instance is the main object that will interact with the REST API and manage all communications. There are two way of accessing information stored in the LIMS:

Searching the Lims

The most common way of accessing data from the LIMS is to first perform searches. For example, retrieving all samples from project1 would be:

samples = l.get_samples(projectname='project1')

This will return a list of all Sample objects that belong to project1.

The functions from pyclarity_lims closely match the API search function from Basespace-clarity REST API. For example get_samples has similar parameters as the samples end point from Basespace-clarity

Retrieving object with their id

In some cases you will know the id or uri of the instance you want to retrieve. In this case you can create the object directly.

Note that you will still need the Lims instance as an argument.

For Example:

from pyclarity_lims.entities import Sample
sample = Sample(l, id='sample_luid')
print(sample.name)

Lazy loading and caching

All entities such as Sample, Artifact or Step are loaded lazily which mean that no query will be sent to the REST API until an attribute of the object is accessed or a method is run. In the code above:

from pyclarity_lims.entities import Sample
sample = Sample(l, id='sample_luid')
# the Sample object has been created but no query have been sent yet
print(sample.name)
# accessing the name of the sample triggers the query

To avoid sending too many queries, all Entities that have been retrieved are also cached which means that once the Entity is retrieved it won’t be queried again unless forced. This makes pyclarity_lims more efficient but also not very well suited for long running process during which the state of the LIMS is likely to change. You can bypass the cache as shown in Make sure to have the up-to-date program status.

Looking beyond

You can look at some Practical Examples There are many other search methods available in the Lims and you can also look at all the classes defined in Entities