Canvas Python SDK

0.132.0 · active · verified Thu Apr 16

The Canvas Python SDK (pypi package `canvas`, import `canvas_sdk`) allows you to programmatically define and interact with your Canvas instance. It simplifies the process of creating and managing event-driven actions, workflows, and integrations within the Canvas low-code platform. Currently at version 0.132.0, the library maintains a frequent release cadence to support new Canvas features and improvements.

Common errors

```
ModuleNotFoundError: No module named 'canvas'
```
cause Attempting to import directly from the PyPI package name 'canvas' instead of the module 'canvas_sdk'.

fix Change your import statement from `from canvas import Canvas` to `from canvas_sdk import Canvas`.
```
TypeError: Canvas.__init__() missing 1 required positional argument: 'api_key'
```
cause The `Canvas` client constructor now requires an `api_key` argument, which was not provided or was optionally omitted in older versions.

fix Pass your Canvas API key as `api_key` to the `Canvas` constructor, e.g., `canvas = Canvas(api_key=os.environ.get("CANVAS_API_KEY"))`.
```
AttributeError: 'Canvas' object has no attribute 'register_action'
```
cause The direct `register_action` method for manually crafted action objects might have been removed or replaced with a more integrated registration mechanism, often through decorators or `canvas.register()` with SDK-defined objects.

fix Use the `@python_action` decorator (`from canvas_sdk.functions import python_action`) for defining Python actions, or refer to `canvas_client.register()` with appropriate SDK-defined `Entity` or `Action` objects (e.g., `canvas_client.register(action=my_action_object)`). Consult the latest SDK documentation for the correct registration pattern.

Warnings

gotcha The PyPI package name is `canvas`, but the main import module is `canvas_sdk`. Importing `from canvas import Canvas` will result in a `ModuleNotFoundError`.
Fix: Always import from `canvas_sdk`: `from canvas_sdk import Canvas`.
breaking The `api_key` argument for `Canvas()` initialization became mandatory. Older code that initialized `Canvas()` without an API key will now fail.
Fix: Ensure `Canvas(api_key="your_key")` is always called with a valid API key. It's recommended to load this from environment variables (e.g., `os.environ.get("CANVAS_API_KEY")`).
breaking The `PythonAction` class and decorator were significantly refactored and moved. Code using `from canvas_sdk.actions import PythonAction` or the decorator might break.
Fix: For defining actions using a decorator, use `from canvas_sdk.functions import python_action`. For the underlying action classes, refer to `canvas_sdk.actions.Action` and its related types in the latest documentation.
deprecated The `base_url` argument for `Canvas()` client initialization is deprecated and will be removed in future versions. The SDK will automatically infer the correct Canvas platform URL.
Fix: Remove the `base_url` argument from your `Canvas` client initialization. If you have a custom Canvas instance URL, consult the documentation for alternative configuration methods.

Install

pip install canvas Install latest version

Imports

Canvas
wrong:
```
from canvas import Canvas
```
correct:
```
from canvas_sdk import Canvas
```
The PyPI package is 'canvas', but the primary module to import from is 'canvas_sdk'.
Args
```
from canvas_sdk.args import Args
```
Used for defining input and output arguments for actions and entities.
python_action
```
from canvas_sdk.functions import python_action
```
Decorator for defining Python functions as Canvas Actions.

Quickstart

Initializes the Canvas SDK client using an API key from environment variables, and then attempts to fetch existing entities from your Canvas instance. This demonstrates basic connectivity and a read operation with the Canvas platform.

import os
from canvas_sdk import Canvas

# Ensure CANVAS_API_KEY is set as an environment variable
# Example: export CANVAS_API_KEY="your_api_key_here"
api_key = os.environ.get("CANVAS_API_KEY", "")

if not api_key:
    print("Warning: CANVAS_API_KEY environment variable not set.")
    print("Please set it to connect to your Canvas instance.")
    # In a real application, you might raise an error here.
else:
    try:
        canvas_client = Canvas(api_key=api_key)
        print("Canvas client initialized successfully.")
        
        # Example: Attempt to retrieve entities from Canvas instance
        print("Attempting to retrieve entities...")
        entities_page = canvas_client.get_entities() # This sends an API request
        print(f"Successfully retrieved {len(entities_page.data)} entities. First 3 names: {[e.name for e in entities_page.data[:3]]}")
    except Exception as e:
        print(f"Failed to connect or retrieve entities. Ensure API key is valid and Canvas is reachable. Error: {e}")

view raw JSON →