Comparing custom and Python toolboxes

The script tool framework was introduced at ArcGIS 9.0, and is geared toward creating Python-based tools for new users, but it is an inefficient process for more experienced users. In the script tool framework, you do the following:

  • You define parameters through the wizard.
  • You create validation code that lives in the toolbox.
  • Plus, you create and maintain the source script separately.

All of these parts are segregated and more difficult to manage collectively.

At ArcGIS 10.1, a second approach for creating Python-based tools was introduced, Python toolboxes. In a Python toolbox, parameter definitions, validation code, and the source code are all handled with Python code, making it easier to create and maintain Python tools.

For those with Python experience, Python toolboxes provide the opportunity to take advantage of your Python skills and create tools entirely and easily out of Python. If you are new to Python, you will be better suited to creating tools in custom toolboxes, where the wizard takes you through the necessary parts of a script tool.

If you use or are planning to use significant validation code in your script tool, almost certainly you will find the experience more straightforward in a Python toolbox.

Organization

Custom toolboxesPython toolboxes

Script tools in a custom toolbox are organized into three parts:

  1. The tool and parameter definitions, which are defined through a wizard.
  2. The optional validation code that provides extra control on parameter behavior and resides in the toolbox.
  3. The source code is maintained separately from the toolbox, usually as a Python script (.py).

A Python toolbox is a Python script with a .pyt extension, which contains all aspects of a toolbox and its tools: parameters, validation, and execution. This is done using Python classes: one class for the toolbox and one class for each of the tools.

Editing

Custom toolboxesPython toolboxes

The source code can be edited in any editor.

The parameters are edited through the script tool wizard.

Validation code (if used) can be edited from the Validation tab on the script tool's dialog box or edited in a separate Python integrated development environment (IDE).

Python toolbox files (.pyt) can be edited in any editor, and all parts of the tool (parameter definitions, validation code, and source code) can be edited in the same place.

As Python toolboxes can only be edited in an editor, they do not support copying/pasting within a toolbox or between toolboxes.

Using other tools

Custom toolboxesPython toolboxes

Custom toolboxes support various tool types, including Python script tools and model tools (built with ModelBuilder).

Python toolboxes do not directly support other tool types; that is, you cannot add model or built-in tools to your Python toolbox. However, you can call tools in other toolboxes from within the Python toolbox code.

Debugging

Custom toolboxesPython toolboxes

IDEs can only debug Python files (.py). For Python code in script tool validation (embedded in a toolbox), copy the code to an external Python file and replace the code in the Python toolbox with the example below. You can then open the Python file in your IDE and set breakpoints, attach the IDE to ArcGIS Pro, and run your script tool. Upon completion of code modification, copy the contents of the Python file back into the tool validation.

IDEs can only debug Python files (.py). For code in a Python toolbox file (.pyt), copy the code to an external Python file, and replace the code in the Python toolbox with the example below. You can then open the Python file in your IDE and set breakpoints, attach the IDE to ArcGIS Pro, and use your Python toolbox. Upon completion of code modification, copy the contents of the Python file back into the Python toolbox.

Learn more about debugging Python in ArcGIS Pro

Additional security

Custom toolboxesPython toolboxes

Script tools in a custom toolbox can have their source code embedded into the toolbox and secured with a password.

A Python toolbox .pyt file can be encrypted in place and secured with a password.