Toolbox¶

CLASS	DESCRIPTION
`Done`	An Empty Output parameter that can be used to signal that a tool has completed in Model Builder
`Double`	Simple Double/Float parameter with default and filter passthroughs
`FeatureDataset`	Simple Feature Dataset parameter with filter and default passthroughs
`FeatureLayer`	Simple Feature Layer parameter with filter and default passthroughs
`FeatureLayerList`	Simple Feature Layer parameter with filter and default passthroughs
`FilePath`	Simple filepath input with default and filter passthroughs
`Folder`	Simple Feature Layer parameter with filter and default passthroughs
`HiddenString`	Simple string input parameter with filter options and default passthrough
`Integer`	Simple Integer number parameter with default and filter passthroughs
`MultiFilePath`	Simple milti-filepath input with default and filter passthroughs
`Parameters`	Wrap a list of parameters and override the index to allow indexing by name
`String`	Simple string input parameter with filter options and default passthrough
`StringList`	Simple string list with default and filter passthroughs
`TextBox`	Simple multiline text box parameter with filter options and default passthrough
`Toggle`	Simple toggle button with a name and default state
`Tool`
`ValueTable`	Simple ValueTable parameter with filter and default passthroughs

FUNCTION	DESCRIPTION
`safe_load`	Safely load in tools to a toolbox placing all failed imports in a `Broken Tools` category
`toolify`	Convert a typed function into a tool for the specified Toolbox class

Done ¶

Done()

Bases: Parameter

An Empty Output parameter that can be used to signal that a tool has completed in Model Builder

Source code in src/arcpie/toolbox.py

def __init__(self) -> None:
    self.__class__.__name__ =  __name__ = 'Parameter'
    super().__init__(
        displayName='Done',
        name='done',
        direction='Output',
        parameterType='Derived',
    )

Double ¶

Double(
    displayName: str,
    options: list[float] | None = None,
    default: float | None = None,
    required: bool = True,
    name: str | None = None,
    category: str | None = None,
)

Bases: Parameter

Simple Double/Float parameter with default and filter passthroughs

Source code in src/arcpie/toolbox.py

def __init__(self, displayName: str, 
             options: list[float]|None=None, 
             default: float|None=None,
             required: bool=True,
             name: str|None=None,
             category: str|None=None) -> None:

    self.__class__.__name__ =  __name__ = 'Parameter'
    super().__init__(
        displayName=displayName,
        # Snake Case the name
        name=name or displayName.lower().replace(' ', '_'),
        parameterType='Required' if required else 'Optional',
        datatype='GPDouble',
        direction='Input',
        category=category,
    )
    if self.filter and options:
        self.filter.list = options
    if default is not None:
        self.value = default

FeatureDataset ¶

FeatureDataset(
    displayName: str,
    options: list[str] | None = None,
    default: str | None = None,
    required: bool = True,
    name: str | None = None,
    category: str | None = None,
)

Bases: Parameter

Simple Feature Dataset parameter with filter and default passthroughs

Source code in src/arcpie/toolbox.py

def __init__(self, displayName: str, 
             options: list[str]|None=None,
             default: str|None=None,
             required: bool=True,
             name: str|None=None,
             category: str|None=None) -> None:

    self.__class__.__name__ =  __name__ = 'Parameter'
    super().__init__(
        displayName=displayName,
        # Snake Case the name
        name=name or displayName.lower().replace(' ', '_'),
        parameterType='Required' if required else 'Optional',
        datatype='DEFeatureDataset',
        direction='Input',
        category=category,
    )
    if self.filter and options:
        self.filter.list = options
    if default is not None:
        self.value = default

FeatureLayer ¶

FeatureLayer(
    displayName: str,
    options: list[str] | None = None,
    default: str | None = None,
    required: bool = True,
    name: str | None = None,
    allow_create: bool = False,
    category: str | None = None,
)

Bases: Parameter

Simple Feature Layer parameter with filter and default passthroughs

Source code in src/arcpie/toolbox.py

def __init__(self, displayName: str, 
             options: list[str]|None=None,
             default: str|None=None,
             required: bool=True,
             name: str|None=None,
             allow_create: bool=False,
             category: str|None=None) -> None:

    self.__class__.__name__ =  __name__ = 'Parameter'
    super().__init__(
        displayName=displayName,
        # Snake Case the name
        name=name or displayName.lower().replace(' ', '_'),
        parameterType='Required' if required else 'Optional',
        datatype='GPFeatureLayer',
        direction='Input',
        category=category,
    )
    if self.filter and options:
        self.filter.list = options
    if default is not None:
        self.value = default
    if allow_create:
        self.controlCLSID = '{60061247-BCA8-473E-A7AF-A2026DDE1C2D}'

FeatureLayerList ¶

FeatureLayerList(
    displayName: str,
    options: list[str] | None = None,
    default: str | None = None,
    required: bool = True,
    name: str | None = None,
    allow_create: bool = False,
    category: str | None = None,
)

Bases: Parameter

Simple Feature Layer parameter with filter and default passthroughs

Source code in src/arcpie/toolbox.py

def __init__(self, displayName: str, 
             options: list[str]|None=None,
             default: str|None=None,
             required: bool=True,
             name: str|None=None,
             allow_create: bool=False,
             category: str|None=None) -> None:

    self.__class__.__name__ =  __name__ = 'Parameter'
    super().__init__(
        displayName=displayName,
        # Snake Case the name
        name=name or displayName.lower().replace(' ', '_'),
        parameterType='Required' if required else 'Optional',
        datatype='GPFeatureLayer',
        direction='Input',
        category=category,
        multiValue=True,
    )
    if self.filter and options:
        self.filter.list = options
    if default is not None:
        self.value = default
    if allow_create:
        self.controlCLSID = '{60061247-BCA8-473E-A7AF-A2026DDE1C2D}'

FilePath ¶

FilePath(
    displayName: str,
    options: list[str] | None = None,
    default: str | None = None,
    required: bool = True,
    name: str | None = None,
    category: str | None = None,
)

Bases: Parameter

Simple filepath input with default and filter passthroughs

Source code in src/arcpie/toolbox.py

def __init__(self, displayName: str, 
             options: list[str]|None=None, 
             default: str|None=None,
             required: bool=True,
             name: str|None=None,
             category: str|None=None) -> None:

    self.__class__.__name__ =  __name__ = 'Parameter'
    super().__init__(
        displayName=displayName,
        # Snake Case the name
        name=name or displayName.lower().replace(' ', '_'),
        parameterType='Required' if required else 'Optional',
        datatype='DEFile',
        direction='Input',
        category=category,
    )
    if self.filter and options:
        self.filter.list = options
    if default is not None:
        self.value = default

Folder ¶

Folder(
    displayName: str,
    options: list[str] | None = None,
    default: str | None = None,
    required: bool = True,
    name: str | None = None,
    category: str | None = None,
)

Bases: Parameter

Simple Feature Layer parameter with filter and default passthroughs

Source code in src/arcpie/toolbox.py

def __init__(self, displayName: str, 
             options: list[str]|None=None,
             default: str|None=None,
             required: bool=True,
             name: str|None=None,
             category: str|None=None) -> None:

    self.__class__.__name__ =  __name__ = 'Parameter'
    super().__init__(
        displayName=displayName,
        # Snake Case the name
        name=name or displayName.lower().replace(' ', '_'),
        parameterType='Required' if required else 'Optional',
        datatype='DEFolder',
        direction='Input',
        category=category,
    )
    if self.filter and options:
        self.filter.list = options
    if default is not None:
        self.value = default

HiddenString ¶

HiddenString(
    displayName: str,
    options: list[str] | None = None,
    default: str | None = None,
    required: bool = True,
    name: str | None = None,
    category: str | None = None,
)

Bases: Parameter

Simple string input parameter with filter options and default passthrough

Source code in src/arcpie/toolbox.py

def __init__(self, displayName: str, 
             options: list[str]|None=None, 
             default: str|None=None,
             required: bool=True,
             name: str|None=None,
             category: str|None=None) -> None:

    self.__class__.__name__ =  __name__ = 'Parameter'
    super().__init__(
        displayName=displayName,
        # Snake Case the name
        name=name or displayName.lower().replace(' ', '_'),
        parameterType='Required' if required else 'Optional',
        datatype='GPStringHidden',
        direction='Input',
        category=category,
    )
    if self.filter and options:
        self.filter.list = options
    if default is not None:
        self.value = default

Integer ¶

Integer(
    displayName: str,
    options: list[int] | range | None = None,
    default: int | None = None,
    required: bool = True,
    name: str | None = None,
    category: str | None = None,
)

Bases: Parameter

Simple Integer number parameter with default and filter passthroughs

Source code in src/arcpie/toolbox.py

def __init__(self, displayName: str, 
             options: list[int]|range|None=None, 
             default: int|None=None,
             required: bool=True,
             name: str|None=None,
             category: str|None=None) -> None:

    self.__class__.__name__ =  __name__ = 'Parameter'
    super().__init__(
        displayName=displayName,
        # Snake Case the name
        name=name or displayName.lower().replace(' ', '_'),
        parameterType='Required' if required else 'Optional',
        datatype='GPLong',
        direction='Input',
        category=category,
    )
    if self.filter and options:
        if isinstance(options, range):
            if options.step:
                self.filter.list = list(options)
            else:
                self.filter.type = 'Range'
                self.filter.list = [options.start, options.stop]
        else:
            self.filter.list = options
    if default is not None:
        self.value = default

MultiFilePath ¶

MultiFilePath(
    displayName: str,
    options: list[str] | None = None,
    default: str | None = None,
    required: bool = True,
    name: str | None = None,
    category: str | None = None,
)

Bases: Parameter

Simple milti-filepath input with default and filter passthroughs

Source code in src/arcpie/toolbox.py

def __init__(self, displayName: str, 
             options: list[str]|None=None, 
             default: str|None=None,
             required: bool=True,
             name: str|None=None,
             category: str|None=None) -> None:

    self.__class__.__name__ =  __name__ = 'Parameter'
    super().__init__(
        displayName=displayName,
        # Snake Case the name
        name=name or displayName.lower().replace(' ', '_'),
        parameterType='Required' if required else 'Optional',
        datatype='DEFile',
        direction='Input',
        category=category,
        multiValue=True,
    )
    if self.filter and options:
        self.filter.list = options
    if default is not None:
        self.value = default

Parameters ¶

Bases: list[Parameter]

Wrap a list of parameters and override the index to allow indexing by name

String ¶

String(
    displayName: str,
    options: list[str] | None = None,
    default: str | None = None,
    required: bool = True,
    name: str | None = None,
    category: str | None = None,
)

Bases: Parameter

Simple string input parameter with filter options and default passthrough

Subclassed by:

Modules Toolbox TextBox

Source code in src/arcpie/toolbox.py

def __init__(self, displayName: str, 
             options: list[str]|None=None, 
             default: str|None=None,
             required: bool=True,
             name: str|None=None,
             category: str|None=None) -> None:

    self.__class__.__name__ =  __name__ = 'Parameter'
    super().__init__(
        displayName=displayName,
        # Snake Case the name
        name=name or displayName.lower().replace(' ', '_'),
        parameterType='Required' if required else 'Optional',
        datatype='GPString',
        direction='Input',
        category=category,
    )
    if self.filter and options:
        self.filter.list = options
    if default is not None:
        self.value = default

StringList ¶

StringList(
    displayName: str,
    options: list[str] | None = None,
    defaults: list[str] | None = None,
    required: bool = True,
    name: str | None = None,
    category: str | None = None,
)

Bases: Parameter

Simple string list with default and filter passthroughs

Source code in src/arcpie/toolbox.py

def __init__(self, displayName: str, 
             options: list[str]|None=None, 
             defaults: list[str]|None=None,
             required: bool=True,
             name: str|None=None,
             category: str|None=None) -> None:

    self.__class__.__name__ =  __name__ = 'Parameter'
    super().__init__(
        displayName=displayName,
        # Snake Case the name
        name=name or displayName.lower().replace(' ', '_'),
        parameterType='Required' if required else 'Optional',
        datatype='GPString',
        direction='Input',
        category=category,
        multiValue=True,
    )
    if self.filter and options:
        self.filter.list = options
    if defaults:
        self.values = defaults

TextBox ¶

TextBox(
    displayName: str,
    options: list[str] | None = None,
    default: str | None = None,
    required: bool = True,
    name: str | None = None,
    category: str | None = None,
)

Bases: String

Simple multiline text box parameter with filter options and default passthrough

Source code in src/arcpie/toolbox.py

def __init__(self, displayName: str, 
             options: list[str] | None = None, 
             default: str | None = None, 
             required: bool = True, 
             name: str | None = None, 
             category: str | None = None) -> None:
    super().__init__(displayName, options, default, required, name, category)
    self.controlCLSID = '{E5456E51-0C41-4797-9EE4-5269820C6F0E}'

Toggle ¶

Toggle(
    displayName: str,
    default: bool = False,
    name: str | None = None,
    category: str | None = None,
)

Bases: Parameter

Simple toggle button with a name and default state

Source code in src/arcpie/toolbox.py

def __init__(self, displayName: str, 
             default: bool=False, 
             name: str|None=None,
             category: str|None=None) -> None:

    self.__class__.__name__ =  __name__ = 'Parameter'
    super().__init__(
        displayName=displayName,
        # Snake Case the name
        name=name or displayName.lower().replace(' ', '_'),
        parameterType='Required',
        datatype='GPBoolean',
        direction='Input',
        category=category,
    )
    self.value = default

Tool ¶

Tool()

Bases: ToolABC

ATTRIBUTE	DESCRIPTION
`project`	Get the current project that the tool is running in if it exists (otherwise: None) TYPE: `Project`

Source code in src/arcpie/toolbox.py

def __init__(self) -> None:
    self.label: str = self.__class__.__name__
    self.description: str = self.__doc__ or 'No Descrption Provided'
    self.category: str | None = None

project `property` ¶

project: Project

Get the current project that the tool is running in if it exists (otherwise: None)

ValueTable ¶

ValueTable(
    displayName: str,
    columns: dict[str, ParameterDatatype],
    filters: dict[str, list[Any]] | None = None,
    defaults: list[dict[str, str]] | None = None,
    required: bool = True,
    name: str | None = None,
    category: str | None = None,
)

Bases: Parameter

Simple ValueTable parameter with filter and default passthroughs

Source code in src/arcpie/toolbox.py

def __init__(self, displayName: str, 
             columns: dict[str, ParameterDatatype],
             filters: dict[str, list[Any]]|None=None,
             defaults: list[dict[str, str]]|None=None,
             required: bool=True,
             name: str|None=None,
             category: str|None=None) -> None:

    self.__class__.__name__ =  __name__ = 'Parameter'
    super().__init__(
        displayName=displayName,
        # Snake Case the name
        name=name or displayName.lower().replace(' ', '_'),
        parameterType='Required' if required else 'Optional',
        datatype='GPValueTable',
        direction='Input',
        category=category,
    )
    self.columns = [[v, k] for k, v in columns.items()]
    if filters:
        for i, k in enumerate(columns):
            if k in filters:
                self.filters[i].list = filters[k]
    if defaults is not None:
        self.values = defaults

safe_load ¶

safe_load(
    tools: dict[str, list[str]],
    *,
    scope: dict[str, Any] | None = None,
    reload_module: bool = False,
) -> list[type[ToolABC]]

Safely load in tools to a toolbox placing all failed imports in a Broken Tools category

PARAMETER	DESCRIPTION
`tools` ¶	A mapping of tool modules to tool files or tool classes in a module TYPE: `dict[str, list[str]]`
`scope` ¶	The `globals()` dict for the Toolbox scope (required so loading happend in Toolbox scope) TYPE: `dict[str, Any]` DEFAULT: `None`
`reload_module` ¶	Reload the module after importing (default: False) TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`list[type[ToolABC]]`	A list of tool classes

Note

To isolate bugs in a large toolbox, it is reccomended that you use file/module level importing with matching toolclass names (e.g. Tool.py -> class Tool) where the Tool mapping is: Tools = {'tools': ['Tool.py']} instead of: Tools = {'tools.Tool': ['Tool']} This allows the import to fail softly on a single tool instead of breaking imports for all other toolclasses in that Tool.py module.

Any tools with errors will be placed in a Broken Tools category in the toolbox with the full stack trace placed in its description field. The final component of the exception will be placed at the end of the tool label for easy debugging.

Example

>>> # File import
>>> Tools = {
...     # import matching class from named file in a submodule (tools)
...     # where ToolFileA is ToolFileA.py with a class ToolFileA
...     'tools': ['ToolFileA', 'ToolFileB'],
...     
...     # Import explicit ToolClass from toolfile (MyTools.py)
...     # NOT RECOMMENDED
...     'tools.MyTools': ['ToolClassA', 'ToolClassB'],
... }
>>> tools = safe_import(globals(), Tools)

Source code in src/arcpie/toolbox.py

def safe_load(tools: dict[str, list[str]],
              *,
              scope: dict[str, Any]|None=None,
              reload_module: bool=False) -> list[type[ToolABC]]:
    """Safely load in tools to a toolbox placing all failed imports in a `Broken Tools` category

    Args:
        tools (dict[str, list[str]]): A mapping of tool modules to tool files or tool classes in a module
        scope (dict[str, Any]): The `globals()` dict for the Toolbox scope (required so loading happend in Toolbox scope)
        reload_module (bool): Reload the module after importing (default: False)

    Returns:
        ( list[type[ToolABC]] ): A list of tool classes

    Note:
        To isolate bugs in a large toolbox, it is reccomended that you use file/module level importing
        with matching toolclass names (e.g. `Tool.py -> class Tool`) where the Tool mapping is:
            `Tools = {'tools': ['Tool.py']}`
        instead of:
            `Tools = {'tools.Tool': ['Tool']}`
        This allows the import to fail softly on a single tool instead of breaking imports for all other
        toolclasses in that `Tool.py` module.

        Any tools with errors will be placed in a `Broken Tools` category in the toolbox with the full
        stack trace placed in its description field. The final component of the exception will be placed
        at the end of the tool label for easy debugging.

    Example:
        ```python
        >>> # File import
        >>> Tools = {
        ...     # import matching class from named file in a submodule (tools)
        ...     # where ToolFileA is ToolFileA.py with a class ToolFileA
        ...     'tools': ['ToolFileA', 'ToolFileB'],
        ...     
        ...     # Import explicit ToolClass from toolfile (MyTools.py)
        ...     # NOT RECOMMENDED
        ...     'tools.MyTools': ['ToolClassA', 'ToolClassB'],
        ... }
        >>> tools = safe_import(globals(), Tools)
        ```
    """
    _tools = [
        _get_tool(module, tool_name, reload_module)
        for module in tools
        for tool_name in tools[module]
    ]
    if scope:
        scope.update({tool.__name__: tool for tool in _tools})
    return _tools

toolify ¶

toolify(
    *tool_registries: list[type[ToolABC]],
    name: str | None = None,
    params: ParameterTypeMap | None = None,
    debug: bool = False,
    logger: Logger | None = None,
)

Convert a typed function into a tool for the specified Toolbox class

PARAMETER	DESCRIPTION
`*tool_registries` ¶	The tool registry lists to add this tool to TYPE: `list[type[ToolABC]]` DEFAULT: `()`
`name` ¶	The name of the tool TYPE: `str` DEFAULT: `None`
`params` ¶	A mapping of parameter names to Parameter types and a callable constructor that converts the parameter to the expected value for the function parameter. You can also pass a fully formed arcpy.Parameter object as the first item in the tuple instead of a simple type TYPE: `ParameterTypeMap` DEFAULT: `None`
`debug` ¶	Print the converted arguments to the ArcGIS Pro message console (default: False) TYPE: `bool` DEFAULT: `False`
`logger` ¶	An optional logger to use for logging all runs of the toolified tool TYPE: `Logger \| None` DEFAULT: `None`

Usage

>>> @toolify(
>>>     TOOL_REGISTRY, 
>>>     name='PDF Exporter', 
>>>     params={
>>>         'project': ('DEFile', lambda p: Project(p.valueAsText)),
>>>         'outfile': ('DEFile', lambda p: Path(p.valueAsText))
>>>     }
>>> )
>>> def export_pdf(project: Project|str='CURRENT', outfile: Path|str='out.pdf') -> None:
>>>     ...

Source code in src/arcpie/toolbox.py

def toolify(*tool_registries: list[type[ToolABC]], 
            name: str|None=None, 
            params: ParameterTypeMap|None=None, 
            debug: bool=False, 
            logger: Logger|None=None,
):
    """Convert a typed function into a tool for the specified Toolbox class

    Args:
        *tool_registries (list[type[ToolABC]]): The tool registry lists to add this tool to
        name (str): The name of the tool
        params (ParameterTypeMap): A mapping of parameter names to Parameter types and a callable constructor 
            that converts the parameter to the expected value for the function parameter. You can also pass
            a fully formed arcpy.Parameter object as the first item in the tuple instead of a simple type
        debug (bool): Print the converted arguments to the ArcGIS Pro message console (default: False)
        logger (Logger|None): An optional logger to use for logging all runs of the toolified tool

    Usage:
        ```python
        >>> @toolify(
        >>>     TOOL_REGISTRY, 
        >>>     name='PDF Exporter', 
        >>>     params={
        >>>         'project': ('DEFile', lambda p: Project(p.valueAsText)),
        >>>         'outfile': ('DEFile', lambda p: Path(p.valueAsText))
        >>>     }
        >>> )
        >>> def export_pdf(project: Project|str='CURRENT', outfile: Path|str='out.pdf') -> None:
        >>>     ...
        ```
    """
    def _builder(func: Callable[..., Any]):

        @wraps(func)
        def _execute(*args: Any, **kwargs: Any):
            return func(*args, **kwargs)

        # Build the tool class
        _label = func.__name__.replace('_', ' ').title()
        _description = func.__doc__ or 'No Description Provided'
        _class_name = _label.replace(' ', '')
        sig = inspect.signature(func)
        sig_params = sig.parameters

        # Handle parameter converison
        def _passthrough_execution(self: ToolABC, parameters: Parameters | list[Parameter], messages: Any) -> None:
            if debug:
                print(f'Executing toolified {func.__name__} via {self.label}')
            args, kwargs = _read_params(parameters, sig_params, params or {})
            start = time.time()
            try:
                if debug:
                    print(f"Using *{args}, **{kwargs}")
                res = _execute(*args, **kwargs)
                end = time.time()
                if logger:
                    logger.info(f'[{datetime.isoformat(datetime.now())}] PASS "{self.label}" ({end-start:0.2f} seconds) [{res}]')
            except Exception as e:
                print(f'Something went wrong!:\n\t{traceback.format_exc()}', severity='ERROR')
                end = time.time()
                if logger:
                    logger.info(f'[{datetime.isoformat(datetime.now())}] FAIL "{self.label}" ({end-start:0.2f} seconds) [{e}] ')

        def _local_build_params(self: ToolABC) -> Parameters | list[Parameter]:
            return _build_params(sig_params, params or {})

        def _local_init(self: ToolABC) -> None:
            self.label = name or _label
            self.description = _description

        _tool_class = type(
            _class_name, 
            (ToolABC, ),
            {
                '__init__': _local_init, 
                'getParameterInfo':_local_build_params, 
                'execute': _passthrough_execution
            }
        )

        for registry in tool_registries:
            if _tool_class.__name__ not in map(lambda c: c.__name__, registry):
                registry.append(_tool_class)
                globals()[_class_name] = _tool_class
        return _execute
    return _builder

Toolbox¶

Done ¶

Double ¶

FeatureDataset ¶

FeatureLayer ¶

FeatureLayerList ¶

FilePath ¶

Folder ¶

HiddenString ¶

Integer ¶

MultiFilePath ¶

Parameters ¶

String ¶

StringList ¶

TextBox ¶

Toggle ¶

Tool ¶

project `property` ¶

ValueTable ¶

safe_load ¶

`tools` ¶

`scope` ¶

`reload_module` ¶

toolify ¶

`*tool_registries` ¶

`name` ¶

`params` ¶

`debug` ¶

`logger` ¶

Toolbox¶

Done ¶

Double ¶

FeatureDataset ¶

FeatureLayer ¶

FeatureLayerList ¶

FilePath ¶

Folder ¶

HiddenString ¶

Integer ¶

MultiFilePath ¶

Parameters ¶

String ¶

StringList ¶

TextBox ¶

Toggle ¶

Tool ¶

project property ¶

ValueTable ¶

safe_load ¶

tools ¶

scope ¶

reload_module ¶

toolify ¶

*tool_registries ¶

name ¶

params ¶

debug ¶

logger ¶

project `property` ¶

`tools` ¶

`scope` ¶

`reload_module` ¶

`*tool_registries` ¶

`name` ¶

`params` ¶

`debug` ¶

`logger` ¶