Python SDK for Contentful's Content Delivery API
Project description
Python SDK for Contentful’s Content Delivery API.
Setup
Installation via pip:
pip install contentful-cda
Usage
Creating a Client
The Client class manages all your interaction with the Contentful Delivery API, creating one is as simple as:
client = Client('space-id', 'access-token')
Fetching Resources
The simplest form of fetching resources follows:
client.fetch(Asset).all() # Returns an array of Assets
client.fetch(Asset).first() # Returns the first Asset available
client.fetch(Entry).all() # Returns an array of Entries
client.fetch(Entry).first() # Returns the first Entry available
client.fetch(ContentType).all() # Returns an array of Content Types
client.fetch(ContentType).first() # Returns the first Content Type available
When used with the all() method, expect an Array object to be returned, which is iterable:
for resource in array:
dosomething(resource)
and sliceable:
for resource in array[2:4]:
dosomething(resource)
Custom Queries
Custom queries can be provided by invoking the where() method of a Request object, for example:
client.fetch(Entry).where({'sys.id': 'MyEntry'}).first()
Defining Models
Custom Entry classes can be declared by providing a Content Type ID value and by defining a set of fields. Consider the Cat Content Type from the official demo space, which looks like this (sans some properties for brevity):
{
"fields": [
{"id": "name", "name": "Name", "type": "Text"},
{"id": "likes", "name": "Likes", "type": "Array", "items": { "type": "Symbol" }},
{"id": "color", "name": "Color", "type": "Symbol"},
{"id": "bestFriend", "name": "Best Friend", "type": "Link", "linkType": "Entry"},
{"id": "birthday", "name": "Birthday", "type": "Date"},
{"id": "lives", "name": "Lives left", "type": "Integer"},
{"id": "image", "name": "Image", "type": "Link", "linkType": "Asset"}
],
"name": "Cat",
"displayField": "name",
"description": "Meow."
}
A custom Entry class for this Content Type can be defined as follows:
class Cat(Entry):
__content_type__ = 'cat'
name = Field(Text)
likes = Field(List)
color = Field(Text)
best_friend = Field(Link, field_id='bestFriend')
birthday = Field(Date)
lives = Field(Number)
image = Field(Link)
The class also has to be registered when creating a Client:
client = Client('cfexampleapi', 'b4c0n73n7fu1', custom_entries=[Cat])
Whenever this Client will attempt to create an Entry with a Content Type that matches the one defined in the class, an instance of the Cat class will be created, and it’s fields will be set accordingly, and can later be easily accessed as instance attributes:
print 'Name of the Cat: {0}'.format(cat.name)
If at any point it is desired to fetch only resources of that type, it can be passed to the fetch() method and inferred by the client:
client.fetch(Cat).all() # Fetches all the Cats!
Link Resolution
Unless specified otherwise, a Client is configured to attempt and resolve links automatically when requesting resource arrays. Be mindful about providing the includes parameter properly, since only if the linked resources are contained within the response they will be resolved automatically. In case a link is not resolved, expect a ResourceLink object as the field’s value, which could later be resolved by invoking the resolve_resource_link() method of a Client, which issues a network request per the resource ID.
Automatic link resolution:
array = client.fetch(Cat).all()
print array[0].best_friend
# <Cat(sys.id=nyancat)>
Manual link resolution:
cat = client.fetch(Cat).first()
print cat.best_friend
# <contentful.cda.resources.ResourceLink object at 0x1030df390>
print cli.resolve_resource_link(cat.best_friend)
# <Cat(sys.id=nyancat)>
License
Copyright (c) 2015 Contentful GmbH. See LICENSE.txt for further details.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.