cs-icon.svg

Contentstack - Python Delivery SDK

Python Delivery SDK for Contentstack

Contentstack is a headless CMS with an API-first approach. It is a CMS that developers can use to build powerful cross-platform applications in their favorite languages. Build your application front end, and Contentstack will take care of the rest. Read More.

Contentstack provides Python Delivery SDK to build applications on top of Python. Given below is the detailed guide and helpful resources to get started with our Python Delivery SDK.

Prerequisite

This guide will help you get started with Contentstack Python SDK to build apps powered by Contentstack.


SDK Installation and Setup

To use the Contentstack Python SDK with your existing project, perform the following steps:

  1. Open the terminal, create a project, and move inside it as follows:
    mkdir contentstack-example
cd
  2. Create a virtual environment:
    python3 -m venv venv
  3. Activate the virtual environment:
    source  venv/bin/activate
  4. Install pip Contentstack as follows:
    pip install contentstack

You can download the latest dependency version here

Quickstart in 5 mins

Initializing your SDK

Contentstack offers five regions North America (NA), Europe (EU), Azure North America (AZURE_NA), Azure Europe (AZURE_EU), and GCP North America (GCP_NA) as data centers to store customers' account details and data. These regions are independent of each other and therefore have a dedicated set of instructions to use SDKs offered by Contentstack.

To use SDKs for the Europe, Azure NA, or Azure EU region, you will have to make certain changes in the configuration of the SDK, as detailed below, and the rest of the instructions remain the same.

To initialize the SDK, the stack’s api_key delivery token and the name of the environment where you will publish the content, as shown in the snippet below:

import contentstack
stack = contentstack.Stack(api_key='api_key', delivery_token='delivery_token', environment='environment')

Note: By default, the SDK uses the North American region. Configuration changes are not required for North American region users.

By default, the SDK uses the North American region. Configuration changes are not required for North American region users.

Refer the below code if you want to use the Europe, Azure North America, Azure Europe, or GCP North America region.

import contentstack
stack = contentstack.Stack("api_key", "delivery_token", "environment", region = "ContentstackRegion.AZURE_EU")

Once you have initialized the SDK, you can query entries to fetch the required content.

For Setting the branch for Europe, Azure North America, Azure Europe, or GCP North America, refer the code below

For Setting Branch:

If you want to initialize SDK in a particular branch use the code given below:

import contentstack
stack = contentstack.Stack(api_key='api_key', delivery_token='delivery_token',environment= 'environment', branch='branch')

Basic Queries

Contentstack SDKs let you interact with the Content Delivery APIs and retrieve content from Contentstack. They are read-only in nature. The SDKs fetch and deliver content from the nearest server via Fastly, our powerful and robust CDN.

Get a Single Entry

To retrieve a single entry from a content type, use the code snippet given below:

import contentstack
stack = contentstack.Stack(api_key='api_key', delivery_token='delivery_token', environment='environment')
contentType = stack.content_type("content_type_uid")
entry = content_type.entry("entry_uid")
response = entry.fetch()

Get Multiple Entries

To retrieve multiple entries of a particular content type, use the code snippet given below:

import contentstack
stack = contentstack.Stack(api_key='api_key', delivery_token='delivery_token', environment='environment')
query = stack.content_type("content_type_uid").query()
response = query.find()

Note: By default, the limit for response details per request is 100, with the maximum limit set at 250.

Pagination

In a single instance, the Get Multiple Entries query will retrieve only the first 100 items of the specified content type. You can paginate and retrieve the rest of the items in batches using the skip and limit parameters in subsequent requests.

stack = contentstack.Stack(api_key='api_key', delivery_token='delivery_token', environment='environment')
query = stack.content_type('content_type_uid').query()
response = query.locale('locale').limit(20).skip(20).find()

Stack

Retrieves stack

NameTypeDescription

headers (required)

dict

early_access

dict

Optional array of header strings for early access features.

sync_param

dict

endpoint

str

api_key (required)

str

delivery_token (required)

str

environment (required)

str

host

str

version

str

region

Region

DB region for your stack. You can choose from five regions namely, NA, EU, Azure NA, Azure EU, and GCP NA

timeout

int

branch

str

retry_strategy

Retry

live_preview_dict

dict

live_preview_query

live_preview_query accepts key-value pair objects to the query

Returns:
Type
void

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
response = stack.live_preview_query(**kwargs)
print(response)

image_transform

Image Delivery API covers the parameters that you can add to the URL to retrieve, manipulate (or convert) image files and display it to your web or mobile properties.

Returns:
Type
ImageTransform

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
response = stack.image_transform("image_url", **kwargs)
print(response)

sync_token

You can use the sync token (that you receive after the initial sync)to get the updated content next time. The sync token fetchesonly the content that was addedafter your last sync and the details of the content that was deleted or updated.
Returns:
Type
List Of Sync Items

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
response = stack.sync_token("sync_token")
print(response)

pagination

If the result of the initial sync (or subsequent sync)contains more than 100 records, the response would bepaginated. It provides a pagination token in the response.However, you do not have to use the pagination tokenmanually to get the next batch.
Returns:
Type
List Of Sync Items
import contentstack
stack = contentstack.Stack(api_key = 'api_key', access_token = 'access_token', environment = 'environment')
result = stack.pagination('pagination_token')
if result is not None:
   logger.info(result)
        # result.items: Contains sync data
        # result.paginationToken: For fetching the next batch of entries using pagination token
        # result.syncToken: For performing subsequent sync after initial sync
else:
    logger.error(result)

asset_query

initial sync of the stack

Returns:
Type
List Of Sync Items

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
response = stack.
(
)
print(
)

asset_query

assets of the stack

Returns:
Type
AssetQuery

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
assets = stack.asset_query()
print(
)

asset

asset of the stack

Returns:
Type
Asset

import contentstack;
stack = contentstack.Stack('api_key', 'delivery_token', 'environment');
asset = stack.asset("uid")
print(asset)

get_live_preview

live_preview for the stack

Returns:
Type
String

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
result = stack.get_live_preview
print(result)

get_headers

headers for the stack

Returns:
Type
String

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
result = stack.get_headers
print(result)

get_branch

branch for the stack

Returns:
Type
String

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
result = stack.get_branch
print(result)

get_environment

environment for the stack

Returns:
Type
String

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
result = stack.get_environment
print(result)

get_delivery_token

Delivery Token for the stack

Returns:
Type
String

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
result = stack.get_delivery_token
print(result)

get_api_key

api_key for the stack

Returns:
Type
String

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment)          
result = stack.get_api_key
print(result)

early_access

Array of header strings for early access features.

Returns:
Type
dict
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment, early_access=["early_access_1", "early_access_2"]);

Asset

Retrieves a single asset, specify its UID.

NameTypeDescription

uid

str

Readonly property to check value of asset’s uid

fetch

This call fetches the latest version of a specific asset of a particular stack

Returns:
Type
dict

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset = stack.asset(uid='asset_uid')
response = asset.fetch()

include_fallback

Retrieve the published content of the fallback locale if an entry is not localized in specified locale

Returns:
Type
Asset

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset = stack.asset(uid='asset_uid')
asset = asset.include_fallback()

include_dimension

Include the dimensions (height and width) of the image in the response. Supported image types: JPG, GIF, PNG, WebP, BMP, TIFF, SVG, and PSD

Returns:
Type
Asset

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset = stack.asset(uid='asset_uid')
asset = asset.include_dimension()

relative_urls

Include the relative URLs of the assets in the response

Returns:
Type
Asset

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset = stack.asset(uid='asset_uid')
asset = asset.relative_urls()

environment

Provide the name of the environment if you wish to retrieve the assets published in a particular environment

Returns:
Type
Asset

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset = stack.asset(uid='asset_uid')
asset = asset.environment('environment_name')

params

params is used to pass additional parameters to the asset query

Returns:
Type
Asset

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset = stack.asset(uid='asset_uid')
asset = asset.param('key', 'value')

remove_environment

Removes environment from the request params

Returns:
Type
Asset

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset = stack.asset(uid='asset_uid')
asset = asset.
('production')

AssetQuery

Retrieves Assets

NameTypeDescription

asset_query_params

dict

Readonly property to get data of entry.

find

This call fetches the list of all the assets of a particular stack. It also returns the content of each asset in dict format.

Returns:
Type
Dict

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset_query = stack.asset_query()
response = stack.asset_query().find()

locale

Enter locale code. e.g., en-us

Returns:
Type
AssetQuery

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset_query = stack.asset_query()
stack.asset_query().locale("locale_code")

include_fallback

Retrieve the published content of the fallback locale if an entry is not localized in specified locale

Returns:
Type
AssetQuery

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset_query = stack.asset_query()
stack.asset_query().
()

relative_url

include the relative URLs of the assets in the response

Returns:
Type
AssetQuery

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset_query = stack.asset_query()
stack.asset_query().relative_url()

include_branch

Includes branch in the response

Returns:
Type
AssetQuery

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset_query = stack.asset_query()
stack.asset_query().
()

version

Specify the version number of the asset that you wish to retrieve. If the version is not specified, the details of the latest version will be retrieved. To retrieve a specific version, keep the environment parameter blank

Returns:
Type
AssetQuery

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset_query = stack.asset_query()
asset_query.version(version)

environment

Provide the name of the environment if you wish to retrieve the assets published in a particular environment

Returns:
Type
AssetQuery

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);

ContentType

ContentType provides Entry and Query instance.

query

We can query on entry of specified ContentType

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()

fetch

This method is useful to fetch ContentType of the stack

Returns:
Type
dict

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
response = content_type.fetch()

find

This method is useful to fetch ContentType of the of the stack.

Returns:
Type
dict

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
response = content_type.find()

entry

An entry is the actual piece of content created using one of the defined content types

Returns:
Type
Entry

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')

Entry

Retrieves assets

NameTypeDescription

entry_params

dict

Readonly property to get data of entry.

content_type_id

str

entry_uid

str

base_url

str

fetch

Fetches the latest version of the entries from stack

Returns:
Type
dict

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')
response = entry.fetch()

include_embedded_items

include_embedded_items instance of Entry include_embedded_objects (Entries and Assets) along with entry/entries details

Returns:
Type
Entry

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')
entry.include_embedded_items()

include_branch

Retrieve the published pranch in the entry response

Returns:
Type
Entry

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')
entry.include_branch()

include_fallback

Retrieve the published content of the fallback locale if an entry is not localized in specified locale

Returns:
Type
Entry

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')
entry.

param

This method is useful to add additional Query parameters to the entry

Returns:
Type
Entry

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')
entry.param("key", "value")

version

When no version is specified, it returns the latest version, To retrieve a specific version, specify the version number under this parameter. In such a case, DO NOT specify any environment

Returns:
Type
Entry

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')
entry.version(number)

environment

Enter the name of the environment of which the entries needs to be included

Returns:
Type
Entry

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')
entry.environment('environment_name')

Query

Retrieves assets

NameTypeDescription

content_type_uid

str

base_url

str

query

Adds key value pairs to the to the query parameters

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query = query.query("key":"value")

addParams

Adds Query Parameters to the to the request

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query = query.addParam({"key":"value"})

param

Adds Query Parameters to the to the request

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query = query.param("key", "value")

order_by_descending

you can sort them in the descending order with respect to the value of a specific field in the response body

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query.order_by_descending("key")

order_by_ascending

you can sort them in the ascending order with respect to the value of a specific field in the response body.

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query.order_by_ascending("key")

limit

A limit on the number of objects to return./p>

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query.limit(count)

skip

The number of objects to skip before returning any. skip_count No of objects to skip from returned objects

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query.skip(count)

include_count

Retrieve count and data of objects in result

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query.include_count()

where

Get entries containing the field values matching the condition in the query

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query("
", 
)
query.where()

add_param

This method adds key and value to the Query

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.add_param("key","value")

include_reference_content_type_uid

This method also includes the content type UIDs of the referenced entries returned in the response

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.
()

include_content_type

This method also includes the ContentType in the entry

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.include_content_type()

include_reference

When you fetch an entry of a content type that has a reference field, by default, the content of the referred entry is not fetched. It only fetches the UID of the referred entry, along with the content of the specified entry

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.include_reference()

excepts

Specifies list of field_uid that would be excluded from the response. It refers to the top-level fields of the schema

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.excepts()

only

Specifies an array of only keys in BASE object that would be included in the response. It refers to the top-level fields of the schema

Returns:
Type
Query

Example 1:
Displays values of the specified fields of entries or assets in the response.

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.only("title")

Example 2:
The only function with an array of field UIDs will include data of mentioned fields and exclude the data of all other fields for each entry.

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type('demo').query().add_param('only[BASE][]', ['title','description'])
response = query.find()

find_one

It fetches single query response

Returns:
Type
dict

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
response = query.find_one()

locale

Language code of which the entries need to be included. Only the entries published in this locale will be displayed

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
response = query.locale()

find

It fetches the query response

Returns:
Type
dict

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
response = query.find()

include_embedded_items

Retrieve the published pranch in the response

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.include_embedded_items()

include_branch

Retrieve the published pranch in the response

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.
()

include_fallback

Retrieve the published content of the fallback locale if an entry is not localized in specified locale

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()

where_not_in

Get entries having values based on referenced fields. This query works the opposite of $in_query and retrieves all entries that does not satisfy query conditions made on referenced fields.

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.where_not_in("brand")

where_in

Get entries having values based on referenced fields. This query retrieves all entries that satisfy the query conditions made on referenced fields

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query = query.where_in("brand")

search

This method provides only the entries matching the specified value.

Returns:
Type
Query

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query = query.search("search_keyword")

tags

Include tags with which to search entries that accept variable-length argument lists

Returns:
Type
dict

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
response = query.fetch()

query_operator

query_operator Get entries that satisfy all the conditions provided in the '$and' query.

Returns:
Type
dict

import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query1 = stack.content_type("content_type_uid_1").query()
query2 = self.query1.where("price", QueryOperation.IS_LESS_THAN, fields=90)