AYX Python SDK Overview
The AYX Python SDK is the back-end engine for building custom Alteryx Designer plugins in Python. Combine it with the AYX UI SDK, which provides the user interface, to create a complete plugin. This page covers the SDK architecture, the plugin lifecycle, the tool-type shapes, and the authoring workflow.
Importante
In the SDK API, the component that you build is a plugin (PluginV2). In the Designer Tool Palette and in the CLI, it appears as a tool. The two terms mean the same thing, and this page uses "plugin".
Requirements and Prerequisites
To develop a plugin with the AYX Python SDK, you need these items:
Component | Requirement |
|---|---|
Operating System | Windows 10, 64-bit. Designer and the AYX Plugin CLI run only on Windows. |
Alteryx Designer | Designer version compatible with the SDK release you install. Check the Alteryx Python Compatibility table for the target release. |
Python | |
AYX Python SDK ( | |
AYX Plugin CLI ( | |
Node.js and npm | |
Engine Compatibility
The AYX Python SDK requires that the AMP Engine is enabled.
Installation
To install the AYX Python SDK, run pip install ayx-python-sdk.
Architecture
The AYX Python SDK is the runtime that your plugin code imports and runs against (ayx_python_sdk.core and ayx_python_sdk.providers.amp_provider). It does these things:
Defines the plugin lifecycle that your Python code implements (
PluginV2).Provides a
providerobject that your code uses to read configuration, write output, log messages, and get anchor and connection information at runtime.Moves data between Designer and your plugin as Arrow tables (
pyarrow.TableandRecordBatch).Provides a local test harness that validates plugin logic without opening Designer.
The SDK works with a separate package, the AYX Plugin CLI (ayx-plugin-cli). The CLI scaffolds the workspace and plugin files, generates configuration and test files, and packages and installs the finished plugin in Designer. You use the two packages together. The SDK is the runtime, and the CLI is the authoring tool.
The optional user interface of a plugin is a React-based configuration panel. The CLI generates it into its own ui/ folder, and you build it with the AYX UI SDK. A plugin with no user-configurable settings can skip the user interface entirely with --omit-ui, and then it has no Node.js or npm dependency.
Mental Model
These ideas describe how the SDK works:
A workspace is the project folder that holds one or more plugins. It also holds the shared metadata (
ayx_workspace.json) and the build files.A plugin ("tool" in Designer's Tool Palette) is one Designer extension that lives in the workspace. The CLI generates it from a tool-type template.
The Python class of a plugin subclasses
PluginV2and receives aproviderobject in__init__. All input and output, configuration access, and logging go through that provider.Designer delivers data to the plugin as Arrow tables or record batches, one stream for each input or output anchor. An anchor is a named connection point on the tool icon in Designer, for example,
InputandOutput. Multiple batches can arrive on each input connection, and the plugin writes batches to named output anchors.
Plugin Lifecycle
Every PluginV2 subclass implements four callbacks:
Callback | Called When | Notes |
|---|---|---|
| The plugin is constructed. | Store the provider, read configuration, and log the startup. It also runs in update-only mode. |
| An input anchor finishes sending data, including an optional anchor that received nothing. | Not called in update-only mode. |
| A batch of records arrives on an input anchor. | Not called in update-only mode. Not called at all for input-type plugins, because they have no inputs. |
| All other processing has finished. | Clean up here. Input-type plugins, and optional-input plugins with no incoming connection, generate and write their output here instead of in |
To write output, call
provider.write_to_anchor("AnchorName", table).To log, call
provider.io.info(...),provider.io.warn(...), orprovider.io.error(...).To read the settings of the plugin, use
provider.tool_config.
Tool-Type Shapes
The --tool-type option of create-ayx-plugin scaffolds the anchor layout of the plugin. The SDK includes a worked example for each shape in AyxPythonSdk/ayx_python_sdk/examples/:
AyxSdkPassThrough: one input and one output.AyxSdkInput: no input anchor. It generates its output inon_complete.AyxSdkOutput: consumes input and produces no downstream rows.AyxSdkMultipleInputAnchorsandAyxSdkMultipleOutputAnchors: route or combine data across more than one named anchor.AyxSdkMultiConnectionsMultiOutputAnchor: multiple connections feed a single input anchor.AyxSdkOptionalInputAnchor: handles both the connected case and the unconnected case.
Start from the example that is closest to the data flow of your plugin, not from a blank file..
Authoring Workflow
Building a plugin follows the same sequence for every tool-type shape:
Create a workspace with
ayx_plugin_cli sdk-workspace-init.Create a plugin in the workspace with
ayx_plugin_cli create-ayx-plugin --tool-name <Name> --tool-type <type>. Add--omit-uifor a backend-only plugin.Implement the transformation in the generated
backend/ayx_plugins/<tool>.pymodule.Generate and edit a local test with
ayx_plugin_cli generate-tests --tool-name <Name>. Run it withayx_plugin_cli testorpytest backend. The CLI command doesn’t return the failing exit status of pytest, so usepytest backendin scripts and CI.Package the plugin with
ayx_plugin_cli create-yxi. To build and install in one step, useayx_plugin_cli designer-install --install-type user.Restart Designer, enable AMP, and test the plugin in a workflow.
For a complete example, go to the Platform SDK Quickstart Guide. It walks through this sequence with a plugin that converts a text column to uppercase. It includes the generated files, the full plugin code, a working test, and troubleshooting for each step.