The Delivery Python SDK can be used in Python projects to retrieve content from the Kentico Kontent headless CMS. This is a community project and not an official Kentico SDK. If you find a bug in the SDK or have a feature request, please submit a GitHub issue.

• Installation
• Creating a client
  • Setting up config.py
  • Delivery options
  • Retrying requests
• Requesting items
  • Getting a single item
  • Getting linked items
  • Getting multiple items
  • Filtering content
• Rich Text Resolution
  • Resolving inline links
  • Resolving inline items and components
• Enumerating all items
• Requesting content types
  • Getting a content type
  • Getting multiple content types
• Requesting Taxonomies
  • Getting a taxonomy group
  • Getting multiple taxonomies
• Listing languages
• Transforming images

To install the SDK from the Python Package Index use:

pip install kontent_delivery

To obtain content from Kentico Kontent, you will create an instance of DeliveryClient and pass it your Project ID:

from kontent_delivery.client import DeliveryClient

client = DeliveryClient("your_project_id")

Using a configuration file to pass API keys and client options when creating instances of DeliveryClient is recommended. This can be done by adding a config.py file to the root of your project and importing it to your modules.

The config.py file should be in the JSON format as follows:

project_id ="your_project_id"
delivery_options = {   
    "preview": False,
    "preview_api_key": "enter_key_here",
    "secured": False,
    "secured_api_key": "enter_key_here",
    "timeout": (4,7)
    }

Which can be imported and used to build your DelieryClient:

import config
from kontent_delivery.client import DeliveryClient

client = DeliveryClient(config.project_id, options=config.delivery_options)

Note: Preview and Secured API cannot be enabled simultaneously.

By default, the SDK uses a retry policy, asking for requested content again in case of an error. The default policy retries the HTTP request if the following status codes are returned:

• 408 - RequestTimeout
• 429 - TooManyRequests
• 500 - InternalServerError
• 502 - BadGateway
• 503 - ServiceUnavailable
• 504 - GatewayTimeout

The SDK will perform a total of 6 attempts at a maximum of 32 seconds to retrieve content before returning a max retry error. The consecutive attempts are delayed with exponential backoff.

To disable the retry policy or set a custom number of attempts, you can set retry_attempts in the config file:

project_id ="your_project_id"
delivery_options = {   
    "retry_attempts": 0
    }

Getting an item from Kontent can be accomplished by using the DeliveryClient's get_content_item method and passing in the content item's codename:

response = client.get_content_item("coffee_processing_techniques")

print(response.codename)
print(response.elements.title.value)

# prints:
# coffee_processing_techniques
# Coffee processing techniques

Using this method will return a ContentItem. To access elements and their values use dot notation in the format: response.elements.element_name.value

Getting items used in a linked items element on a content item can be done by using the get_linked_items() method and passing in the linked items element's codename:

response = client.get_content_item("coffee_processing_techniques")

linked_items = response.get_linked_items("related_articles")

for item in linked_items:
    print(f"name: {item.name}")
    # prints:
    # On Roasts
    # About Us
    # etc.

Using this method will return a list of ContentItems.

Getting an item listing from Kontent can be accomplished by using the DeliveryClient's get_content_items method:

response = client.get_content_items()

for item in response.items:
    print(item.name)
    # prints:
    # About us
    # AeroPress
    # AeroPress Filters
    # ...

Using the DeliveryClient's get_content_items method will produce a ContentItemListing object that stores each retrieved item as a ContentItem in an "items" attribute.

Filtering can be used when getting multiple items. Filters use an "element", "operation", "value" pattern. For example, the following filter gets any items with the title "On Roasts":

from kontent_delivery.builders.filter_builder import Filter

response = client.get_content_items(
    Filter("elements.title", "[eq]", "On Roasts")
)

Filters can also be used for Kontent's Projection and parameters following the same pattern. If there is no element to act upon, the Filter's first value is empty:

Filter("", "depth", 6)

Multiple filters and parameters can be passed into a single call:

response = client.get_content_items(
    Filter("system.type", "[eq]", "coffee"),
    Filter("elements.product_name", "[neq]", "Folgers"),
    Filter("price", "[lte]", "10.5"),
    Filter("elements.country", "[in]", ["Kenya","Brazil","Argentina"]),
    Filter("","depth", 6),
    Filter("","elements","product_name")
)

Rich Text Elements in Kontent can contain inline references to other content items within the project using links, inline content items, or components. To accomplish this using the Python SDK you need to:

1. Create a custom resolver
2. Import your custom resolver
3. Register the resolver with your DeliveryClient

Once a custom resolver is implemented and registered to the client, resolution will automatically happen when a ContentItem or ContentItemListing is built.

Use samples and example.py as a reference.

By default, Kentico Kontent returns inline content item links with an empty "href" attribute and a "data-item-id" attribute containing the content item ID:

<!-- inline content item link -->
<a data-item-id=\"80c7074b-3da1-4e1d-882b-c5716ebb4d25\" href=\"\">

To resolve the link, create a CustomLinkResolver that uses the resolve_link() method to evaluate and return an href string value:

class CustomLinkResolver:
    @staticmethod
    def resolve_link(link):
        if link.type == "coffee":
            return f"/coffees/{link.url_slug}"
            
        if link.type == "article":
            return f"/articles/{link.url_slug}"

The link argument passed into resolve_link() allows you to access the link type, codename, and url_slug.

Once a custom link resolver is implemented, import it and register to your DeliveryClient:

from kontent_delivery.client import DeliveryClient
# namespace for your custom resolver will vary
from samples.custom_link_resolver import CustomLinkResolver

client = DeliveryClient("your_project_id")
client.custom_link_resolver = CustomLinkResolver()

By default, Kentico Kontent returns inline content items and components links as objects with identifying attributes like "data-type" and "data-codename." This attributes are used to identify the inline item:

<!-- Inline Content Item: -->
<object type=\"application/kenticocloud\" data-type=\"item\" data-rel=\"link\" data-codename=\"on_roasts\"></object>
<!-- Component: -->
<object type=\"application/kenticocloud\" data-type=\"item\" data-rel=\"component\" data-codename=\"n71d0469e_9a77_0168_8f49_08f6d3bcaca3\"></object>

To resolve the inline item or component, create a CustomItemResolver that uses the resolve_item() method to replace the object elements:

class CustomItemResolver:
    @staticmethod
    def resolve_item(linked_item):
        if linked_item.content_type == "article":
            return f"<h1>{linked_item.elements.title.value}</h1>"
            
        if linked_item.content_type == "tweet":
            return (f"<blockquote class='twitter-tweet' data-lang='en'"
                    f"data-theme={linked_item.elements.theme.value[0].codename}>"
                    f"<a href={linked_item.elements.tweet_link.value}></a></blockquote>")

The linked_item argument passed into resolve_item() is a ContentItem.

Once a custom link resolver is implemented, import it and register to your DeliveryClient:

from kontent_delivery.client import DeliveryClient
# namespace for your custom resolver will vary
from samples.custom_item_resolver import CustomItemResolver

client = DeliveryClient(config.project_id, options=config.delivery_options)
client.custom_item_resolver = CustomItemResolver()

When enumerating all items in the specified project, or if exceeding the item response limit on the Delivery API's items endpoint is necessary, the items-feed endpoint can be used.

Getting an item feed from Kontent can be accomplished by using the DeliveryClient's get_content_items_feed method:

r = client.get_content_items_feed()

while r.next:
    next_result = r.get_next()
    r.feed.items.extend(next_result.items)

for item in r.feed.items:
    print(item.name)
    # prints:
    # Example Item Name 001
    # Example Item Name 002
    # ...
    # Example Item Name 4300
    # etc.

Using the DeliveryClient's get_content_items_feed method will produce a ContentItemsFeed object that stores ContentItemListing objects in a "feed" attribute. Paginated results can be retrieved by using the get_next method, which returns a ContentItemListing object.

Filtering can also be used when getting content item feeds:

r = client.get_content_items_feed(
    Filter("system.codename", "[eq]", "test999")
)

print(r.url)
# prints: ~/items-feed?system.codename[eq]=test999

Getting a content type from Kontent can be accomplished by using the DeliveryClient's get_content_type method and passing in the content type's codename:

response = client.get_content_type("article")

print(response.codename)
print(response.elements.body_copy)
print(response.elements.body_copy.name)

# prints:
# article
# namespace(type='rich_text', name='Body Copy')
# Body Copy

Using this method will return a ContentType. To access elements and their values use dot notation in the format: response.elements.element_name.attribute_name

Getting a type listing from Kontent can be accomplished by using the DeliveryClient's get_content_types method:

response = client.get_content_types()

for content_type in response.types:
    print(content_type.name)
    # prints:
    # About us
    # Accessory
    # Article
    # ...

Using the DeliveryClient's get_content_types method will produce a ContentTypeListing object that stores each retrieved item as a ContentType in the "types" attribute.

Getting a taxonomy group from Kontent can be accomplished by using the DeliveryClient's get_taxonomy method and passing in the taxonomy group's codename:

response = client.get_taxonomy("personas")

print(response.codename)
print(response.terms)
print(response.terms[0].codename)
# prints:
# personas
# [namespace(name='Coffee expert', codename='coffee_expert', terms=[namespace(name='Barista', codename='barista', terms=[]) ...
# coffee_expert

Using this method will return a TaxonomyGroup. To access terms and their values use dot notation in the format: response.terms[list_postion].attribute_name

You can get term and nested term values by looping through the terms lists or chaining together .terms[list_postion]:

for term in response.terms:
    print(term.name)
    # prints:
    # Coffee expert
    # Coffee enthusiast
    # ...
print(response.terms[0].terms[0].codename)
# prints:
# barista

Using the DeliveryClient's get_taxonomies method will produce a TaxonomyGroupListing object that stores each retrieved item as a TaxonomyGroup in the "taxonomy_groups" attribute.

Using the DeliveryClient's get_languages method will produce a LanguageListing object that stores each retrieved language as a Language in the "languages" attribute.

To access language values loop through the language listing and use dot notation:

response = client.get_languages()

for language in response.languages:
    print(language.name)
    # prints:
    # English (United States)
    # Spanish (Spain)
    # ...

When you've obtained the URL for an asset, you can use the Kontent Image Transformation API to make on-the-fly modifications to the image.

To use this, create an instance of ImageBuilder and pass the desired transformation methods into the bulder's .transform() method. Example:

from kontent_delivery.builders.image_builder import ImageBuilder

# Get content item
response = client.get_content_item("coffee_processing_techniques")

# Get asset url
asset_url = response.elements.teaser_image.value[0].url

# Transform image
image = ImageBuilder(asset_url)
transformed_image = image.transform(
    image.width(300),
    image.height(300),
    image.pixel_ratio(1.5),
    )

print(transformed_image)
# prints: ~/coffee-processing-techniques-1080px.jpg?w=300&h=300&dpr=1.5