Using the SDK¶

Authentication¶

There are three ways to authenticate with the Mendeley Python SDK. Before you start, you’ll need to have registered your application at the developer portal.

Authorization code flow¶

This flow is recommended for applications that have access to secure, private storage, such as web applications deployed on a server.

from mendeley import Mendeley

# These values should match the ones supplied when registering your application.
mendeley = Mendeley(client_id, client_secret=client_secret, redirect_uri=redirect_uri)

auth = mendeley.start_authorization_code_flow()

# The user needs to visit this URL, and log in to Mendeley.
login_url = auth.get_login_url()

# After logging in, the user will be redirected to a URL, auth_response.
session = auth.authenticate(auth_response)

Implicit grant flow¶

This flow is recommended for applications running in environments that do not provide secure storage.

from mendeley import Mendeley

# These values should match the ones supplied when registering your application.
mendeley = Mendeley(client_id, redirect_uri=redirect_uri)

auth = mendeley.start_implicit_grant_flow()

# The user needs to visit this URL, and log in to Mendeley.
login_url = auth.get_login_url()

# After logging in, the user will be redirected to a URL, auth_response.
session = auth.authenticate(auth_response)

Client credentials flow¶

This flow does not require the user to log in. However, it only provides access to a limited set of resources (the read-only Mendeley Catalog of crowd sourced documents).

from mendeley import Mendeley

# These values should match the ones supplied when registering your application.
mendeley = Mendeley(client_id, client_secret=client_secret)

auth = mendeley.start_client_credentials_flow()
session = auth.authenticate()

Sessions¶

After authentication, you will have a MendeleySession, which will allow you to access the Mendeley API. The linked resources describe the operations that you can perform, and the objects that you can interact with.

class mendeley.session.MendeleySession¶

Entry point for accessing Mendeley resources.

annotations¶: A :class: Annotations <mendeley.resources.annotations.Annotations> resource for accessing annotations in the logged-in user’s library.

catalog¶: A Catalog resource for accessing the Mendeley catalog.

documents¶: A Documents resource for accessing documents in the logged-in user’s library.

files¶: A Files resource for accessing files in the logged-in user’s library.

groups¶: A Groups resource for accessing groups that the user is a member of.

profiles¶: A Profiles resource for accessing profiles of Mendeley users.

trash¶: A Trash resource for accessing trashed documents in the logged-in user’s library.

Pagination¶

Many collections in the API are spread over multiple pages. Typically, the SDK provides two ways of navigating these collections:

an iter method, which provides the whole collection as an iterator.
a list method, which returns the first page of results as a Page. You can use this object to navigate through the other pages.

class mendeley.pagination.Page¶

A page of a collection of objects.

first_page¶: the first Page of the collection.

items¶: a list of items on this page.

last_page¶: the first Page of the collection.

next_page¶: the next Page of the collection, or None if this is the last page.

previous_page¶: the previous Page of the collection, or None if this is the first page.

Examples¶

To print the name of the logged-in user:

print session.profiles.me.display_name

To print the titles of all of the documents in the user’s library:

for document in session.documents.iter():
    print document.title

To print the number of readers of a document by DOI:

print session.catalog.by_identifier(doi='10.1371/journal.pmed.0020124', view='stats').reader_count