ChEMBL python client update

Along with updating ChEMBL web services to the new 2.x version, we've also updated the python client library (chembl_webresource_client). The change was backwards compatible so it's possible that existing users haven't even noticed the change.

As we've already provided examples of using new web services via cURL or using live docs, now it's good time to explain the changes made to the python client.

First of all, if you haven't installed (or updated) it yet, you can do it using Python Package Index:

pip install -U chembl_webresource_client

view raw install.bash hosted with ❤ by GitHub

Now you can access new functionality using the following import statement:

from chembl_webresource_client.new_client import new_client

view raw import.py hosted with ❤ by GitHub

Just as a mild warning, in 0.8.x versions of the client the new part will be called new_client. In 0.9.x it will change the name to client and the old part will be renamed to old_client and deprecated. In 1.0.x the old functionality will be removed completely.

OK, so since we know how to import our new_client object, we can try to do something useful. Let's retrieve some activities. We know, that the new web services introduces filtering, so we can try to get only activities with standard type equal to 'Ki' and with standard value greater or equal 5:

acts = activity.filter(standard_type="Ki").filter(standard_value__gte=5)

view raw act.py hosted with ❤ by GitHub

We've already applied two filters, so you may expect that the client made two requests to server as well (one to get all activities with specified standard type and another one to filter on the standard value). In reality no interaction with server has been performed so far. This is because our client is lazy - but in the good sense. It waits until you are actually trying to use some of the data requested and then tries to perform the most sensible query to the server so you don't have to care.

So If we would like to access the fifth element:

	print acts[5]
	#or loop through all the elements:
	for act in acts:
	...

view raw loop.py hosted with ❤ by GitHub

the client will interact with server and retrieve a chunk of data that is large enough to prevent from hammering the server too frequently. The data is then cached locally, so if you restart your computer and rerun your script all the data will be fetched from the cache (if available).

A careful reader with IT background will notice that our client presents an interface that is very similar to Django QuerySet. This is true, we designed our client to mimic Django ORM behavior by implementing chaining filters and lazy evaluation. You don't have to be a Django expert to see advantages of such approach, but if you do have some experience with Django, you will feel like home.

To cover most important use cases we've created an IPython notebook, comparing the client with the plain requests library approach. The notebook is loaded into myChEMBL so if you have myChEMBL running locally, you can give it a try immediately. If not, just install the client and follow the tutorial below: