Contentstack Utils

1.5.0 · active · verified Thu Apr 16

contentstack_utils is a Python utility package designed to assist with processing data from the Contentstack headless CMS. Its primary function is to convert Rich Text Editor (RTE) content, including Supercharged RTE (SRTE) with embedded items, from Contentstack's JSON format into HTML. The current version is 1.5.0, with minor releases happening every few months.

Common errors

```
ModuleNotFoundError: No module named 'lxml'
```
cause The `lxml` library is a required dependency for `contentstack-utils` to function correctly, but it was not installed or is not available in the current environment.

fix Install `lxml` manually: `pip install lxml`. If issues persist, try reinstalling `contentstack-utils` to ensure all dependencies are met: `pip install contentstack-utils`.
```
AttributeError: 'list' object has no attribute 'get' (or similar type error when passing data to json_to_html)
```
cause The `ContentstackUtils.json_to_html` function expects a list of dictionaries representing the raw JSON content of the RTE field (e.g., `entry['your_rte_field']['json']`), not the entire RTE field object or a string.

fix Verify that you are passing the correct part of your Contentstack entry data. If your RTE field is named 'body', you should typically pass `entry['body']['json']` to the function.
```
Embedded entries or assets are not rendered in the HTML output, even when options are provided.
```
cause The `Options` object, specifically the `embedded_items` dictionary and `render_embedded_object` callback, might not be configured correctly. The UIDs in `embedded_items` must match the UIDs in the RTE JSON, and the `render_embedded_object` function must return valid HTML.

fix Double-check that the `uid` values in your RTE JSON's reference nodes exactly match the keys in the `options.embedded_items` dictionary. Ensure that `options.embedded_items` contains the full data payload for each embedded item, and that your `render_embedded_object` callback correctly identifies and renders the embedded item based on its `content-type-uid` and provided data.

Warnings

gotcha This library only handles processing existing Contentstack data (like RTE content) and does NOT provide functionality for fetching data from Contentstack. You must use the official Contentstack Python SDK or another HTTP client to retrieve entry data first.
Fix: Use the `contentstack-sdk-python` library to fetch content entries from Contentstack, then pass the relevant RTE JSON to `contentstack-utils` for processing.
breaking Versions 1.1.0 (SRTE Support) and 1.2.1 (GraphQL SRTE support) introduced significant changes to how Rich Text Editor content, especially Supercharged RTE (SRTE) with embedded items, is handled. Existing code that manually parsed or expected a simpler RTE JSON structure might require updates.
Fix: Review the official documentation for SRTE and embedded items. Utilize `ContentstackUtils.json_to_html` with the `Options` class and a `render_embedded_object` callback for proper handling of embedded content in newer RTE fields.
breaking Version 1.3.0 added 'Reference support', which could alter the structure of RTE JSON when entries contain linked references. If your application was making assumptions about RTE JSON structure, this might cause unexpected behavior.
Fix: Ensure your code is resilient to changes in RTE JSON structure, particularly when dealing with references. Always validate the input to `json_to_html` or use the `Options` class to provide appropriate rendering logic for references.
gotcha Security fixes were implemented in versions 1.3.2 and 1.3.3. Older versions may contain unpatched vulnerabilities related to dependencies or parsing logic.
Fix: Always upgrade to the latest stable version (currently 1.5.0) to ensure you have the most up-to-date security patches and bug fixes.

Install

pip install contentstack-utils Install stable version

Imports

ContentstackUtils

from contentstack_utils import ContentstackUtils

Options
```
from contentstack_utils.helper import Options
```
Required for advanced RTE features like rendering embedded items.

Quickstart

This quickstart demonstrates how to convert a Contentstack Rich Text Editor (RTE) JSON structure into renderable HTML using the `ContentstackUtils.json_to_html` method. This is the most common use case for the library.

import json
from contentstack_utils import ContentstackUtils

# Sample Rich Text Editor JSON from Contentstack
# This structure is typically found under the 'json' key of an RTE field.
rte_content_json = [
    {
        "type": "doc",
        "children": [
            {
                "type": "p",
                "children": [
                    {
                        "text": "Hello from Contentstack Rich Text Editor!"
                    }
                ]
            },
            {
                "type": "p",
                "children": [
                    {
                        "type": "a",
                        "attrs": {
                            "href": "https://www.contentstack.com",
                            "target": "_blank",
                            "rel": ["noopener", "noreferrer"]
                        },
                        "children": [
                            {
                                "text": "Visit Contentstack"
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

# Convert the RTE JSON to HTML
html_output = ContentstackUtils.json_to_html(rte_content_json)

print("Converted HTML output:")
print(html_output)

view raw JSON →