{"id":8885,"library":"canvas","title":"Canvas Python SDK","description":"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.","status":"active","version":"0.132.0","language":"en","source_language":"en","source_url":"https://github.com/canvas-sdk/python-sdk","tags":["sdk","canvas","low-code","automation","platform-integration"],"install":[{"cmd":"pip install canvas","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Primary HTTP client for API communication with the Canvas platform.","package":"httpx","optional":false}],"imports":[{"note":"The PyPI package is 'canvas', but the primary module to import from is 'canvas_sdk'.","wrong":"from canvas import Canvas","symbol":"Canvas","correct":"from canvas_sdk import Canvas"},{"note":"Used for defining input and output arguments for actions and entities.","symbol":"Args","correct":"from canvas_sdk.args import Args"},{"note":"Decorator for defining Python functions as Canvas Actions.","symbol":"python_action","correct":"from canvas_sdk.functions import python_action"}],"quickstart":{"code":"import os\nfrom canvas_sdk import Canvas\n\n# Ensure CANVAS_API_KEY is set as an environment variable\n# Example: export CANVAS_API_KEY=\"your_api_key_here\"\napi_key = os.environ.get(\"CANVAS_API_KEY\", \"\")\n\nif not api_key:\n    print(\"Warning: CANVAS_API_KEY environment variable not set.\")\n    print(\"Please set it to connect to your Canvas instance.\")\n    # In a real application, you might raise an error here.\nelse:\n    try:\n        canvas_client = Canvas(api_key=api_key)\n        print(\"Canvas client initialized successfully.\")\n        \n        # Example: Attempt to retrieve entities from Canvas instance\n        print(\"Attempting to retrieve entities...\")\n        entities_page = canvas_client.get_entities() # This sends an API request\n        print(f\"Successfully retrieved {len(entities_page.data)} entities. First 3 names: {[e.name for e in entities_page.data[:3]]}\")\n    except Exception as e:\n        print(f\"Failed to connect or retrieve entities. Ensure API key is valid and Canvas is reachable. Error: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always import from `canvas_sdk`: `from canvas_sdk import Canvas`.","message":"The PyPI package name is `canvas`, but the main import module is `canvas_sdk`. Importing `from canvas import Canvas` will result in a `ModuleNotFoundError`.","severity":"gotcha","affected_versions":"All versions"},{"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\")`).","message":"The `api_key` argument for `Canvas()` initialization became mandatory. Older code that initialized `Canvas()` without an API key will now fail.","severity":"breaking","affected_versions":"<0.50.0 to >=0.50.0"},{"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.","message":"The `PythonAction` class and decorator were significantly refactored and moved. Code using `from canvas_sdk.actions import PythonAction` or the decorator might break.","severity":"breaking","affected_versions":"<0.80.0 to >=0.80.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"0.100.0 and above"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change your import statement from `from canvas import Canvas` to `from canvas_sdk import Canvas`.","cause":"Attempting to import directly from the PyPI package name 'canvas' instead of the module 'canvas_sdk'.","error":"ModuleNotFoundError: No module named 'canvas'"},{"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\"))`.","cause":"The `Canvas` client constructor now requires an `api_key` argument, which was not provided or was optionally omitted in older versions.","error":"TypeError: Canvas.__init__() missing 1 required positional argument: 'api_key'"},{"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.","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.","error":"AttributeError: 'Canvas' object has no attribute 'register_action'"}]}