API

This chapter covers all API interfaces of the simplenote module.

Historical Simplenote API - Note Object

Prior to the Simperium API a complete note dict object contained the following fields:

{
  key       : (string, note identifier, created by server),
  deleted   : (bool, whether or not note is in trash),
  modifydate: (last modified date, in seconds since epoch),
  createdate: (note created date, in seconds since epoch),
  syncnum   : (integer, number set by server, track note changes),
  version   : (integer, number set by server, track note content changes),
  minversion: (integer, number set by server, minimum version available for note),
  sharekey  : (string, shared note identifier),
  publishkey: (string, published note identifier),
  systemtags: [(Array of strings, some set by server)],
  tags      : [(Array of strings)],
  content   : (string, data content)
}

Simperium API - Note Object

Under Simperium some of the fields were renamed and some were removed. String data also seems to be UTF-8 by default. A Simperium note object looks like this:

{
  deleted         : (bool, whether or not note is in trash),
  modificationDate: (last modified date, in seconds since epoch),
  creationDate    : (note created date, in seconds since epoch),
  version         : (integer, number set by server, track note content changes),
  shareURL        : (string, shared url),
  publishURL      : (string, published note url),
  systemTags      : [(Array of strings, some set by server)],
  tags            : [(Array of strings)],
  content         : (string, data content)
}

It no longer includes the “key” (actually now an “id”, but still not included in the note object).

Howver, Simplenote.py tries to work as a drop in replacement for code that expects the older fields and therefore you can still use the following:

{
  key       : (string, note identifier, created by server),
  deleted   : (bool, whether or not note is in trash),
  modifydate: (last modified date, in seconds since epoch),
  createdate: (note created date, in seconds since epoch),
  version   : (integer, number set by server, track note content changes),
  systemtags: [(Array of strings, some set by server)],
  tags      : [(Array of strings)],
  content   : (string, data content)
}

And simplenote.py will handle conversion to/from the Simperium fields.

Simplenote main class

class simplenote.Simplenote(username, password)

Class for interacting with the simplenote web service

add_note(note)

Wrapper method to add a note

The method can be passed the note as a dict with the content property set, which is then directly send to the web service for creation. Alternatively, only the body as string can also be passed. In this case the parameter is used as content for the new note.

Arguments:

  • note (dict or string): the note to add

Returns:

A tuple (note, status)

  • note (dict): the newly created note

  • status (int): 0 on success and -1 otherwise

authenticate(user, password)

Method to get simplenote auth token

Arguments:

  • User (string): simplenote email address

  • password (string): simplenote password

Returns:

Simplenote API token as string

delete_note(note_id)

Method to permanently delete a note

Arguments:

  • note_id (string): key of the note to trash

Returns:

A tuple (note, status)

  • note (dict): an empty dict or an error message

  • status (int): 0 on success and -1 otherwise

get_note(noteid, version=None)

Method to get a specific note

Arguments:

  • noteid (string): ID of the note to get

  • version (int): optional version of the note to get

Returns:

A tuple (note, status)

  • note (dict): note object

  • status (int): 0 on success and -1 otherwise

get_note_list(data=True, since=None, tags=[])

Method to get the note list

The method can be passed optional arguments to limit the list to notes containing a certain tag, or only updated since a certain Simperium cursor. If omitted a list of all notes is returned.

By default data objects are returned. If data is set to false only keys/ids and versions are returned. An empty data object is inserted for compatibility.

Arguments:

  • tags=[] list of tags as string: return notes that have at least one of these tags

  • since=cursor Simperium cursor as string: return only changes since this cursor

  • data=True If false only return keys/ids and versions

Returns:

A tuple (notes, status)

  • notes (list): A list of note objects with all properties set except

content. - status (int): 0 on success and -1 otherwise

get_token()

Method to retrieve an auth token.

The cached global token is looked up and returned if it exists. If it is None a new one is requested and returned.

Returns:

Simplenote API token as string

trash_note(note_id)

Method to move a note to the trash

Arguments:

  • note_id (string): key of the note to trash

Returns:

A tuple (note, status)

  • note (dict): the newly created note or an error message

  • status (int): 0 on success and -1 otherwise

update_note(note)

Method to update a specific note object, if the note object does not have a “key” field, a new note is created

Arguments

  • note (dict): note object to update

Returns:

A tuple (note, status) - note (dict): note object - status (int): 0 on success and -1 otherwise