Getting Started with the Guru SDK

The Guru SDK is a Python module that wraps our API's functionality. Writing a script to invite users to your team and assign them the groups is just a few lines of code.

The SDK is available on github: https://github.com/guruhq/py-sdk and there's a full reference of the commands it provides.

Installing the SDK

In a terminal, run this command to install the SDK:

pip install git+https://github.com/guruhq/py-sdk.git

The SDK is hosted through Github but you don't need a Github account to install it. If you're having trouble running pip, check these articles for some help: How to install pip to manage PyPI packages easily How to Install Python PIP on Windows, Mac, and Linux.

Generating an API Token

You'll need an API token to use the SDK, so check this Guru Help Center article for details on how to get your API token.

Using the SDK

The SDK provides its functionality through the Guru class in the guru module. An instance of the Guru class is what wraps all of your API calls -- when creating the object, you give it your username and API token and it uses these for every call it makes.

Here's an example:

import guru
g = guru.Guru("[email protected]", "abcdabcd-abcd-abcd-abcd-abcdabcdabcd")

This imports the guru module and instantiates the Guru object. You can provide your username and API token as parameters or you can put them in the GURU_USER and GURU_TOKEN environment variables. Environment variables can be handy for a few reasons:

  1. If you generate a new API token you just have to update it in one place.
  2. If you're sharing your scripts or checking the code into github, you don't have to worry about your token being sent around.
  3. When you start a new script, you don't have to copy and paste your API token into it -- just writing guru.Guru() will work!

Expanding on this, here's how we'd use the Guru object to get a list of all cards in a particular collection:

import guru
g = guru.Guru("[email protected]", "abcdabcd-abcd-abcd-abcd-abcdabcdabcd")
cards = g.find_cards(collection="HR")
print ("There are %s cards in the HR collection." % len(cards))

This handles pagination for you and gets all cards in the HR collection.

Reading card content

Let's expand this example a little more. Suppose you want to scan all HR cards and see what Dropbox files you link to. Here's how you'd do that:

import guru
g = guru.Guru()

for card in g.find_cards(collection="HR"):
  for link in card.doc.select("a[href*=dropbox.com]"):
    print card.collection.name, card.title, card.url, link.attrs.get("href")
  • find_cards returns a list of Card objects.
  • Content is stored as HTML, so the Card object uses BeautifulSoup to parse this content so you can use card.doc to easily work with the card's content.
  • We can use card.doc.select() with a CSS selector to find specific elements in the card -- in this case, we're looking for links to any dropbox.com URL.
  • We can access other properties of cards, like card.title or card.collection.name.