Embeddedpy-bridge: A Toolkit for Embedded Python

Overview

Embedded Python is a game-changer for InterSystems IRIS, offering access to the vast Python ecosystem directly within the database. However, bridging the gap between ObjectScript and Python can sometimes feel like translating between two different worlds.

To make this transition seamless using embeddedpy-bridge.

This package is a developer-centric utility kit designed to provide high-level ObjectScript wrappers, familiar syntax, and robust error handling for Embedded Python. It allows developers to interact with Python data structures using the native IRIS patterns they are already comfortable with.

The Challenge

While the %SYS.Python library is powerful, developers often face a few hurdles:

1. Handling Proxies: Navigating Python lists and dictionaries using raw proxies doesn't feel "native" to ObjectScript.
2. Iteration: Standard ObjectScript While loops don't natively "talk" to Python iterators.
3. Namespace Management: Ensuring Python utilities are available system-wide.

The Solution: embeddedpy-bridge

My goal was to create a "Bridge" that makes Python feel like a first-class citizen in ObjectScript.

Key Features:

• The py Prefix Convention: All methods in the %ZPython.Utils class use a py prefix (e.g., pyDict(), pyList(), pyJSON()) to clearly distinguish Python-related logic from native IRIS code.
• OO Wrappers: High-level classes for List and Dict that support familiar methods like GetAt(), SetAt(), and Count().
• Smart Iterators: Integrated ListIterator and DictIterator allow you to traverse Python data using standard ObjectScript While loops.
• Macro Support: A %ZPython.inc file provides shortcuts like $$$pyDict and $$$pyJSON for cleaner, faster development.

Usage Examples

1. Simple Syntax (Macros)

No more typing ##class(...) every time. Use short shortcuts:

• $$$pyDict — Create a Python Dictionary.
• $$$pyList — Create a Python List.
• $$$pyJSON(dynObj) — Turn a JSON object into Python instantly.

2. Unified Dictionary Handling

Instead of managing raw Python proxies, use the wrapped dictionary:

Code snippet:

Include %ZPython
Set pyDict = $$$pyDict
Do pyDict.SetAt("Status", "Active")
Do pyDict.SetAt("Version", 1.0)

// Standard IRIS iteration
Set iter = pyDict.%GetIterator()
While iter.%GetNext(.key, .val) {
    Write "Key: ", key, " Val: ", val, !
}

Set pyList = $$$zpyList()

Do pyList.Append("First Item")
Do pyList.Append("Second Item")

Write "Total items: ", pyList.Count(), !

// Access by index
Write "Item 1: ", pyList.GetAt(0), !

2. Seamless Data Conversion

Convert IRIS Dynamic Objects to Python objects and back with one line:

Code snippet

Set dynObj = {"name": "John", "roles": ["Admin", "User"]}
Set pyObj = $$$pyJSON(dynObj)

// Verify Python type
Write ##class(%ZPython.Utils).IsType(pyObj, "dict") // 1

The goal of this project is to bridge the gap between two powerful worlds. While InterSystems IRIS provides the engine for Embedded Python, embeddedpy-bridge provides the steering wheel.