Python Tool

One Tool Example

Python has a One Tool Example. Visit Sample Workflows to learn how to access this and many other examples directly in Alteryx Designer.

The Python tool is a code editor for Python users. You should be proficient in Python before you use this tool.

After you import the Alteryx Python package, run Alteryx.help for information about useful functions:

from ayx import Alteryx
Alteryx.help()

Important

Although Designer accepts customer Python code, Alteryx doesn't provide support for customer Python code.

Get Started

The Python tool configuration window resembles a Jupyter Notebook. If you aren't familiar with Jupyter Notebooks, go to Help > User Interface Tour or Help > Notebook Help. For code assistance, see the additional references in Help.

Note

Although the tool mimics the Jupyter Notebook interface, some options may behave differently from what you expect.

Install the Data-Science Packages You Need

The Python tool includes these data-science packages:

ayx: Alteryx API
jupyter: Jupyter Metapackage
matplotlib: Python Plotting Package
numpy: NumPy, array processing for numbers, strings, records, and objects.
pandas: Powerful data structures for data analysis, time series, and statistics.
requests: HTTP for Humans
scikit-learn: A set of Python modules for machine learning and data mining.
scipy: SciPy, Scientific Library for Python
six: Utilities compatible with Python 2 and 3.
SQLAlchemy: Database Abstraction Library
statsmodels: Statistical computations and models for Python.

Additional Package Installation

Depending on what version of Designer you use, you can install additional packages with the function Alteryx.installPackages. For example, install keras:

   from ayx import Package

Package.installPackages("keras")

You can install additional Python packages only if you run Designer as an admin. Non-admin users can't install additional Python packages.

Connect Inputs

The Python tool accepts multiple inputs. After you connect inputs, you must run the workflow to cache the incoming data streams. Follow these steps to access an incoming data connection:

1. Import the Alteryx library:

   from ayx import Alteryx

2. Access the connection and provide a variable to use as a data reference:

   # Use the method this method to read data from the reference. Replace "CONNECTION_NAME" with the name of your connection.

data1 = Alteryx.read("CONNECTION_NAME")

# Read in all connections and reference the returned zero-index array. Replace "INDEX_NUMBER" with the appropriate index number from the array.

Alteryx.read(Alteryx.getIncomingConnectionNames()[INDEX_NUMBER])

3. Run your workflow before you begin work with the Python tool. This caches your data and makes it accessible to the tool.

Note

The Python tool treats your data as a Pandas DataFrame. For more information, visit pandas.pydata.org.

Configure the Tool

Set the Workflow Execution Mode

You have the option to use two modes to work with the Python tool:

Use Interactive mode to start development.
Use Production mode to improve speed when you've completed development and want to run your code through a standard Python interpreter.

Interactive Mode

Select the Interactive button. Use this mode for development. This mode allows you to interact with incoming data through a Jupyter notebook without any need to re-run the workflow to see the results of your code.

When you run your workflow, Designer performs these tasks:

Designer caches a copy of the incoming data and makes it available to the Python tool.
The Jupyter shell executes the code in the Notebook.
If your code calls the method Alteryx.write(), the Jupyter shell sends results through the output anchors.
The Jupyter Notebook displays all errors, warnings, and print statements, just like when you select Run All.

Production Mode

Select the Production button. Use this mode for models in production. In this mode, Designer consolidates all Python cells from the Jupyter Notebook into a single, read only script. Designer passes that script to your Python interpreter.

When you run the workflow, Designer performs these tasks:

It bypasses the Jupyter shell, then runs the read-only script through a standard Python interpreter.
It doesn'tdisplay errors, warnings, or print statements.

To edit the Production mode script, select Interactive mode, then edit the cells in the Jupyter Notebook. After you complete your edits, select Production mode.

Set Data Storage Format

The Python tool has two format options: SQLite and YXDB.

SQLite

Select the Alteryx menu in the Configuration window of the Python tool.
Select Sqlite override.

YXDB

Follow these steps to use the YXDB data-storage format.

Select the Alteryx menu in the Configuration window of the Python tool.
Deselect Sqlite override to remove the check mark.

	SQLite	YXDB
Blob	No Support	Support
Spatial Objects	No Support	Pass spatial objects between the Python tool and other tools. Use metadata tags when you create spatial-object outputs from the Python tool.
Column Limitation	Limit is 2000	No Limit
Null-values Note	No Support	Designer converts numeric or byte columns to the float64 data type (i.e., double precision float).

If you don't change the arrangement of rows or if you use GeoSpatial Python, Alteryx recommends that you slice the GeoSpatial data off the dataset and rejoin it after the Python tool. The reason for that is the conversion to and from Alteryx Binary and GeoSpatial text is slow.

Import a File or Directory

You can import a file or directory in two ways:

Use the import function in the Alteryx menu to import individual Python scripts or Jupyter Notebooks.
Use the import command to import a directory.

Follow these steps to import a Python script or Jupyter Notebook with the import function:

Select the Alteryx menu.
Select Import Script.
Select Choose File.
Navigate to a .py or .ipynb file and select Import.

Use the Kernel Menu

Issue any of these commands from the Kernel menu:

To stop processing, select Interrupt.
To restart processing, select Restart.
To clear the workbook of immediate results, select Reconnect.
Change kernel doesn't provide functionality.
Alteryx recommends that you don't select Shutdown.

Follow Best Practices

These best practices help you use the Python tool successfully:

Use the method Alteryx.getWorkflowConstant when you refer to a workflow constant, such as Engine.WorkflowDirectory. Otherwise, the result or output of the command permanently replaces the command in your Jupyter Notebook when you run your code.

Warning

Avoid using % wrappers in workflow constants. Instead, for example, use this to call the Engine.WorkflowDirectory:

from ayx import Alteryx

Alteryx.getWorkflowConstant("Engine.WorkflowDirectory")

Output Data from the Tool

Use the method Alteryx.write to output data from the tool.

To send data to other tools on the canvas, use the method like this:

   # Replace "PANDAS_DF" with your data, in DataFrame form.
# Replace "OUTPUT_ANCHOR_NUM" with the number of your output anchor.

Alteryx.write(PANDAS_DATAFRAME, OUTPUT_ANCHOR_NUM)

The Alteryx.write method accepts only Pandas DataFrames. If you have data in another format, use the Pandas library to convert it to a DataFrame. The Pandas library is already installed as part of Designer. Access it in the Jupyter Notebook with import pandas.

You can send up to five DataFrames to the output anchors.

In this section: