Distribute a geoprocessing module—ArcGIS AllSource

Distribute and install a custom geoprocessing module by following standard patterns of distributing Python packages.

This topic follows the foo module example from the Create geoprocessing modules topic.

Distribute a geoprocessing module as a compressed archive

To distribute a geoprocessing module as a compressed archive, archive the module (the foo package, as an example) as a .zip file or other preferred compression format. Then provide the following steps to your audience:

Clone the default ArcGIS AllSource conda environment.
Note:
Modifying the ArcGIS AllSource default Python environment (arcgispro-py3) is not advisable and may result in unintended consequences. It is recommended that you only modify a cloned environment.
Extract the foo package into the clone's site-packages folder (%LocalAppData%\ESRI\conda\envs\<clone_environment_name>\Lib\site-packages).
Switch the current ArcGIS AllSource conda environment to the cloned environment using the Python Package Manager.

Distribute a geoprocessing module with pip

Geoprocessing modules can be distributed through pip with a wheel file by using the setuptools library.

Note:

To distribute a module with pip, the conda, pip, setuptools, and wheel packages are required in your Python environment. These packages are included with the default ArcGIS AllSource Python environment.

Create a wheel file for distribution

A distribution package is required for the foo package so that it can be installed in the Python site-packages directory. With a distribution package, the package can be shared and used by others.

To create a wheel file, complete the following steps:

Create a setup.py script similar to the following:

setup.py

Sample code to create a setup.py script.

import os 
from setuptools import setup 
 
def read(fname): 
    return open(os.path.join(os.path.dirname(__file__), fname)).read() 
 
setup(name='foo', 
      version='1.0',
      author='Esri',
      description=("Example for extending geoprocessing through Python modules"),
      long_description=read('Readme.txt'),
      python_requires='~=3.3',
      packages=['foo'], 
      package_data={'foo':['esri/toolboxes/*',  
                  'esri/arcpy/*', 'esri/help/gp/*',  
                  'esri/help/gp/toolboxes/*', 'esri/help/gp/messages/*'] 
                  }, 
      )

If distributing a geoprocessing module that supports additional languages, the setup function's package_data parameter must include the additional language directories. For example, if including a Spanish localization, setup.py should be the following:

setup.py for Spanish localization

Sample code for setup.py to include Spanish localization directories.

import os 
from setuptools import setup 
 
def read(fname): 
    return open(os.path.join(os.path.dirname(__file__), fname)).read() 
 
setup(name='foo', 
      version='1.0', 
      author='Esri', 
      description=("Example for extending geoprocessing through Python modules"), 
      long_description=read('Readme.txt'), 
      python_requires='~=3.3', 
      packages=['foo'], 
      package_data={'foo':['esri/toolboxes/*',  
                  'esri/arcpy/*', 'esri/help/gp/*',  
                  'esri/help/gp/toolboxes/*', 'esri/help/gp/messages/*',
                  'esri/help/es/gp/*', 'esri/help/es/gp/toolboxes/*', 
                  'esri/help/es/gp/messages/*'] 
                  }, 
      )

The setup.py build script sets several properties and directs the build utility to the package directory. The long description is stored in an accompanying Readme.txt file. The setup.py and Readme.txt files should be located in the src directory. For more information on using setup(), see Packaging and distributing projects. The directory structure for the foo package will be as follows (exclude the additional es Spanish language folder if only supporting English):

Src
├  setup.py
├  Readme.txt
└──foo
    ├  __init__.py 
    ├  bar.py
    └──esri
        ├──arcpy
        │   └  SamplePythonToolbox.py
        ├──help
        │   ├──es
        │   │   └──gp
        │   │       ├  SamplePythonToolbox_toolbox.xml
        │   │       ├  SampleTool_SamplePythonToolbox.xml
        │   │       ├──messages
        │   │       │   └  messages.xml
        │   │       └──toolboxes
        │   │           └  SamplePythonToolbox.xml
        │   └──gp
        │       ├  SamplePythonToolbox_toolbox.xml
        │       ├  SampleTool_SamplePythonToolbox.xml
        │       ├──messages
        │       │   └  messages.xml
        │       └──toolboxes
        │           └  SamplePythonToolbox.xml
        └──toolboxes
            ├  SamplePythonToolbox.pyt
            ├  SamplePythonToolbox.pyt.xml
            └  SamplePythonToolbox.SampleTool.pyt.xml

To build an installer for the foo package, run the following command from the src directory using the command prompt:
```
python setup.py sdist bdist_wheel
```
The sdist bdist_wheel command creates dist, build, and foo.egg-info folders in the src parent directory. In the dist folder, a wheel file named foo-1.0-py3-none-any.whl is created. A wheel file can be distributed directly with pip.

Install from a wheel file using pip

After cloning and switching environments, open the Python Command Prompt to install the wheel file directly with pip. Pip will install the wheel file in the active environment.

Run the following command from the Python Command Prompt from the src\dist directory:

pip install foo-1.0-py3-none-any.whl

When the foo package is installed, the following directory structure will be created in the site-packages directory (exclude the additional es Spanish language folder if only supporting English):

site-packages
└──foo
    ├  __init__.py 
    ├  bar.py
    └──esri
        ├──arcpy
        │   └  SamplePythonToolbox.py
        ├──help
        │   ├──es
        │   │   └──gp
        │   │       ├  SamplePythonToolbox_toolbox.xml
        │   │       ├  SampleTool_SamplePythonToolbox.xml
        │   │       ├──messages
        │   │       │   └  messages.xml
        │   │       └──toolboxes
        │   │           └  SamplePythonToolbox.xml
        │   └──gp
        │       ├  SamplePythonToolbox_toolbox.xml
        │       ├  SampleTool_SamplePythonToolbox.xml
        │       ├──messages
        │       └──toolboxes
        │           └  SamplePythonToolbox.xml
        └──toolboxes
            ├  SamplePythonToolbox.pyt
            ├  SamplePythonToolbox.pyt.xml
            └  SamplePythonToolbox.SampleTool.pyt.xml

Note:

The messages folder is only present if there are message files in the package.

If your computer has restrictions that prohibit running an installation, copying the foo directory from the build\lib directory to the %LocalAppData%\ESRI\conda\envs\<environment_name>\Lib\site-packages folder will produce the same effect as installing from an archived file. When copying the package manually, it will not be recognized or managed by pip.

Use the geoprocessing module

In ArcGIS AllSource, the SamplePythonToolbox tool is available from the Geoprocessing pane and is searchable. The toolbox and tool can also be accessed from arcpy as follows: arcpy.SamplePythonToolbox.SampleTool()

Using ArcGIS AllSource and the Python package development process, it is possible to build and distribute a package that extends geoprocessing with custom toolboxes that can be viewed and executed from within the ArcGIS system toolboxes and arcpy, and the geoprocessing module can be internationalized to support multiple languages.

Distribute a geoprocessing module as a compressed archive

Note:

Distribute a geoprocessing module with pip

Note:

Create a wheel file for distribution

Install from a wheel file using pip

Note:

Use the geoprocessing module

Related topics

In this topic