Getting Started with Contentful and Python

This guide will show you how to get started using our Python client library to consume content.

Contentful's Content Delivery API (CDA) is a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location by using our global CDN.

We publish client libraries for various languages to make developing applications easier.

Requirements

This tutorial assumes that you understand the Contentful data model.

Authentication

For every request, clients need to provide an API key, which is created per space and used to delimit applications and content classes.

You can create an access token using the Contentful web app or the Content Management API.

Installation

Install the 'contentful' client with pip:

pip install contentful

Or add the client library to your requirements.txt file:

contentful

And run pip install -r requirements.txt to install the client and all dependencies.

Setting up the Contentful client

Once you have installed the package, you can use it inside your application.

Initialize the client

You need an API key and a space ID to initialize a client. You can use the API key and space ID pre-filled below from our example space or replace them with your own values.

import contentful

client = contentful.Client('<space_id>', '<access_token>')

Getting your content

Contentful separates content between entries, which contain your data and relationships with other content or images, and assets, which represent static content, like images, and are served as files. Read more in our content model guide.

Entries

With the client created, you can now start consuming data from the CDA.

For example, to request all entries in a space:

entries = client.entries()

for entry in entries:
    print(getattr(entry, 'product_name', 'Not a product'))

Not a product
Not a product
Whisk Beater
Hudson Wall Cup
Not a product
Not a product
Not a product
Not a product
SoSo Wall Clock
Not a product
Not a product
Not a product
Playsam Streamliner Classic Car, Espresso

Or to request a single entry:

entry_id = '<entry_id>'
classic_car = client.entry(entry_id)

Playsam Streamliner Classic Car, Espresso

You can specify any of the query parameters accepted by the API, for example:

products_by_price = client.entries({'content_type': '<product_content_type_id>', 'order': 'fields.price'})

for entry in products_by_price:
  print(entry.product_name)

Hudson Wall Cup
Whisk Beater
Playsam Streamliner Classic Car, Espresso
SoSo Wall Clock

Using your entry as a Python object

Once you have your entry, you can use it as a Python object that follows standard Python conventions:

print(product.product_name)
print("it costs {0}".format(product.price))
print("I am tagged with {0}".format(' and '.join(product.tags)))

Playsam Streamliner Classic Car, Espresso
it costs 44
I am tagged with wood and toy and car and sweden and design

You can form complicated queries and interaction with your entries:

products_with_many_tags = [ product for product in client.entries({'content_type': '<product_content_type_id>', 'include': 2}) if product.tags.size > 2 ]
for product in products_with_many_tags:
   print("I am tagged with {0}".format(' and '.join(product.tags)))
   print("My brand is: {0}".format(product.brand.company_name))

I am tagged with vase and flowers and accessories
My brand is: Normann Copenhagen
I am tagged with wood and toy and car and sweden and design
My brand is: Playsam
I am tagged with kitchen and accessories and whisk and scandinavia and design
My brand is: Normann Copenhagen
I am tagged with home décor and clocks and interior design and yellow and gifts
My brand is: Lemnos

In this example you added the include: 2 parameter, which allows the API to resolve links to other related entries.

Using assets

You query assets in a similar way to entries, but the CDA offers more specific features, such as filtering by the type of file. You can also use our Images API, that allows you to manipulate images as you retrieve them.

To query a single asset:

client.asset('<asset_id>').url()

//images.ctfassets.net/71rop70dkqaj/wtrHxeu3zEoEce2MokCSi/e86a375b7ad18c25e4ff55de1eac42fe/quwowooybuqbl6ntboz3.jpg

To query all assets in a space:

assets = client.assets()

for asset in assets:
  print(asset.url())

//images.ctfassets.net/71rop70dkqaj/1MgbdJNTsMWKI0W68oYqkU/4c2d960aa37fe571d261ffaf63f53163/9ef190c59f0d375c0dea58b58a4bc1f0.jpeg
//images.ctfassets.net/71rop70dkqaj/4zj1ZOfHgQ8oqgaSKm4Qo2/8c30486ae79d029aa9f0ed5e7c9ac100/playsam.jpg
//images.ctfassets.net/71rop70dkqaj/3wtvPBbBjiMKqKKga8I2Cu/90b69e82b8b735383d09706bdd2d9dc5/zJYzDlGk.jpeg
//images.ctfassets.net/71rop70dkqaj/wtrHxeu3zEoEce2MokCSi/e86a375b7ad18c25e4ff55de1eac42fe/quwowooybuqbl6ntboz3.jpg
//images.ctfassets.net/71rop70dkqaj/6t4HKjytPi0mYgs240wkG/b7ba3984167c53d728e7533e54ab179d/toys_512pxGREY.png
//images.ctfassets.net/71rop70dkqaj/10TkaLheGeQG6qQGqWYqUI/13c64b63807d1fd1c4b42089d2fafdd6/ryugj83mqwa1asojwtwb.jpg
//images.ctfassets.net/71rop70dkqaj/Xc0ny7GWsMEMCeASWO2um/190cc760e991d27fba6e8914b87a736d/jqvtazcyfwseah9fmysz.jpg
//images.ctfassets.net/71rop70dkqaj/2Y8LhXLnYAYqKCGEWG4EKI/44105a3206c591d5a64a3ea7575169e0/lemnos-logo.jpg
//images.ctfassets.net/71rop70dkqaj/6m5AJ9vMPKc8OUoQeoCS4o/07b56832506b9494678d1acc08d01f51/1418244847_Streamline-18-256.png
//images.ctfassets.net/71rop70dkqaj/6s3iG2OVmoUcosmA8ocqsG/b55b213eeca80de2ecad2b92aaa0065d/1418244847_Streamline-18-256__1_.png
//images.ctfassets.net/71rop70dkqaj/KTRF62Q4gg60q6WCsWKw8/ae855aa3810a0f6f8fee25c0cabb4e8f/soso.clock.jpg