Создание модулей геообработки

Пользовательские наборы инструментов (.atbx и .tbx) и наборы инструментов Python (.pyt) могут распространяться в виде пакетов Python. Процесс создания и распространения набора инструментов подразумевает создание пакета Python и добавление в структуру пакета папки esri, в которой будут содержаться ваши собственные наборы инструментов. Как только такой пакет будет установлен в среде Python, ваш набор инструментов будет отображаться и будет доступен всеми способами, как если бы он входил в состав системного набора инструментов в ArcGIS Pro, доступного на панели Геообработка и из arcpy. Кроме того, пользовательские модули геообработки могут использовать хорошо зарекомендовавшую себя методологию, которую используют системные наборы инструментов ArcGIS Pro в отношении распространения сообщений, языковой справки и адаптации к региональным настройкам.

Создание пакета Python

Для наглядности мы создадим пакет Python с именем foo, содержащий модуль bar.py.

bar.py

Пример кода для модуля Python.

import os 
 
def hello(): 
    return f'Hello {os.getenv("username")}'

Чтобы модуль был создан и размещен, должна иметь место особая структура директорий. Для хранения модуля bar должна быть создана директория foo. Поскольку для распространения требуется, чтобы каталог, в котором хранится модуль bar, находился в корневой директории, создается директория с именем src для хранения каталога foo и модуля bar. Структура папок должна быть следующей:

src
└───foo
     └  bar.py

Чтобы модуль bar инициализировал и выполнил определенный код, когда он будет импортирован, необходим файл __init__.py. При использовании файла __init__.py каталог foo будет обрабатываться как пакет Python.

__init__.py

Пример кода для __init__.py в foo.

from foo import bar

Структура папок теперь должна быть следующей:

src
└───foo
     ├  __init__.py 
     └  bar.py

Примечание:

На протяжении всего этого процесса в каталогах могут появляться дополнительные папки __pycache__. Эти папки содержат файлы кэша скомпилированных версий модулей, генерируемых Python для ускорения загрузки модулей. Для упрощения схем структуры папок они здесь не показаны.

Работая со структурой файлов и каталогов, модуль bar можно импортировать посредством import foo и реализовать функцию foo.bar.hello().

Примечание:

Чтобы импортировать модуль в Python, этот модуль должен находиться в текущем каталоге, каталоге списка sys.path или в каталоге, указанном с помощью переменной среды PYTHONPATH.

Расширение пакета Python инструментами геообработки

Чтобы добавить в пакет Python пользовательские наборы инструментов или наборы инструментов Python, эти наборы инструментов и сопутствующие файлы объединяются в модуль в папке esri. Стандартная структура каталогов для пакета Python, расширенного пользовательскими функциями геообработки, выглядит следующим образом:

Src
└──foo
    ├  __init__.py 
    ├  bar.py
    └──esri
        ├──arcpy
        ├──help
        │   └──gp
        │       ├──messages
        │       └──toolboxes
        └──toolboxes

Пользовательские наборы инструментов помещаются в каталог esri\toolboxes вместе с любыми вспомогательными файлами .py. Файлы метаданных инструментов и их наборов (.xml) хранятся в папке esri\help\gp.

• Правила наименования файла метаданных наборов инструментов: псевдоним набора инструментов сопровождается суффиксом _toolbox.
• Правила наименования файла метаданных инструмента: название инструмента сопровождается псевдонимом набора инструментом с разделителем-подчеркиванием.

Любые файлы сообщений геообработки .xml хранятся в каталоге esri\help\gp\messages. Эти файлы сообщений используются в наборах инструментов Python для сообщений, которые необходимо интернационализировать.

Процесс расширения геообработки пакетами Python может быть проиллюстрирован с помощью набора инструментов Python с именем SamplePythonToolbox.

Более подробно о создании набора инструментов Python

SamplePythonToolbox.pyt

Пример кода для создания набора инструментов Python.

# -*- coding: utf-8 -*-

import arcpy
import os
import foo

class Toolbox(object):
    def __init__(self):
        """Define the toolbox (the name of the toolbox is the name of the
        .pyt file)."""
        self.label = "Sample Python Toolbox"
        self.alias = "SamplePythonToolbox"

        # List of tool classes associated with this toolbox
        self.tools = [SampleTool]

class SampleTool(object):
    def __init__(self):
        """Define the tool (tool name is the name of the class)."""
        self.label = "Sample Tool"
        self.description = ""
        self.canRunInBackground = False

    def getParameterInfo(self):
        """Define parameter definitions"""
        parameters=[arcpy.Parameter(displayName='Msg', 
                                  name='msg',
                                  datatype='GPString',
                                  parameterType='Derived',
                                  direction='Output')
                                  ]
        return parameters

    def isLicensed(self):
        """Set whether tool is licensed to execute."""
        return True

    def updateParameters(self, parameters):
        """Modify the values and properties of parameters before internal
        validation is performed.  This method is called whenever a parameter
        has been changed."""
        return

    def updateMessages(self, parameters):
        """Modify the messages created by internal validation for each tool
        parameter.  This method is called after internal validation."""
        return

    def execute(self, parameters, messages):
        """The source code of the tool."""
        result = foo.bar.hello()
        messages.AddMessage(f"{result}, welcome to the sample tool")
        parameters[0].value = result
        return

Примечание:

Чтобы проверить набор инструментов на этом этапе, временно поместите его в корневую папку src. Поскольку foo импортируется в набор инструментов, этот инструмент, скорее всего, не будет работать должным образом, если он не находится в том же каталоге, что и пакет foo.

В набор инструментов SamplePythonToolbox.pyt импортируется пакет foo, и метод execute класса SampleTool вызывает функцию hello() из модуля bar.

Такой подход является эффективным способом распространения пользовательского кода Python в виде пакета и раскрытия его функциональных возможностей с помощью инструментов геообработки ArcGIS Pro. Когда будет создан набор инструментов SamplePythonToolbox.pyt, в метаданных этого набора инструментов можно указать справку по его параметрам. Для редактирования метаданных на панели Каталог щелкните правой кнопкой на одном из инструментов в наборе и выберите Редактировать метаданные.

После обновления метаданных для инструмента и набора инструментов можно запустить функцию arcpy.gp.createtoolboxsupportfiles для создания вспомогательных файлов .xml, находящихся в описанной выше структуре папок esri. Эта команда также создает оболочку arcpy SamplePythonToolbox.py, названную так по имени инструмента, которая обеспечивает доступность этого набора инструментов из arcpy. Если файла там нет, поместите SamplePythonToolbox.pyt в корневую папку src, а затем запустите python -c "import arcpy; arcpy.gp.createtoolboxsupportfiles(r'<path to toolbox>')" из командной строки Python.

Примечание:

Перед запуском команды arcpy.gp.createtoolboxsupportfiles убедитесь, что для набора указан псевдоним. Псевдоним нужен для создания файлов справки.

В итоговой папке esri создайте каталог toolboxes и перенесите в нее SamplePythonToolbox.pyt. Файлы метаданных (.pyt.xml) можно не переносить. Теперь папка esri должна выглядеть следующим образом:

esri
 ├──arcpy
 │   └  SamplePythonToolbox.py
 ├──help
 │   └──gp
 │       ├  SamplePythonToolbox_toolbox.xml
 │       ├  SampleTool_SamplePythonToolbox.xml
 │       ├──messages 
 │       └──toolboxes
 │           └  SamplePythonToolbox.xml
 └──toolboxes
     └  SamplePythonToolbox.pyt

Примечание:

Папка messages не создается посредством arcpy.gp.createtoolboxsupportfiles; она должна быть создана вручную, чтобы сделать сообщения об ошибках, которые используются в инструментах-скриптах или наборах инструментов Python, доступными для локализации; но ее (создание) можно пропустить, если интернационализация не планируется.

Переместите папку esri в каталог src\foo. Структура директорий должна быть следующей:

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

Для распространения на английском языке никаких дополнительных шагов не требуется. Дополнительные сведения о расширении геообработки для распространения на языках, отличных от английского, см. в разделе Интернационализация модулей геообработки. О распространении модуля см. раздел Распространение модуля геообработки.