Настройка поведения инструмента в наборе инструментов Python

Проверка – все,что происходит до нажатия кнопки OK. При создании собственных инструментов проверка позволяет провести настройку реакции параметров, а также их взаимодействия со своими значениями и друг с другом. Проверка производится при помощи блока кода Python, контролирующего поведение инструмента.

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

У каждого параметра инструмента набора Python есть связанный с ним объект Parameter, у которого есть свойства и методы для проверки корректности параметров инструмента. В наборе инструментов Python параметры задаются в методе getParameterInfo класса инструмента. Поведение этих параметров и способ их взаимодействия друг с другом и входными данными проверяется в соответствии с методом updateParameters класса инструментов.

Доступ к параметрам инструмента

Объекты Parameter служат основой для определения параметров инструментов и их взаимодействия в наборе инструментов Python. Обычной практикой является создание списка параметров в классе метода getParameterInfo, как показано в приведенном ниже программном коде.

def getParameterInfo(self):
    #Define parameter definitions

    # First parameter
    param0 = arcpy.Parameter(
        displayName="Input Features",
        name="in_features",
        datatype="GPFeatureLayer",
        parameterType="Required",
        direction="Input")

    return [param0]

Дополнительная информация о задании параметров в наборе инструментов Python приведена в разделе Определение параметров в наборе инструментов Python.

Объект Parameter

Методы

Имя методаОписание использования

setErrorMessage(message)

Отмечает параметр, как имеющий ошибку (Ошибка), с добавленным сообщением. Инструменты не выполняются, если один из параметров имеет ошибку.

setWarningMessage(message)

Отмечает параметр, как имеющий предупреждение (Предупреждение), с добавленным сообщением. В отличие от ошибок, инструменты с предупреждениями выполняются.

setIDMessage(messageType, messageID, {AddArgument1}, {AddArgument2})

Позволяет вам задать системное сообщение. Аргументы те же, что и у функции AddIDMessage.

clearMessage()

Очищает любой текст сообщения и устанавливает статус на информативность (не ошибка и не предупреждение).

hasError()

Возвращает значение true, если параметр содержит ошибку.

hasWarning()

Возвращает значение true, если параметр содержит предупреждение.

isInputValueDerived()

Возвращает значение true, если инструмент был проверен внутри модели, и его входное значение является выходным значением другого инструмента данной модели.

Методы объекта Parameter

Свойства

Имя свойстваЧтение/записьЗначениеОписание

name

Только для чтения

String

Имя параметра

direction

Только для чтения

String: "Input", "Output"

Входное/выходное направление параметра.

datatype

Только для чтения

String

Список типов данных параметров приведен в разделе Определение типов данных параметров в наборах инструментов Python.

parameterType

Только для чтения

String: "Required" (Обязательный), "Optional" (Дополнительный), "Derived" (Производный)

Тип параметра.

parameterDependencies

Чтение/запись

Список Python

Список индексов каждого зависимого параметра.

value

Чтение/запись

Объект Value

Значение параметра.

defaultEnvironmentName

Только для чтения

String

Значение параметра среды по умолчанию.

enabled

Чтение/запись

Boolean

False, если параметр недоступен.

altered

Только для чтения

Boolean

True, если пользователь изменил значение.

hasBeenValidated

Только для чтения

Boolean

True, если параметр был проверен внутренней процедурой проверки.

category

Чтение/запись

String

Категория параметра.

schema

Только для чтения

Объект Schema

Схема выходного набора данных.

filter

Только для чтения

Объект Filter

Фильтр, применяемый к значениям параметра.

symbology

Чтение/запись

String

Путь к файлу слоя (.lyrx), используемому для отображения выходных данных.

message

Только для чтения

String

Сообщение, показываемое пользователю. См. методы setErrorMessage и setWarningMessage выше.

Свойства объекта Parameter

Хотя многие свойства объекта Parameter доступны для чтения и записи, большинство из них можно задать или изменить только при первоначальном создании или изменении объекта. Некоторые свойства, включая name, displayName, datatype, direction и parameterType, устанавливают характеристики инструмента и не могут быть изменены во время проверки (например, updateMessages и updateParameters).

parameterDependencies

Как правило, вы устанавливаете набор зависимостей параметра для использования объектом Schema. Существуют два случая, когда зависимость уже может быть установлена в методе инструмента getParameterInfo.

  • Для параметра выходного набора данных, производного типа, зависимостью является индекс параметра, из которого извлекаются выходные данные.
  • Для определенных типов входных данных, зависимостью является индекс параметра, содержащий информацию, используемую элементом управления, как показано в таблице ниже.

Тип данных параметраТип данных зависимого параметра

Единицы площади (GPArealUnit)

Географический набор данных, используемый для определения единиц измерения по умолчанию.

Например, можно использовать тип данных Векторный слой (GPFeatureLayer), Растровый слой (GPRasterLayer), Набор объектов (GPFeatureRecordSetLayer) или Набор записей (GPRecordSet).

Поле (Field)

Таблица, содержащая поля.

Например, можно использовать тип данных Вид таблицы (GPTableView), Векторный слой (GPFeatureLayer), Растровый слой (GPRasterLayer), Набор объектов (GPFeatureRecordSetLayer) или Набор записей (GPRecordSet).

Сопоставления полей (GPFieldMapping)

Набор полей в одной или более входных таблицах.

Например, можно использовать тип данных Вид таблицы (GPTableView), Векторный слой (GPFeatureLayer), Растровый слой (GPRasterLayer), Набор объектов (GPFeatureRecordSetLayer) или Набор записей (GPRecordSet).

Таблица геостатистических значений ( GPGAValueTable)

Таблица наборов данных и полей, используемых в инструментах Geostatistical Analyst.

Используйте тип данных Геостатистический слой (GPGALayer).

Линейные единицы измерения (GPLinearUnit)

Географический набор данных, используемый для определения единиц измерения по умолчанию.

Например, можно использовать тип данных Векторный слой (GPFeatureLayer), Растровый слой (GPRasterLayer), Набор объектов (GPFeatureRecordSetLayer) или Набор записей (GPRecordSet).

Настройки иерархии Network Analyst (GPNAHierarchySettings)

Набор сетевых данных, содержащий информацию об иерархии.

Используйте тип данных Набор сетевых данных (DENetworkDataset).

Режим передвижения по сети (NetworkTravelMode)

Список режимов передвижения.

Используйте тип данных Источник сетевых данных (GPNetworkDataSource), Набор сетевых данных (DENetworkDataset) или Слой набора сетевых данных (GPNetworkDatasetLayer).

Выражение SQL (GPSQLExpression)

Таблица, содержащая поля.

Например, можно использовать тип данных Вид таблицы (GPTableView), Векторный слой (GPFeatureLayer), Растровый слой (GPRasterLayer), Набор объектов (GPFeatureRecordSetLayer) или Набор записей (GPRecordSet).

Типы данных parameterDependencies

Зависимости обычно устанавливаются в методе getParameterInfo:

def getParameterInfo(self):
    #Define parameter definitions

    # First parameter
    param0 = arcpy.Parameter(
        displayName="Input Features",
        name="in_features",
        datatype="GPFeatureLayer",
        parameterType="Required",
        direction="Input")

    # Second parameter
    param1 = arcpy.Parameter(
        displayName="Sinuosity Field",
        name="sinuosity_field",
        datatype="Field",
        parameterType="Optional",
        direction="Input")
    param1.value = "sinuosity"

    # Third parameter
    param2 = arcpy.Parameter(
        displayName="Output Features",
        name="out_features",
        datatype="GPFeatureLayer",
        parameterType="Derived",
        direction="Output")
    param2.parameterDependencies = [param0.name]
    param2.schema.clone = True

    params = [param0, param1, param2]

    return params

value

Это значение параметра, которое ввел пользователь, или которое было задано вами программно. Вы можете задать значение методом getParameterInfo, и в этом случае оно выступит в качестве начального значения по умолчанию, установленное для данного параметра. Вы также можете установить значение в updateParameters в ответ на ввод значения пользователем, как показано ниже.

def updateParameters(self, parameters):
    # Set the default distance threshold to 1/100 of the larger of the width
    #  or height of the extent of the input features.  Do not set if there is no 
    #  input dataset yet, or the user has set a specific distance (Altered is true).
    #
    if parameters[0].valueAsText:
        if not parameters[6].altered:
            extent = arcpy.Describe(parameters[0]).extent
        if extent.width > extent.height:
            parameters[6].value = extent.width / 100
        else:
            parameters[6].value = extent.height / 100

    return

Свойство value параметра возвращает объект, кроме случая, когда параметр не заполнен, в этом случае value возвращает значение None. Чтобы убедиться, что параметр заполнен, используйте проверку if перед использованием его значения.

Фрагмент кода ниже тестирует, является ли значение идентичным строке "Get Spatial Weights From File". Данный тест работает, поскольку тип данных параметра является строковым.

# If the option to use a weights file is selected, enable the 
#   parameter for specifying the file, otherwise disable it

if parameters[3].value:  # check that parameter has a value
    if parameters[3].value == "Get Spatial Weights From File":
        parameters[8].enabled = True
    else:
        parameters[8].enabled = False

Поскольку объект Value не поддерживает манипуляции со строками, используйте свойство значения объекта Value всякий раз, когда требуется обработать или проанализировать строку. Пример кода ниже использует метод os.path.dirname, чтобы вернуть директорию для набора данных.

if parameters[0].value:
    workspace = os.path.dirname(parameters[0].value.value)
Примечание:

За исключением метода Describe, не используйте для проверки методы, берущие путь к каталогу, такие как ListFields. Набор данных может не существовать, когда проверка инструмента осуществляется в ModelBuilder, и метод может дать сбой или выдать непредсказуемый результат.

В конкретном случае метода ListFields, Describe свойство объекта fields предоставит эквивалентную информацию.

Примечание:

Не устанавливайте значение параметра updateMessages(), пока это значение не будет проверено внутренней подпрограммой проверки.

altered

altered равно true, если изменено значение параметра, например, путем ввода выходного пути. Если параметр был изменен, то он остается измененным, пока пользователь не очистит (не удалит) значение, в этом случае оно вернется к изначальному неизмененному состоянию. Изменение значения программным способом с проверкой кода будет влиять на измененный статус. То есть, если вы установите значение для параметра, измененный статус параметра будет обновляться.

altered используется, чтобы определить, можете ли вы изменить значение параметра. Например, предположим, что у инструмента есть параметр класс объектов и параметр ключевое слово. Если класс объектов содержит точки или полигоны, то ключевыми словами будут Красный (RED), Зеленый (GREEN), и Синий (BLUE), а если линии – то Оранжевый (ORANGE), Желтый (YELLOW), Фиолетовый (PURPLE), и Белый (WHITE).

Предположим, пользователь вводит точечный класс объектов. Если параметр ключевое слово не изменен, вы устанавливаете значение на RED, поскольку оно является значением по умолчанию.

Если вводится линейный класс объектов, вы устанавливаете значение на ORANGE, поскольку параметр ключевое слово не изменен.

Однако, если параметр ключевое слово был изменен пользователем (например, ключевое слово установлено на GREEN), не меняйте обратно ключевое слово. Пользователь сделал свой выбор (GREEN), и вы не знаете его намерений. Он мог поменять класс объектов, и тогда GREEN будет корректным значением, или он мог поменять ключевое слово (на PURPLE, например). Поскольку GREEN не входит в набор ключевых слов, которые вы создали для линий, внутренняя проверка установит на параметре отметку ошибки. У пользователя будет два варианта действий: изменить входной класс объектов или изменить ключевое слово.

if not parameters[2].altered:
    parameters[2].value = "POINT"

hasBeenValidated

hasBeenValidated равно False, если значение параметра было изменено пользователем с того момента, когда updateParameters и внутренняя проверка вызывались в последний раз. После вызова внутренней процедуры проверки, процедура геообработки автоматически устанавливает hasBeenValidated равным True для каждого параметра.

hasBeenValidated используется для определения, изменял ли пользователь значение с момента последнего запуска updateParameters. Эта информация необходима при решении вопроса о необходимости проверки параметра.

def updateParameters(self, parameters):
    # Set the default distance threshold to 1/100 of the larger of the width
    #  or height of the extent of the input features.  Do not set if there is no 
    #  input dataset yet, or the user has set a specific distance.
    #
    if parameters[0].valueAsText:
        if parameters[6].hasBeenValidated:
            extent = arcpy.Describe(parameters[0]).extent
            if extent.width > extent.height:
                parameters[6].value = extent.width / 100
            else:
                parameters[6].value = extent.height / 100

    return

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