Content Delivery SDK for Python

Starting from today, building Contentful-powered Python apps will be much more enjoyable. We are excitedly releasing the first-ever Python SDK for the Content Delivery API. It simplifies fetching and traversing resources from the API by abstracting tedious tasks, such as dealing with networking, mapping fields, resolving links and much more. Below is a quick overview of the features we have so far and some examples demonstrating how the library works.

Setup

The library is available on PyPi and currently supports Python versions 2.7, 3.2, 3.3 and 3.4. The library can be installed in several ways, depending on how your environment is configured. Example with pip:

pip install contentful.py

Full documentation can be found [here][1] and the source code is [available on GitHub][2].
You can verify that the library is installed by running:

(env) contentful:~ doge$ pip show contentful.py

Name: contentful.py
Version: 0.9.1
Location: /Users/doge/env/lib/python2.7/site-packages
Requires: enum34, requests, six, python-dateutil
(env) contentful:~ doge$

Getting Started

In the following examples we will use the credentials for our official demo space:

space_id: cfexampleapi
access_token: b4c0n73n7fu1

The first thing to do would be creating a [**Client**][3] which is used to fetch resources from the Content Delivery API. It has a constructor that takes several parameters, but only two are required to create a fully functional instance: **space_id** and **access_token**. For example:

From here on, this instance can be used to fetch resources from the demo space.

Resources

The Delivery API can return different types of resources, such as assets, content types and entries. These are represented in the resources module of the SDK , respectively named Asset, ContentType and Entry.

In order to fetch resources from the API, use the Client's fetch() method which takes the resource type as the only parameter. For example:

The reason for chaining the first() method at the end of the call is because the fetch() method actually returns a RequestArray instance. This enables requesting only one item by invoking the first() method or requesting an array of items by invoking the all() method.

When used with the all() method, expect an Array instance to be returned:

which is iterable:

and sliceable:

Defining Models

It is often more convenient to define custom classes for your models rather than using the built-in Entry type. Usually, the most common usage is exposing convenience accessors to the underlying data, but certainly this can be useful in many other ways. The SDK has a built-in feature to make that possible. Consider the Cat content type of the official demo space, which looks like this (some properties are omitted for brevity):

A custom model class for this content type can be defined as follows:

By default fields IDs are mapped according to the name of the attribute. If you wish to explicitly specify the ID for a field, provide the field_id parameter to the Field constructor, as in the best_friend field in the example above.

The class also has to be registered when creating the Client:

Whenever this Client will attempt to create an entry with a content type that matches the one defined in our custom class, an instance of the Cat class will be created, and its fields will be set accordingly, so that they can be accessed as instance attributes:

If at any point it is desired to fetch only resources of that type, the class can be passed to the fetch() method and the content type will be inferred by the client:

Link Resolution

By default a Client is configured to attempt to resolve links automatically when requesting resource arrays. While doing so, if a link is successfully resolved, the field will simply reference the linked resource; otherwise, the unresolved link will be represented as a ResourceLink object. It is possible to manually resolve ResourceLink objects by using the resolve_resource_link method which attempts to fetch the linked resource from the API by invoking a network request.

Automatic Link Resolution

Manual Link Resolution

Conclusion

This is the very first release of our Python SDK, so it is still in "labs" stage. We are planning to improve it and introduce new features in the nearest future. For any feedback, please drop us a line.