Personnalisation du comportement de l'outil dans une boîte à outils Python
La validation concerne tout ce qui se passe avant d'appuyer sur le bouton OK d'un outil. Lorsque vous créez vos propres outils personnalisés, la validation vous permet de personnaliser les modalités de réaction des paramètres ainsi que leurs interactions avec les valeurs et avec les autres paramètres. La validation s'effectue avec un bloc de code Python permettant de contrôler le comportement de l'outil.
Pour en savoir plus sur la validation, reportez-vous à la rubrique Présentation de la validation dans les outils de script.
Dans une boîte à outils Python, chaque paramètre d'outil dispose d'un objet Parameter associé comportant les propriétés et méthodes utiles à la validation d'outils. Dans une boîte à outils Python, les paramètres sont définis dans la méthode getParameterInfo de la classe d'outils. Le comportement de ces paramètres et la façon dont ils interagissent l'un avec l'autre et les entrées sont validés d'après la méthode updateParameters de la classe d'outils.
Accès aux paramètres de l'outil
Les objets Parameter constituent la fondation de la définition des paramètres et leur interaction dans une boîte à outils Python. La procédure habituelle consiste à créer la liste de paramètres dans la méthode getParameterInfo de la classe d'outil, comme illustré dans le code ci-dessous.
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]
Pour en savoir plus sur la définition des paramètres dans une boîte à outils Python, consultez la rubrique Définition de paramètres dans une boîte à outils Python.
Objet Parameter
Méthodes
|
Nom de la méthode |
Description de l'utilisation |
|---|---|
|
setErrorMessage(message:string) |
Indique une erreur sur le paramètre (un X rouge) avec le message fourni. Les outils ne s'exécutent pas si l'un des paramètres comporte une erreur. |
|
setWarningMessage(message:string) |
Indique qu'un avertissement sur le paramètre (un triangle jaune) avec le message fourni. Contrairement aux erreurs, les outils s'exécutent avec les messages d'avertissement. |
|
setIDMessage(messageType: string, messageID: string, {AddArgument1}, {AddArgument2}) |
Permet de définir un message système. Les arguments sont les mêmes que pour la fonction AddIDMessage. |
|
clearMessage() |
Supprime le texte de message et définit le statut sur information (pas d'erreur ou d'avertissement). |
|
hasError() |
Renvoie la valeur True si le paramètre contient une erreur. |
|
hasWarning() |
Renvoie la valeur True si le paramètre contient un avertissement. |
|
isInputValueDerived() |
Renvoie la valeur True si l'outil est validé à l'intérieur d'un Modèle et si la valeur en entrée correspond à la sortie d'un autre outil dans le modèle. |
Propriétés
|
Nom de la propriété |
Lecture/écriture |
Valeur(s) |
Description |
|---|---|---|---|
|
name |
Lecture seule |
Chaîne |
Nom du paramètre. |
|
direction |
Lecture seule |
Chaîne : "Entrée", "Sortie" |
Direction d'entrée/sortie du paramètre. |
|
datatype |
Lecture seule |
Chaîne |
Pour obtenir une liste de types de données de paramètre, consultez la rubrique Définition de types de données de paramètre dans une boîte à outils Python. |
|
parameterType |
Lecture seule |
Chaîne : "Requis", "Facultatif", "Dérivé" |
Type de paramètre. |
|
parameterDependencies |
Lecture/écriture |
Liste Python |
Liste des index de chaque paramètre dépendant. |
|
valeur |
Lecture/écriture |
Objet Value |
Valeur du paramètre. |
|
defaultEnvironmentName |
Lecture seule |
Chaîne |
Paramètre d'environnement par défaut. |
|
enabled |
Lecture/écriture |
Booléen |
Valeur False si le paramètre est indisponible. |
|
altered |
Lecture seule |
Booléen |
Valeur True si l'utilisateur a modifié la valeur. |
|
hasBeenValidated |
Lecture seule |
Booléen |
Valeur True si la routine de validation interne a vérifié le paramètre. |
|
category |
Lecture/écriture |
Chaîne |
Catégorie du paramètre. |
|
structure |
Lecture seule |
Objet Schema |
Structure du jeu de données en sortie. |
|
filter |
Lecture seule |
Objet Filter |
Filtre à appliquer aux valeurs dans le paramètre. |
|
symbologie |
Lecture/écriture |
Chaîne |
Chemin d'accès à un fichier de couches (.lyr) utilisé pour afficher la sortie. |
|
message |
Lecture seule |
Chaîne |
Message à afficher à l'utilisateur. Reportez-vous aux méthodes SetErrorMessage et SetWarningMessage ci-dessus. |
parameterDependencies
Vous définissez généralement des dépendances de paramètres à utiliser par l'objet Schema. Dans deux cas, les dépendances peuvent avoir déjà été définies dans la méthode getParameterInfo de l'outil.
- Pour un paramètre de jeu de données en sortie de type Dérivé, la dépendance est l'index du paramètre à partir duquel la sortie est dérivée.
- Pour certains types de données en entrée, la dépendance est l'index du paramètre qui contient les informations utilisées par le contrôle, comme illustré dans la table ci-dessous.
|
Type de données en entrée |
Type de données dépendantes |
Description |
|---|---|---|
|
Champ ou expression SQL |
Table |
Table qui contient les champs. |
|
Elément INFO ou expression INFO |
Table INFO |
La table INFO qui contient les attributs. |
|
Classe d'entités de couverture |
Couverture |
La couverture qui contient des entités. |
|
Unités de surface ou unités linéaires |
Jeu de données géographiques |
Un jeu de données géographiques utilisé pour déterminer les unités par défaut. |
|
Système de coordonnées |
Espace de travail |
Un espace de travail utilisé pour déterminer le système de coordonnées par défaut. |
|
Paramètres de hiérarchie Network Analyst |
Jeu de données réseau |
Le jeu de données réseau qui contient les informations de hiérarchie. |
|
Table de valeurs géostatistiques |
Couche géostatistique |
Couche d'analyse qui contient les tables. |
Les dépendances sont généralement définies dans la méthode 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
valeur
C'est la valeur du paramètre que l'utilisateur a saisie ou que vous avez définie à l'aide d'un programme. Vous pouvez définir cette valeur dans la méthode getParameterInfo, auquel cas elle devient la valeur initiale par défaut du paramètre. Vous pouvez également définir la valeur dans updateParameters en réponse aux informations saisies par l'utilisateur, comme illustré ci-dessous.
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
Remarque :La liste des paramètres démarre à zéro, la position zéro est donc attribuée au premier paramètre de la liste. Pour accéder au troisième paramètre, vous devez utiliser parameters[2].
Ne définissez pas la valeur d'un paramètre dans updateMessages, car elle ne sera pas validée par la routine de validation interne.
Une valeur est un objet avec une représentation de chaîne. L'extrait de code ci-dessous vérifie si la valeur est égale à la chaîne "Extraire les pondérations spatiales à partir du fichier". Ce test fonctionne car le type de données du paramètre est une chaîne.
# 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
Le test dans le code ci-dessus ne fonctionnerait pas si le type de données du paramètre était une classe d'entités ou toute valeur représentant un jeu de données. Les valeurs qui représentent des données sur le disque, telles que les classes d'entités et les rasters, doivent être converties en chaînes avant d'effectuer des opérations de chaînes. La fonction str intégrée de Python convertit les objets Value en chaînes, comme suit :
if str(parameters[0].value) == "E:/data/example.gdb/roads":
Il vous suffit d'utiliser la fonction str pour les valeurs avec des types de données qui représentent des jeux de données. Pour ces types de valeurs, la fonction str renvoie le chemin d'accès de catalogue au jeu de données. Il n'est pas nécessaire d'utiliser cette fonction pour d'autres types de données, tels que les unités linéaires ou longues, puisque ces types de données ne représentent pas de jeux de données et sont automatiquement convertis en chaînes.
Attention :Lors de l'utilisation de la fonction Describe dans updateParameters, n'utilisez jamais la représentation de chaîne de la valeur.
Incorrect | |
Correct | |
Vous ne devez pas utiliser la représentation de chaîne pour les jeux de données (qui détermine le chemin d'accès de catalogue au jeu de données) car le jeu de données peut ne pas exister : il peut être une variable de modèle, et le modèle doit être exécuté avant que le jeu de données existe sur le disque. Si vous utilisez la représentation de chaîne pour le jeu de données, la fonction Describe peut échouer si le jeu de données n'existe pas encore sur le disque.
Attention :n'utilisez pas les fonctions ArcPy qui utilisent un chemin d'accès de catalogue, telles que ListFields, dans les méthodes de validation. Il se peut que le jeu de données n'existe pas lorsque votre outil est validé dans ModelBuilder, la méthode risque alors d'échouer. (Dans le cas de ListFields, vous pouvez utiliser la propriété fields de l'objet Describe à la place.)
Lorsque vous testez l'équivalence des chaînes, vous devez utiliser des comparaisons insensibles à la casse. Le code suivant montre l'utilisation de la fonction Python lower pour écrire le type de forme d'une classe d'entités en minuscules et comparer les chaînes en minuscules. (Vous pouvez également utiliser la fonction upper pour comparer des chaînes en majuscules.)
fc = parameters[0].value
shapetype = arcpy.Describe(fc).shapeType.lower()
if shapetype in ["point", "multipoint"]:
altered
altered a la valeur True si l'utilisateur a modifié la valeur d'un paramètre, en saisissant un chemin en sortie, par exemple. Lorsqu'un paramètre a été modifié, il le reste jusqu'à ce que l'utilisateur vide (efface) la valeur, auquel cas il revient à son précédent état. La modification d'une valeur à l'aide d'un programme avec un code de validation ne change pas l'état Altered. Autrement dit, si vous définissez une valeur pour un paramètre, l'état Altered du paramètre ne change pas.
La propriété altered permet de déterminer si vous pouvez modifier la valeur d'un paramètre. Supposez par exemple qu'un outil contienne un paramètre de classe d'entités et un paramètre de mot-clé. Si la classe d'entités contient des points ou des polygones, les mots-clés sont RED, GREEN et BLUE et si elle contient des lignes, les mots-clés sont ORANGE, YELLOW, PURPLE et WHITE.
Supposons que l'utilisateur entre une classe d'entités ponctuelles. Si le paramètre de mot-clé est inchangé, vous définissez la valeur sur RED, car c'est la valeur par défaut.
Si une classe d'entités linéaires est entrée, vous définissez la valeur par défaut sur ORANGE tant que le paramètre de mot-clé reste inchangé.
Cependant, si le paramètre de mot-clé a été modifié par l'utilisateur (c'est-à-dire si le mot-clé est défini sur GREEN), vous ne devez pas réinitialiser le mot-clé : l'utilisateur a fait son choix (GREEN) et vous ne connaissez pas son intention, il peut modifier la classe d'entités afin que GREEN soit valide ou modifier le mot-clé (en spécifiant PURPLE, par exemple). Puisque GREEN ne fait pas partie de l'ensemble de mots-clé que vous avez créé pour les lignes, la validation interne marque le paramètre comme contenant une erreur. L'utilisateur a alors deux options : modifier la classe d'entités en entrée ou modifier le mot-clé.
if not parameters[2].altered:
parameters[2].value = "POINT"
hasBeenValidated
La valeur de hasBeenValidated est false si la valeur d'un paramètre a été modifiée par l'utilisateur depuis le dernier appel de la méthode updateParameters et de la validation interne. Lorsque la validation interne est appelée, le géotraitement définit automatiquement hasBeenValidated sur True pour chaque paramètre.
hasBeenValidated permet de déterminer si l'utilisateur a modifié une valeur depuis le dernier appel de la méthode updateParameters. Vous pouvez utiliser cette information pour décider si vous devez effectuer un contrôle du paramètre.
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