Python SDK

The Alteryx Python SDK is a Python extension module that provides users the ability to write custom Alteryx plugin tools using Python. This means you can use the Python SDK to access core elements of the Alteryx Engine framework.

Prerequisites

Creating a custom tool with a Python back end involves working with an SDK. For this reason, we assume you are familiar with:

  • Python
  • File management

Python tools on Server

To use a Python SDK tool that is installed on an Alteryx Server, the workflow or app must be set to Run Mode: Unrestricted. See Server Gallery Workflows or contact your Alteryx Server admin.

Encryption on Server

  • User encryption
    • Cannot be used with remote servers
    • Not portable to other users
  • Machine encryption
    • Cannot be used with remote servers
    • Can only be decrypted on the same machine (or server)
    • Does not require user credentials
    • Recommended for scheduling and uploading to local instances of Alteryx Analytics Gallery

Python installation

Run the Python executable found in your Alteryx installation location. The following commands assume the installation location is as follows:

C:\program files\Alteryx\bin\Miniconda3\python.exe

Run the following commands:

import os, sys
os.environ['PATH'] = r'C:\program files\Alteryx\bin;' + os.environ['PATH']
sys.path.insert(1, r'C:\program files\Alteryx\bin\plugins')
import AlteryxPythonSDK

You should now be able to use the Python SDK.

SDK use

Python SDK environment

The Alteryx Python SDK is not designed to run in a standalone Python environment; it is invoked by the Alteryx Engine as part of an Alteryx workflow by initializing an embedded Python process that is specifically designed for interfacing with plugin modules. The Alteryx Python SDK is compiled to run on Python version 3.6.0 that is part of the Miniconda install currently included as part of the Alteryx Designer installation.

To use the Python SDK when creating your tool's back end, you need to create a Python file. The name should relate to the tool name, and the file needs to be saved in the tool folder.

\MyNiftyPlugin\MyNiftyPluginEngine.py

This file needs to use data gathered from the data stream and manipulate the data in accordance with the user input from the tool's GUI. It is recommended that you create the front end first to connect to the tool's data items. If you have not already created the front end, see HTML GUI SDK or Macro.

To start the design of an Alteryx Python SDK plugin module, import the Alteryx Python SDK extension module at the beginning of your script:

import AlteryxPythonSDK

The main body of the script is implemented in the AyxPlugin class. The Alteryx Engine requires the AyxPlugin class when it runs your script. If you do not have the AyxPlugin class or it is not named correctly, the following atttribute error exception occurs:

AttributeError: module '__main__' has no attribute 'AyxPlugin'

Additional classes are necessary depending on what you are creating. See Classes for an overview. See Data to manage data as records.

Python SDK tools in Iterative and Batch macros

Global variables do not reset between iterations in iterative or batch macros. The global variables will retain their value between iterations and need to be initialized directly by the Python SDK tool. Resetting global variables should happen in the __init__ method of the AyxPlugin class.

You can import additional libraries. To ensure these dependencies do not conflict with any other tools in your workflow, use a virtual environment so each tool operates as a self-contained unit. See Virtual Environment and Dependencies. If using a virtual environment, a different process is required for packaging the tool as a .yxi. See YXI Packaging and Installation.

To see an example of successful implementation of a plugin, navigate to bin\HtmlPlugins\PythonSDKExample.

Build your own tool checklist

Create a folder with the name of your tool. See Build Custom Tools.

Create icon and save it inside the tool folder. See Build Custom Tools.

Create a GUI file and save it inside the folder. See HTML GUI SDK.

Create your back end and save it inside the folder. See C++ SDK, Macro, and Python SDK.

Create a configuration file and save it inside the folder. See Tool Configuration File.

Create a package configuration file and save it with the folder. Package a Tool.

Package the package configuration file and tool folder as a yxi. See Package a Tool.