Python SDK Tutorial

This tutorial shows how the Python SDK can be used to interface with a Squirro project.

Installation

For installation please follow the Python SDK Installation documentation. If you already have a Python environment set up, then you can install the SquirroClient package with:

pip install SquirroClient

Gathering Information

When working with the Squirro SDK you need to provide a few pieces of information. This section explains how you can get that information.

Cluster

The cluster is the address where your Squirro has been set up. For a /wiki/spaces/BOX/overview setup this is generally http://localhost:8300 or http://box.ip.address. For the cloud version this is generally https://customer.squirro.biz or similar.

See Endpoint Mapping for additional details.

Authentication Token

For this purpose the Squirro API uses authentication tokens. To create such a token:

Open the Squirro web interface and log in as the user you'll want to use for API access.
Open the user dropdown menu on the top right, then click "API Access".
In the resulting screen under "User Token" press "Generate". The text field will then be populated with a token:

If the text field already has a token, then simply copy that value. If you press "Renew" the current token will be invalidated and a new one is created.

Treat this token like you would your account password. The token gives full access to that account.

Project Identifier

When working with projects, for example to search items, the project's identifier is needed. The user interface provides this identifier:

Log into Squirro.
Open the Settings dropdown menu on the top right (wheelbarrow icon) and click "Project Properties".
The Project Identifier is in the resulting screen and can be copied to the clipboard.

Instantiation & Authentication

As a first step, you need to instantiate the SquirroClient class and then authentication.

In the constructor specify the cluster, for authentication use the user authentication token.

from squirro_client import SquirroClient

client = SquirroClient(None, None, cluster='https://next.squirro.net')
client.authenticate(refresh_token='570010…fda74e')

Searching Items

Now with a valid connection you can start searching items in an existing Squirro project. Searches are always done in the context of a project, so use the project identifier and get the most recent 15 items in a project with the following code:

print client.query('l0nz…YgBg')

This will output a result like the following (output reformatted and cut to the first two items for clarity):

{u'count': 15,
 u'eof': False,
 u'items': [{u'abstract': u'\xa0Twitter is bringing...',
             u'body': u'<html><body><img wid...',
             u'created_at': u'2015-03-23T17:03:56',
             u'external_id': u'http://techcrunch.com/?p=1135621',
             u'id': u'S8Eh_0a6SEaQwaoYtE85nQ',
             u'language': u'en',
             u'link': u'http://techcrunch.com/2015/03/23/twitter-teaming-with-foursquare-for-location-tagging-in-tweets/?ncid=rss',
             u'modified_at': u'2015-03-23T17:05:26',
             u'objects': [{u'id': u'vXzfrgmERwy1DAMO_ZBQIw',
                           u'project_id': u'l0nz…YgBg',
                           u'source_ids': [u'8lVtipSSTxu7q-ox1KdCjQ'],
                           u'title': u'default',
                           u'type': u'default'}],
             u'read': False,
             u'related_items': [],
             u'score': 1.0,
             u'sources': [{u'id': u'8lVtipSSTxu7q-ox1KdCjQ',
                           u'link': u'http://feeds.feedburner.com/TechCrunch',
                           u'object_ids': [u'vXzfrgmERwy1DAMO_ZBQIw'],
                           u'provider': u'feed',
                           u'title': u'TechCrunch'}],
             u'starred': False,
             u'thumbler_url': u'd4d…f73/thumb/webshot/52/2d/18/522…5d6.png',
             u'title': u'Twitter Teaming With Foursquare For Location Tagging In Tweets',
             u'webshot_height': 2556,
             u'webshot_url': u'http://webshot.next.squirro.net.s3-website-us-west-1.amazonaws.com/52/2d/18/522…5d6.png',
             u'webshot_width': 4884},
            {u'abstract': u'\xa0Instagram today ann...',
             u'body': u'<html><body><img wid...',
             u'created_at': u'2015-03-23T17:00:43',
             u'external_id': u'http://techcrunch.com/?p=1135559',
             u'id': u'_Tt7lGnWRMKJ4b-p_zHvow',
             u'language': u'en',
             u'link': u'http://techcrunch.com/2015/03/23/instagram-layout/?ncid=rss',
             u'modified_at': u'2015-03-23T17:01:45',
             u'objects': [{u'id': u'vXzfrgmERwy1DAMO_ZBQIw',
                           u'project_id': u'l0nz…YgBg',
                           u'source_ids': [u'8lVtipSSTxu7q-ox1KdCjQ'],
                           u'title': u'default',
                           u'type': u'default'}],
             u'read': False,
             u'related_items': [],
             u'score': 1.0,
             u'sources': [{u'id': u'8lVtipSSTxu7q-ox1KdCjQ',
                           u'link': u'http://feeds.feedburner.com/TechCrunch',
                           u'object_ids': [u'vXzfrgmERwy1DAMO_ZBQIw'],
                           u'provider': u'feed',
                           u'title': u'TechCrunch'}],
             u'starred': False,
             u'thumbler_url': u'260…fd9/thumb/webshot/3f/30/a7/3f3…248.jpg',
             u'title': u'Instagram Launches Layout, Its Own Photo Collage App',
             u'webshot_height': 1244,
             u'webshot_url': u'http://webshot.next.squirro.net.s3-website-us-west-1.amazonaws.com/3f/30/a7/3f3…248.jpg',
             u'webshot_width': 1244}],
 u'next_params': {u'expected_num_results': 3402, u'start': 15},
 u'now': u'2015-03-23T18:01:06',
 u'total': 3402}

Reference

For a full documentation of the Python SDK refer to the Python SDK Reference, specifically SquirroClient, SquirroClient Entities and SquirroClient Users.