Расширение геообработки с помощью модулей Python

Примечание:

Этот рабочий процесс требует установки conda, pip, setuptools и wheel в вашей среде Python. Эти пакеты поставляются в среде ArcGIS Pro Python по умолчанию.

Наборы инструментов Python и пользовательские наборы инструментов можно размещать среди других пользователей ArcGIS Pro в виде пакетов Python с помощью библиотеки setuptools. Процесс создания и распространения наборов инструментов начинается с создания модуля Python. Для примера использования мы будем использовать bar.py.

bar.py

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

import os 
 
def hello(): 
    return 'Hello ' + os.getenv('username')

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

src
└───foo     └  bar.py

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

__init__.py

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

from foo import bar

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

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

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

Следующим шагом будет построение пакета распространения (дистрибутива) для пакета foo с тем, чтобы его можно было установить в каталог Python site-packages. Таким образом, пакет может быть совместно использован другими пользователями. Дистрибутив может быть создан путем написания скрипта setup.py.

setup.py

Пример кода для создания скрипта setup.py.

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'],       )

Скрипт сборки setup.py задает несколько свойств и направляет служебную программу сборки в каталог пакета. Длинное описание хранится в сопроводительном файле Readme.txt. Файлы setup.py и Readme.txt должны быть сохранены в папку src. Дополнительные сведения об использовании setup() см. В разделе Упаковка и распространения пакетов. Структура папок должна быть следующей:

Src
├  setup.py
├  Readme.txt
└──foo    ├  __init__.py     └  bar.py
Примечание:

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

С такой структурой директорий должен быть создан установщик для пакета foo – путем запуска указанной ниже команды из папки src, используя строку операционной системы.

python setup.py sdist bdist_wheel

Команда sdist bdist_wheel создает dist, build, а foo.egg-info папки в корневой директории src. В папке dist создается wheel-файл с именем foo-1.0-py3-none-any.whl. Wheel-файл может быть размещен непосредственно с помощью pip.

Установка дистрибутивоа wheel с помощью pip

Примечание:

Изменение среды Python по умолчанию для ArcGIS Pro (arcgispro-py3) может привести к непредвиденным последствиям. Рекомендуется изменять только клонированную среду.

Клонируйте среду ArcGIS Pro по умолчанию и переключитесь на клонированную среду с помощью Менеджера пакетов Python.

После клонирования и переключения сред откройте ArcGIS ProКомандную строку Python, чтобы установить wheel-файл непосредственно с помощью pip. Pip установит wheel-файл в активную среду. В командной строке с указанием вашей директории src\dist выполните следующие действия:

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

Кроме того, каталог foo также может быть скопирован непосредственно из директории build\lib в папку %LocalAppData%\ESRI\conda\envs\<environment_name>\Lib\site-packages. Если существуют ограничения на запуск установок, то копирование каталога foo из каталога build\lib в каталог site-packages приведет к тому же эффекту, что и установка его посредством запуска pip, за исключением того, что пакет не будет распознан или управляться pip.

Когда модуль foo установлен или скопирован в каталог site-packages, структура должна быть следующей:

site-packages
└──foo    ├  __init__.py     └  bar.py

Распространение наборов инструментов ArcGIS Pro в виде пакетов Python

Этот процесс может быть дополнительно развернут для расширения функциональности геообработки, чтобы ваши собственные наборы инструментов появлялись рядом с системными наборами инструментов ArcGIS Pro. Ваши наборы инструментов будут отображаться и станут доступными всеми способами, которые есть внутри ArcGIS Pro, будут доступны через окно Геообработки и из arcpy. Кроме того, это позволяет пользовательскому модулю набора инструментов использовать хорошо зарекомендовавшую себя методологию, используемую системными наборами инструментов ArcGIS Pro для распространения сообщений, языковой справки и реагирования на локализованные параметры. Ниже приведена стандартная структура каталогов:

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

Пользовательские наборы инструментов (.tbx и .pyt) находятся в папке esri\toolboxes вместе с любыми вспомогательными файлами .py. В директории esri\help\gp хранятся метаданные (.xml) для пользовательских инструментов и наборов инструментов. Правила наименования наборов инструментов – <псевдоним набора инструментов>_toolbox.xml, а для каждого инструмента – <имя инструмента>_<псевдоним набора инструментов>.xml. В каталоге esri\help\gp\messages хранятся файлы сообщений геообработки (.xml). Эти файлы сообщений используются в наборах инструментов Python для интернационализированных сообщений. Замещающие файлы надписей инструментов и наборов инструментов, которые находятся в директории esri\help\gp\toolboxes.

Весь процесс расширения геообработки с помощью пакетов Python можно продемонстрировать, создав набор инструментов Python с именем SamplePythonToolbox.

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(result + ", welcome to the sample tool")        parameters[0].value = result        return

Более подробно о создании набора Python

В набор инструментов SamplePythonToolbox.pyt был импортирован пакет foo, и метод запуска execute класса SampleToolвызвал функцию hello() из модуля bar. Это эффективный путь использования пользовательского кода Python как пакета и применения его функциональных возможностей в инструментах геообработки ArcGIS Pro. После того, как был создан SamplePythonToolbox.pyt, справка боковой панели может быть настроена для панели инструментов через метаданные, отредактированные в меню Редактировать метаданные панели Каталога.

После создания метаданных для набора инструментов функция arcpy.gp.createtoolboxsupportfiles может быть запущена для создания вспомогательных файлов .xml, найденных в структуре папок esri, описанной выше. Команда может быть использована для любого набора инструментов. Поместите SamplePythonToolbox.pyt в отдельную папку, затем запустите arcpy.gp.createtoolboxsupportfiles(<path to .tbx or .pyt>).

Примечание:

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

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

Staging
 └──esri
     ├──arcpy
     │   └  SamplePythonToolbox.py
     ├──help
     │   └──gp
     │       ├  SamplePythonToolbox_toolbox.xml
     │       ├  SampleTool_SamplePythonToolbox.xml
     │       ├──messages 
     │       └──toolboxes
     │           └  SamplePythonToolbox.xml
     └──toolboxes
         ├  SamplePythonToolbox.pyt
         ├  SamplePythonToolbox.pyt.xml
         └  SamplePythonToolbox.SampleTool.pyt.xml
Примечание:

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

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

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

Чтобы отразить эти изменения в нашем распределении, нужно отредактировать файл setup.py.

Измененный setup.py

Пример кода для включения изменений директории setup.py:

import os from setuptools import setup 
 def read(fname): 
    return open(os.path.join(os.path.dirname(__file__), fname)).read()  
setup(name='foo',       version='2.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/*'] 
                  },       )

Новый setup.py отличается от исходного одной строкой, в которой содержатся дополнительные данные, найденные в папке esri. Эта версия также была обновлена до 2.0. Чтобы обновить дистрибутив, удалите папки build, dist и foo.edd-info из каталога src и выполните повторный запуск python setup.py sdist bdist_wheel. Для установки выполните следующие действия из командной строки с указанием вашей директории src\dist:

pip install --upgrade foo-2.0-py3-none-any.whl

Теперь, когда построитель (builder) для пакета foo запущен и модуль устанавливается, в каталоге Python site-packages будет создана следующая структура каталогов:

site-packages
└──foo    ├  __init__.py     ├  bar.py    └──esri        ├──arcpy        │   └  SamplePythonToolbox.py        ├──help        │   └──gp        │       ├  SamplePythonToolbox_toolbox.xml        │       ├  SampleTool_SamplePythonToolbox.xml        │       ├──messages        │       └──toolboxes        │           └  SamplePythonToolbox.xml        └──toolboxes            ├  SamplePythonToolbox.pyt            ├  SamplePythonToolbox.pyt.xml            └  SamplePythonToolbox.SampleTool.pyt.xml
Примечание:

Папка messages присутствует только в том случае, если она содержит файлы.

В ArcGIS Pro SamplePythonToolbox теперь можно искать на панели Геообработка, он находится на вкладке Наборы инструментов. Доступ к набору инструментов и инструменту можно получить из arcpy следующим образом: arcpy.SamplePythonToolbox.SampleTool()

Используя ArcGIS Pro и процесс разработки пакета Python, предоставляемый библиотекой setuptools, вы можете создавать и устанавливать пакет, который расширит геообработку пользовательскими наборами инструментов, просматриваемыми и запускаемыми из системных наборов ArcGIS и arcpy. Для английского языка больше ничего не требуется. Дополнительные сведения о расширении геообработки для распространения на языках, отличных от английского, см. в разделе Интернационализация модулей Python.

Связанные разделы