Telepath

0.3.1 · active · verified Thu Apr 09

Telepath is a Python library designed for exchanging data between Python and JavaScript. It enables Python objects to be packed into primitive types suitable for frontend consumption, typically within a web context. The current version is 0.3.1. Releases are infrequent, usually tied to specific feature additions or compatibility updates, particularly concerning Django versions.

Warnings

breaking Version 0.3.1 dropped support for Python versions older than 3.8 and Django versions older than 3.2. Projects on older environments must either upgrade Python/Django or pin telepath to an earlier version.
Fix: Upgrade your Python environment to 3.8+ and Django to 3.2+, or restrict your `telepath` dependency to `<0.3.1`.
gotcha Telepath handles packing Python objects into primitive types. For client-side unpacking, you must include the `telepath-unpack.js` library in your frontend assets.
Fix: Ensure `telepath-unpack.js` is loaded in your HTML, typically via a `<script>` tag, before attempting to unpack data on the frontend.
gotcha The `JSContext` object generated on the Python side contains crucial information for the frontend to correctly re-construct your Python objects. Its script tag (`context.as_script_tag()`) must be rendered into your HTML.
Fix: Embed the output of `context.as_script_tag()` in the `<head>` or at the start of `<body>` of your HTML page.
deprecated While older manual packing methods might still function, Telepath v0.2 and v0.3 introduced and refined an API allowing classes to define their own packing logic (via the `Adapter` class and `pack` method). The recommended approach is to use this dedicated adapter pattern.
Fix: Refactor custom object packing logic to use the `telepath.Adapter` class and `register()` function for clearer and more maintainable code.

Install

pip install telepath Install Telepath

Imports

Adapter
```
from telepath import Adapter
```
register
```
from telepath import register
```
JSContext
```
from telepath import JSContext
```
pack
```
from telepath import pack
```

Quickstart

This quickstart demonstrates how to define a custom Python object, create a Telepath adapter for it, register the adapter, and then pack an instance of the object into a JavaScript-compatible format. It also shows how to generate the necessary JavaScript context for the frontend to unpack the data using the companion `telepath-unpack.js` library.

from telepath import Adapter, register, JSContext, pack

# 1. Define a custom Python object
class MyCustomObject:
    def __init__(self, message, value):
        self.message = message
        self.value = value

# 2. Define a Telepath adapter for your custom object
class MyCustomObjectAdapter(Adapter):
    js_constructor = 'telepath.MyCustomObject'

    def pack(self, obj, context):
        # Pack the Python object into a list of primitive types
        return [obj.message, obj.value]

# 3. Register the adapter with the custom object
register(MyCustomObject, MyCustomObjectAdapter)

# 4. Create an instance of your custom object
my_instance = MyCustomObject("Hello from Python!", 123)

# 5. Create a JSContext and pack the object
context = JSContext()
packed_data = pack(my_instance, context)

print("--- Python Side ---")
print(f"Original object: {my_instance.message}, {my_instance.value}")
print(f"Packed data: {packed_data}")

# The context provides the necessary JavaScript to unpack the data on the frontend.
# This script tag should be included in your HTML.
print("\n--- Frontend Integration (JavaScript) ---")
print("Include this script tag in your HTML header:")
print(context.as_script_tag())

print("\nOn the frontend, with telepath-unpack.js loaded, you would then do:")
print("// const myUnpackedObject = window.telepath.unpack(packed_data);")
print("// console.log(myUnpackedObject.message); // 'Hello from Python!'")

view raw JSON →