{"id":7110,"library":"contentstack-utils","title":"Contentstack Utils","description":"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.","status":"active","version":"1.5.0","language":"en","source_language":"en","source_url":"https://github.com/contentstack/contentstack-utils-python","tags":["Contentstack","CMS","Headless CMS","RTE","HTML","Rich Text Editor","Python"],"install":[{"cmd":"pip install contentstack-utils","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for parsing and rendering HTML from Contentstack's Rich Text Editor JSON.","package":"lxml","optional":false}],"imports":[{"symbol":"ContentstackUtils","correct":"from contentstack_utils import ContentstackUtils"},{"note":"Required for advanced RTE features like rendering embedded items.","symbol":"Options","correct":"from contentstack_utils.helper import Options"}],"quickstart":{"code":"import json\nfrom contentstack_utils import ContentstackUtils\n\n# Sample Rich Text Editor JSON from Contentstack\n# This structure is typically found under the 'json' key of an RTE field.\nrte_content_json = [\n    {\n        \"type\": \"doc\",\n        \"children\": [\n            {\n                \"type\": \"p\",\n                \"children\": [\n                    {\n                        \"text\": \"Hello from Contentstack Rich Text Editor!\"\n                    }\n                ]\n            },\n            {\n                \"type\": \"p\",\n                \"children\": [\n                    {\n                        \"type\": \"a\",\n                        \"attrs\": {\n                            \"href\": \"https://www.contentstack.com\",\n                            \"target\": \"_blank\",\n                            \"rel\": [\"noopener\", \"noreferrer\"]\n                        },\n                        \"children\": [\n                            {\n                                \"text\": \"Visit Contentstack\"\n                            }\n                        ]\n                    }\n                ]\n            }\n        ]\n    }\n]\n\n# Convert the RTE JSON to HTML\nhtml_output = ContentstackUtils.json_to_html(rte_content_json)\n\nprint(\"Converted HTML output:\")\nprint(html_output)\n","lang":"python","description":"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."},"warnings":[{"fix":"Use the `contentstack-sdk-python` library to fetch content entries from Contentstack, then pass the relevant RTE JSON to `contentstack-utils` for processing.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"<1.1.0 to >1.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<1.3.0 to >1.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.3.2"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `lxml` manually: `pip install lxml`. If issues persist, try reinstalling `contentstack-utils` to ensure all dependencies are met: `pip install contentstack-utils`.","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.","error":"ModuleNotFoundError: No module named 'lxml'"},{"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.","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.","error":"AttributeError: 'list' object has no attribute 'get' (or similar type error when passing data to json_to_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.","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.","error":"Embedded entries or assets are not rendered in the HTML output, even when options are provided."}]}