Python Engine 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.
Creating a custom tool with a Python back end involves working with an SDK. For this reason, we assume you are familiar with:
- 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
Run the Python executable found in your Alteryx installation location. The following commands assume the installation location is as follows:
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.
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.
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:
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:
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.