Personalizar el comportamiento de la herramienta en una caja de herramientas Python
La validación es todo lo que ocurre antes de pulsar el botón Aceptar de una herramienta. Cuando cree sus propias herramientas personalizadas, la validación le permitirá personalizar el modo en que los parámetros responden e interaccionan con los valores y entre ellos. La validación se efectúa con un bloque de código de Python que se usa para controlar el comportamiento de la herramienta.
Para obtener más información sobre la validación, consulte Comprender la validación en las herramientas de secuencia de comandos.
En una caja de herramientas de Python, cada parámetro de la herramienta tiene un objeto de parámetro asociado con propiedades y métodos que resultan útiles en la validación de la herramienta. En una caja de herramientas Python, los parámetros se definen en el método getParameterInfo de la clase de herramienta. El comportamiento de esos parámetros y cómo interactúan entre ellos y con las entradas son aspectos que se validan según el método updateParameters de la clase de herramienta.
Acceso a los parámetros de la herramienta
Los objetos de parámetro forman la base de cómo se definen e interactúan los parámetros en una caja de herramientas Python. La práctica estándar es crear la lista de parámetros en el método getParameterInfo de la clase de herramienta, según se muestra en el código a continuación.
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]
Para obtener más información sobre la definición de parámetros en una caja de herramientas de Python, consulte Definición de parámetros en una caja de herramientas Python.
Objeto de parámetro
Métodos
|
Nombre del método |
Descripción de uso |
|---|---|
|
setErrorMessage(message:string) |
Marca un error (una X roja) en el parámetro con el mensaje proporcionado. Las herramientas no se ejecutan si alguno de los parámetros tiene un error. |
|
setWarningMessage(message:string) |
Marca una advertencia (un triángulo amarillo) en el parámetro con el mensaje proporcionado. A diferencia de los errores, las herramientas se ejecutan cuando hay mensajes de advertencia. |
|
setIDMessage(messageType: string, messageID: string, {AddArgument1}, {AddArgument2}) |
Le permite configurar un mensaje del sistema. Los argumentos son los mismo que en la función AddIDMessage. |
|
clearMessage() |
Borra todo el texto del mensaje y configura el estado como informativo (sin errores ni advertencias). |
|
hasError() |
Devuelve verdadero si el parámetro contiene un error. |
|
hasWarning() |
Devuelve verdadero si el parámetro contiene una advertencia. |
|
isInputValueDerived() |
Devuelve verdadero si la herramienta se está validando dentro de un modelo y el valor de entrada es la salida de otra herramienta en el modelo. |
Propiedades
|
Nombre de propiedades |
Lectura/escritura |
Valores |
Descripción |
|---|---|---|---|
|
name |
Sólo lectura |
Cadena de caracteres |
El nombre del parámetro. |
|
dirección |
Sólo lectura |
Cadena de caracteres: "Input", "Output" |
Dirección de entrada/salida del parámetro. |
|
datatype |
Sólo lectura |
Cadena de caracteres |
Para obtener una lista de tipos de datos de parámetro, consulte Definir los tipos de datos de parámetro en una caja de herramientas de Python. |
|
parameterType |
Sólo lectura |
Cadena de caracteres: "Required", "Optional", "Derived" |
El tipo de parámetro. |
|
parameterDependencies |
Lectura/escritura |
Lista de Python |
Una lista de índices de cada parámetro dependiente. |
|
valor |
Lectura/escritura |
Objeto de valor |
El valor del parámetro. |
|
defaultEnvironmentName |
Sólo lectura |
Cadena de caracteres |
La configuración del entorno predeterminada. |
|
habilitado |
Lectura/escritura |
Booleano |
Falso si el parámetro no está disponible. |
|
altered |
Sólo lectura |
Booleano |
Verdadero si el usuario modificó el valor. |
|
hasBeenValidated |
Sólo lectura |
Booleano |
Verdadero si la rutina de validación interna verificó el parámetro. |
|
categoría |
Lectura/escritura |
Cadena de caracteres |
La categoría del parámetro. |
|
esquema |
Sólo lectura |
Objeto de esquema |
El esquema del dataset de salida. |
|
filtro |
Sólo lectura |
Objeto de filtro |
El filtro que se aplicará a los valores en el parámetro. |
|
simbología |
Lectura/escritura |
Cadena de caracteres |
La ruta al archivo de capa (.lyr) que se utiliza para dibujar la salida. |
|
mensaje |
Sólo lectura |
Cadena de caracteres |
El mensaje que se mostrará al usuario. Consulte SetErrorMessage y SetWarningMessage arriba. |
parameterDependencies
Por lo general, configura las dependencias del parámetro para que las utilice el objeto de esquema. Existen dos casos donde las dependencias ya puede estar configuradas en el método getParameterInfo de la herramienta.
- Para un parámetro de dataset de salida cuyo tipo es Derivado, la dependencia es el índice del parámetro desde el cual se deriva la salida.
- Para determinados tipos de datos de entrada, la dependencia es el índice del parámetro que contiene la información utilizada por el control, según se muestra en la tabla a continuación.
|
Tipo de datos de entrada |
Tipo de datos dependientes |
Descripción |
|---|---|---|
|
Campo o expresión de SQL |
Tabla |
La tabla que contiene los campos. |
|
Elemento de INFO o expresión de INFO |
Tabla INFO |
La tabla INFO que contiene los elementos. |
|
Clase de entidad de cobertura |
Cobertura |
La cobertura que contiene las entidades. |
|
Unidades de área o unidades lineales |
GeoDataset |
Un dataset geográfico utilizado para determinar las unidades por defecto. |
|
Sistema de coordenadas |
Espacio de trabajo |
Un espacio de trabajo utilizado para determinar el sistema de coordenadas predeterminado. |
|
Configuración de jerarquía de Network Analyst |
Dataset de red |
El dataset de red que contiene la información de jerarquía. |
|
Tabla de valores de estadísticas geográficas |
Capa de estadísticas geográficas |
La capa de análisis que contiene las tablas. |
Las dependencias por lo general se configuran en el método 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
valor
Este valor es del parámetro que el usuario introdujo o usted configuró de forma programada. Puede configurar el valor en el método getParameterInfo, en cuyo caso sirve como el valor predeterminado inicial para el parámetro. También puede configurar el valor en updateParameters en respuesta a una entrada de usuario como se muestra a continuación.
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].value:
if not parameters[6].altered:
extent = arcpy.Describe(parameters[0].value).extent
if extent.width > extent.height:
parameters[6].value = extent.width / 100
else:
parameters[6].value = extent.height / 100
return
Nota:La lista de parámetros comienza en 0; por lo tanto, el primer parámetro está en la posición cero de la lista. Para obtener acceso al tercer parámetro, utilizará parameters[2].
No configure un valor de parámetro en updateMessages dado que el valor no se validará mediante la rutina de validación interna.
Un valor es un objeto que tiene una representación de cadena de texto. El fragmento de código a continuación evalúa si el valor es igual a la cadena de texto "Get Spatial Weights From File". Esta prueba funciona porque el tipo de datos del parámetro es una cadena de texto.
# If the option to use a weights file is selected, enable the
# parameter for specifying the file, otherwise disable it
#
if parameters[3].value == "Get Spatial Weights From File":
parameters[8].enabled = True
else:
parameters[8].enabled = False
La prueba en el código anterior no funcionaría si el tipo de datos del parámetro es una clase de entidad o cualquier valor que represente un dataset. Los valores que representan los datos en el disco, como clases de entidad y rásteres, deben convertirse a cadenas de texto antes de hacer las operaciones de cadena de texto. La función Python incorporada str convierte los objetos de valor en cadenas de texto, de la manera siguiente:
if str(parameters[0].value) == "E:/data/example.gdb/roads":
Solo es necesario que use la función str para valores con tipos de datos que representan los datasets. Para estos tipos de valores, la función str devuelve una ruta del catálogo al dataset. No necesita utilizar esta función para otros tipos de datos, como unidad larga o lineal, dado que estos tipos de datos no representan datasets y se convierten automáticamente en cadenas de texto.
Precaución:Cuando utilice la función Describir en updateParameters, nunca use la representación de la cadena de caracteres del valor.
Incorrecto | |
Corregir | |
No debe utilizar la representación de cadenas de caracteres para los datasets (que genera la ruta del catálogo hacia el dataset) porque es posible que el dataset no exista; tal vez sea una variable del modelo y éste debe ejecutarse antes de que exista un dataset en el disco. Si utiliza la representación de cadena de texto para el dataset, la función Describe puede fallar ya que es posible que aún no exista el dataset en el disco.
Precaución:No utilice las funciones ArcPy que toman una ruta de catálogo, como ListFields, en los métodos de validación. Es posible que el dataset no exista cuando la herramienta se valida en ModelBuilder y el método puede fallar. (En el caso de ListFields, puede utilizar la propiedad Describir campos de objeto en su lugar).
Cuando prueba las cadenas de texto por equivalencia, debe utilizar comparaciones que no distingan entre mayúsculas y minúsculas. El código que se muestra a continuación muestra el uso de la función minúscula.de Python para colocar en minúscula el tipo de forma de una clase de entidad y comparar cadenas de texto en minúscula. (De manera alternativa, puede usar la función mayúscula para comparar cadenas de texto en mayúscula).
fc = parameters[0].value
shapetype = arcpy.Describe(fc).shapeType.lower()
if shapetype in ["point", "multipoint"]:
altered
altered es verdadero si el usuario cambió el valor de un parámetro, por ejemplo al introducir una ruta de salida. Una vez que el parámetro se ha alterado, permanece así hasta que el usuario vacía (borra) el valor, en cuyo caso vuelve a estar no alterado. Cambiar un valor de forma programada con un código de validación no cambia el estado alterado. Es decir, si configura un valor para un parámetro, el estado alterado del parámetro no cambia.
altered se utiliza para determinar si puede cambiar el valor de un parámetro. A modo de ejemplo, suponga que una herramienta tiene un parámetro de clase de entidad y un parámetro de palabra clave. Si la clase de entidad contiene puntos o polígonos, las palabras clave son ROJO, VERDE y AZUL, y si contiene líneas, NARANJA, AMARILLO, PÚRPURA y BLANCO.
Suponga que el usuario introduce una clase de entidad de punto. Si el parámetro de palabra clave no está alterado, configura el valor como ROJO, dado que es el valor por defecto.
Si se introduce una clase de entidad de línea, configura el valor predeterminado como NARANJA siempre que el parámetro de palabra clave esté no alterado.
No obstante, si el usuario ha alterado el parámetro de palabra clave (es decir, la palabra clave se configura como VERDE), no debe restablecer la palabra clave; el usuario ha realizado su elección (VERDE) y no conoce la intención; es posible que cambien la clase de entidad para que VERDE sea válido o pueden cambiar la palabra clave (por ejemplo, a PÚRPURA). Puesto que VERDE no es un miembro del conjunto que creó para las líneas, la validación interna indica un error del parámetro. El usuario tiene dos opciones en este punto: cambiar la clase de entidad de entrada o cambiar la palabra clave.
if not parameters[2].altered:
parameters[2].value = "POINT"
hasBeenValidated
hasBeenValidated es falso si el usuario ha modificado el valor de un parámetro desde la última vez que se invocaron updateParameters y una validación interna. Una vez que se invocó la validación interna, el geoprocesamiento se configura hasBeenValidated automáticamente en verdadero para cada parámetro.
hasBeenValidated se utiliza para determinar si el usuario ha cambiado un valor desde la última invocación de updateParameters. Puede utilizar esta información al decidir si hará su verificación propia del parámetro.
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].value:
if not parameters[6].altered:
extent = arcpy.Describe(parameters[0].value).extent
if extent.width > extent.height:
parameters[6].value = extent.width / 100
else:
parameters[6].value = extent.height / 100
return