The Evernote SDK for Python Quick-start Guide

The purpose of this guide is describing how to download, install, and configure the Evernote SDK for Python, as well as demonstrate how it’s used. If everything goes as planned, this shouldn’t take more than 10 minutes to complete.

• What you need

  1. An account on https://sandbox.evernote.com, Evernote’s development server. You’ll be connecting to this server while your application is in development.
  2. An Evernote API key, which consists of two values: a consumer key and a consumer secret. If you don’t have an API key yet, you can get one here.

• Downloading the Evernote SDK for Python

  The Evernote SDK for Python, as well as all other Evernote SDKs, is hosted on GitHub. You can download the SDK as a zip file by clicking the download link at the top of the page. After extracting the archive, run the python setup script to install the library on your system (this will likely require administrative privileges):

  python setup.py install

  This script will install the SDK (along with any dependent modules it needs to run) and place everything in a directory Python knows about so you won’t have to mess with PYTHONPATH before using it.

  Alternately, If you’re using git to manage your project, you can instead install the Evernote SDK for Python as a git submodule by issuing the following commands:

  You can then issue git submodule update whenever a new version of the SDK is released, and the changes will be automatically added to your copy of the SDK. Don’t forget to run the setup.py script after downloading or updating.

  Finally, the Evernote SDK for Python is available via the Python Package Index and can be installed using the pip command:

  pip install evernote

• Testing the SDK

  After completing the installation instructions above, you should now be able to include the Evernote SDK for Python in your project. To test this, run this command at the console to verify that the Evernote classes import without error:

  $ python -c 'from evernote.api.client import EvernoteClient'

  If that runs and quietly exits, you’re ready to go.

• Authentication

  Interacting with the Evernote Cloud API requires an authentication token.

  When your application is in development, you can use a Developer Token. This token behaves exactly like an authentication token retrieved using OAuth, but can be downloaded directly from Sandbox, our development server. This allows the developer to begin integrating with the Evernote Cloud API quickly without first needing to implement the entire OAuth flow:

  Once your application is ready for production, users will need to authenticate with Evernote using OAuth. We strongly recommend using developer tokens during the early stages of development.

  If you’re using Pyramid or Django, definitely check out the sample applications the came with the SDK you downloaded — these samples demonstrate how to build OAuth authentication to Evernote into your application.

• UserStore

  UserStore is an object used to retrieve information about the current user. To create an instance of UserStore, call the get_user_store method from EvernoteClient:

  Note: most of the Evernote API documentation indicates that an authorization token parameter is required for almost all API functions. When you initialize your instance of EvernoteClient with a valid authorization token, this parameter should be omitted in other API calls.

• NoteStore

  NoteStore is used to create, update and delete notes, notebooks and other Evernote data found in a user’s account. Just like with UserStore, creating an instance of NoteStore is as easy as calling EvernoteClient.get_note_store:

• Common Data Types

  Next, let’s talk about some of the common data types you’re likely to find when exploring the Evernote Cloud API:

  1. Types.Note represents a single note in a user’s account.
  2. Types.Notebook represents a notebook in a user’s account.
  3. A Types.Resource instance describes a file (image, PDF or any other type of file) attached to a note. Read more about working with Resource objects here.
  4. Notes can have one or more related instances of Types.Tag attached to them; these are short, textual labels that aid the user in organizing their information within Evernote.

  There are other types you’ll be using as you build your integration; if you haven’t already, it might be worth taking a few minutes to go over the API Specification after you finish with this.

• Common Tasks

  Once you’ve got your application successfully authenticating with Evernote, we can go through a few quick examples of tasks common to most Evernote partners:

  Creating a note

  Creating a new Evernote note is as simple as creating a new instance of Types.Note, adding a title and content and calling NoteStore.createNote:

  This will create the note in the user’s default notebook. If you want to specify a destination notebook, you’ll need assign the notebook’s GUID to note.notebookGuid before calling createNote.

  There are, of course, plenty of other attributes within Types.Note that you can adjust, but that’s the simplest form of the note creation process.

  Creating a notebook

  Notebooks are just as simple to create as notes: make a new Types.Notebook object, give it a name, and call NoteStore.createNotebook:

  This will create a new notebook called “My Notebook”.

• Conclusion

  Now that you’ve got the basics down, it would be a good idea to head over to our documentation page and check out how to perform the various tasks common to developers working with the Evernote API. And, as always, feel free to get in touch if you need any assistance.