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.

Mise à jour du schéma dans une boîte à outils PythonComportement de la licence dans une boîte à outils Python

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.

Méthodes des objets paramètre

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.

Propriétés des objets paramètre

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.

Types de données de la propriété Obtenu à partir de
RemarqueRemarque :

parameterDependencies équivaut au paramètre Obtenu à partir de de l'assistant Outil de script.

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

La propriété value d'un paramètre renvoie un objet, sauf si le paramètre n'est pas renseigné, auquel cas value renvoie None. Pour éviter qu'un paramètre ne soit pas renseigné, utilisez un contrôle if avant d'utiliser sa valeur.

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:  # check that parameter has a value
    if parameters[3].value == "Get Spatial Weights From File":
        parameters[8].enabled = True
    else:
        parameters[8].enabled = False

Comme un objet Value ne prend pas en charge la gestion des chaînes, utilisez la propriété de valeur de l'objet Value lorsqu'une chaîne doit être gérée ou analysée. L'exemple de code utilise la méthode os.path.dirname pour renvoyer le répertoire à partir d'un jeu de données.

if parameters[0].value:
    workspace = os.path.dirname(parameters[0].value.value)
RemarqueRemarque :

With the exception of Describe, don't use methods that take a catalog path, such as ListFields, in validation. The dataset may not exist when your tool is validated in ModelBuilder, and the method may fail or give unexpected results.

In the specific case of ListFields, the Describe object's fields property will provide the equivalent information.

RemarqueRemarque :

Don't set a parameter value in updateMessages() since the value will not be validated by the internal validation routine.

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

Thèmes connexes

5/10/2014