ArcGIS Help 10.1 - Anpassen von Werkzeugverhalten in einer Python-Toolbox

Die Validierung umfasst alle Schritte, bevor auf die Schaltfläche OK eines Werkzeugs geklickt wird. Wenn Sie benutzerdefinierte Werkzeuge erstellen, können Sie anhand der Validierung anpassen, wie Parameter reagieren und mit Werten und anderen Parametern interagieren. Die Validierung erfolgt mit einem Python-Codeblock, der zum Steuern des Werkzeugverhaltens verwendet wird.

Weitere Informationen zur Validierung finden Sie unter Validierung in Skriptwerkzeugen.

In einer Python-Toolbox verfügt jeder Werkzeugparameter über ein zugehöriges Parameter-Objekt mit Eigenschaften und Methoden, die für die Werkzeugvalidierung nützlich sind. In einer Python-Toolbox erfolgt die Definition von Parametern in der getParameterInfo-Methode der Werkzeugklasse. Das Verhalten dieser Parameter und ihre Interaktion miteinander und mit den Eingaben wird entsprechend der updateParameters-Methode der Werkzeugklasse überprüft.

Aktualisieren des Schemas in einer Python-Toolbox Lizenzverhalten in einer Python-Toolbox

Zugreifen auf Werkzeugparameter

Parameter-Objekte bilden die Grundlage für die Definition und Interaktion der Parameter in einer Python-Toolbox. Normalerweise wird die Parameterliste, wie im folgenden Code zu sehen, in der Methode getParameterInfo der Werkzeugklasse erstellt.

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]

Weitere Informationen zum Definieren von Parametern in einer Python-Toolbox finden Sie unter Definieren von Parametern in einer Python-Toolbox.

Parameterobjekt

Methoden

Methodenname	Verwendung
setErrorMessage(message:string)	Kennzeichnet den Parameter als fehlerhaft (rotes X) und gibt die entsprechende Meldung aus. Werkzeuge werden nicht ausgeführt, wenn ein Parameter einen Fehler aufweist.
setWarningMessage(message:string)	Gibt an, dass für den Parameter eine Warnung vorliegt (gelbes Dreieck), und gibt die entsprechende Meldung aus. Anders als bei Fehlern werden Werkzeuge bei Warnmeldungen ausgeführt.
setIDMessage(messageType: string, messageID: string, {AddArgument1}, {AddArgument2})	Ermöglicht Ihnen das Festlegen einer Systemmeldung. Die Argumente entsprechen denen der AddIDMessage-Funktion.
clearMessage()	Löscht alle Meldungstexte und setzt den Status auf "Information" (kein Fehler und keine Warnung).
hasError()	Gibt "true" zurück, wenn der Parameter einen Fehler enthält.
hasWarning()	Gibt "true" zurück, wenn für den Parameter eine Warnung vorliegt.
isInputValueDerived()	Gibt "true" zurück, wenn das Werkzeug in einem Modell überprüft wird und der Eingabewert der Ausgabe eines anderen Werkzeugs im Modell entspricht.

Parameterobjektmethoden

Eigenschaften

Name der Eigenschaft	Lesen/Schreiben	Werte	Beschreibung
name	Nur Lesen	String	Der Parametername
direction	Nur Lesen	String: "Input", "Output"	Eingabe-/Ausgaberichtung des Parameters
datatype	Nur Lesen	String	Eine Liste von Parameterdatentypen finden Sie unter Definieren von Parameterdatentypen in einer Python-Toolbox.
parameterType	Nur Lesen	String: "Required", "Optional", "Derived"	Der Parametertyp
parameterDependencies	Lesen/Schreiben	Python-Liste	Eine Liste der Indexwerte für jeden abhängigen Parameter
value	Lesen/Schreiben	Wertobjekt	Der Wert des Parameters
defaultEnvironmentName	Nur Lesen	String	Die Standardeinstellung für environment.
enabled	Lesen/Schreiben	Boolesch	"False", wenn der Parameter nicht verfügbar ist.
altered	Nur Lesen	Boolesch	"True", wenn der Wert geändert wurde.
hasBeenValidated	Nur Lesen	Boolesch	"True", wenn der Parameter von der internen Prüfroutine geprüft wurde.
category	Lesen/Schreiben	String	Die Kategorie des Parameters.
schema	Nur Lesen	Schema-Objekt	Das Schema des Ausgabe-Datasets.
filter	Nur Lesen	Filter-Objekt	Der auf die Werte im Parameter angewendete Filter.
symbology	Lesen/Schreiben	String	Der Pfad zu einer Layer-Datei (.lyr), die zur Darstellung der Ausgabe verwendet wird.
message	Nur Lesen	String	Die angezeigte Meldung. Siehe oben: SetErrorMessage und SetWarningMessage

Parameterobjekteigenschaften

parameterDependencies

Parameterabhängigkeiten werden normalerweise für die Verwendung durch das Schema-Objekt definiert. Es gibt zwei Fälle, in denen die Abhängigkeiten unter Umständen bereits in der getParameterInfo-Methode des Werkzeugs festgelegt sind.

Bei einem Ausgabe-Dataset-Parameter mit dem Typ "Derived" ist die Abhängigkeit der Indexwert des Parameters, von dem die Ausgabe abgeleitet wird.
Bei bestimmten Eingabedatentypen ist die Abhängigkeit der Indexwert des Parameters, der die vom Steuerelement verwendeten Informationen enthält (siehe folgende Tabelle).

Eingabedatentyp	Abhängiger Datentyp	Beschreibung
Feld oder SQL-Ausdruck	Tabelle	Die Tabelle mit den Feldern
INFO-Feld oder INFO-Ausdruck	INFO-Tabelle	Die INFO-Tabelle mit den Feldern
Coverage-Feature-Class	Coverage	Das Coverage mit den Features
Flächeneinheiten oder lineare Einheiten	GeoDataset	Geographisches Dataset, das zum Ermitteln der Standardeinheiten verwendet wird
Koordinatensystem	Workspace	Workspace, der zum Ermitteln des Standardkoordinatensystems verwendet wird
Hierarchie-Einstellungen für Network Analyst	Netzwerk-Dataset	Netzwerk-Dataset mit den Informationen zur Hierarchie
Geostatistische Wertetabelle	Geostatistischer Layer	Der Analyse-Layer mit den Tabellen

Abgerufen von"datatypes"

Abhängigkeiten werden normalerweise in der Methode getParameterInfo festgelegt:

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

Dies ist der vom Benutzer eingegebene oder von Ihnen durch Programmierung festgelegte Wert des Parameters. Sie können den Wert in der Methode getParameterInfo festlegen. In diesem Fall wird der Wert als anfänglicher Standardwert für den Parameter verwendet. Sie können den Wert auch in updateParameters als Reaktion auf Benutzereingaben festlegen, wie unten dargestellt.

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

Hinweis:

Die Parameterliste beginnt mit dem Wert null, das heißt, der erste Parameter befindet sich an Position null in der Liste. Um auf den dritten Parameter zuzugreifen, würden Sie parameters[2] verwenden.

Legen Sie keinen Parameterwert in updateMessages fest, da dieser Wert nicht von der internen Prüfroutine geprüft wird.

Ein Wert ist ein Objekt mit einer Zeichenfolgendarstellung. Mit dem folgenden Codeausschnitt wird überprüft, ob der Wert der Zeichenfolge "Get Spatial Weights From File" entspricht. Die Überprüfung funktioniert, weil es sich beim Datentyp des Parameters um eine Zeichenfolge handelt.

# 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

Die Überprüfung im obigen Code funktioniert nicht, wenn es sich beim Datentyp des Parameters um eine Feature-Class oder um einen Wert, der für ein Dataset steht, handelt. Werte, die für Daten auf einem Datenträger stehen wie Feature-Classes und Raster, müssen zuerst in eine Zeichenfolge konvertiert werden, bevor sie für Zeichenfolgenvorgänge verwendet werden können. Mit der integrierten Python-Funktion str werden Wertobjekte (value) folgendermaßen in Zeichenfolgen konvertiert:

if str(parameters[0].value) == "E:/data/example.gdb/roads":

Die Funktion str muss nur bei Werten mit Datentypen, die für Datasets stehen, verwendet werden. Bei diesen Werten gibt die str-Funktion den Katalogpfad zum Dataset zurück. Bei anderen Datentypen wie "long" oder linearen Einheiten muss diese Funktion nicht verwendet werden, da diese Datentypen keine Datasets repräsentieren und automatisch in Zeichenfolgen umgewandelt werden.

Achtung:

Verwenden Sie bei der Describe-Funktion in updateParameters niemals die Zeichenfolgendarstellung des Wertes.

Falsch	`desc = arcpy.Describe(str(parameters[0].value))`
Richtig	`desc = arcpy.Describe(parameters[0].value)`

Verwenden Sie nicht die Zeichenfolgendarstellung für Datasets (die den Katalogpfad zum Dataset liefert), da das Dataset möglicherweise nicht vorhanden ist. Es könnte sich um eine von einem Modell abgeleitete Variable handeln, und das Modell muss ausgeführt werden, bevor das Dataset auf dem Datenträger vorhanden ist. Wenn Sie die Zeichenfolgendarstellung für das Dataset verwenden, schlägt die Describe-Methode u. U. fehl, da das Dataset möglicherweise noch nicht auf dem Datenträger vorhanden ist.

Achtung:

Verwenden Sie in Validierungsmethoden keine ArcPy-Funktionen, die einen Katalogpfad akzeptieren, wie z. B. ListFields. Eventuell ist das Dataset bei der Validierung des Werkzeugs in ModelBuilder nicht vorhanden, was zu einem Fehler in der Methode führt. (Bei ListFields können Sie stattdessen die fields-Eigenschaft des Describe-Objekts verwenden.)

Wenn Sie Zeichenfolgen auf Äquivalenz überprüfen, sollten Sie möglichst Vergleiche verwenden, bei denen die Groß-/Kleinschreibung ignoriert wird. Im folgenden Beispiel wird der Shape-Typ einer Feature-Class mit der Python-Funktion lower in Kleinbuchstaben konvertiert, und die kleingeschriebenen Zeichenfolgen werden miteinander verglichen. (Alternativ können Sie mit der Funktion upper großgeschriebene Zeichenfolgen vergleichen.)

fc = parameters[0].value
shapetype = arcpy.Describe(fc).shapeType.lower()
if shapetype in ["point", "multipoint"]:

altered

altered ist "true", wenn der Wert eines Parameters geändert wurde, zum Beispiel durch Eingabe eines Ausgabepfades. Nachdem der Parameter geändert wurde, bleibt er geändert, bis der Benutzer den Wert leert (ausblendet). Dann kehrt er zu seinem nicht geänderten Zustand zurück. Eine programmatische Änderung eines Wertes durch Validierungscode hat keine Auswirkung auf den geänderten Zustand. Wenn Sie also einen Wert für einen Parameter festlegen, bleibt der geänderte Zustand (altered) des Parameters unverändert.

Mit altered können Sie ermitteln, ob der Wert eines Parameters geändert werden kann. Beispiel: Ein Werkzeug verfügt über einen Feature-Class-Parameter und einen Schlüsselwortparameter. Wenn die Feature-Class Punkte oder Polygone enthält, lauten die Schlüsselwörter ROT, GRÜN und BLAU. Bei Linien lauten sie ORANGE, GELB, LILA und WEISS.

Der Benutzer gibt eine Point-Feature-Class ein. Wird der Schlüsselwortparameter nicht geändert, setzen Sie den Wert auf ROT, da dies der Standardwert ist.

Gibt der Benutzer dann eine Line-Feature-Class ein, legen Sie den Standardwert als ORANGE fest, solange der Schlüsselwortparameter nicht geändert wird.

Wenn der Schlüsselwortparameter allerdings vom Benutzer geändert wird (das heißt, das Schlüsselwort wird auf GRÜN festgelegt), sollten Sie das Schlüsselwort nicht zurücksetzen, da der Benutzer eine Wahl getroffen hat (GRÜN) und Sie die zugrunde liegende Absicht nicht kennen. Eventuell ändert der Benutzer die Feature-Class, sodass GRÜN ein gültiger Wert ist, oder er ändert das Schlüsselwort (etwa in LILA). Da GRÜN nicht zur Gruppe der Schlüsselwörter gehört, die Sie für Linien definiert haben, wird der Parameter von der internen Prüfung als fehlerhaft gekennzeichnet. Der Benutzer hat dann zwei Möglichkeiten: Änderung der Eingabe-Feature-Class oder Änderung des Schlüsselworts

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

hasBeenValidated

hasBeenValidated ist "false", wenn der Wert eines Parameters seit dem letzten Aufruf von updateParameters und der letzten internen Prüfung geändert wurde. Nach dem Aufruf der internen Prüfung wird hasBeenValidated für jeden Parameter von der Geoverarbeitung automatisch auf "true" festgelegt.

Mit hasBeenValidated wird ermittelt, ob ein Wert seit dem letzten Aufruf von updateParameters geändert wurde. Sie können diese Information bei der Entscheidung heranziehen, ob Sie Ihre eigene Überprüfung des Parameters vornehmen möchten.

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

Anpassen von Werkzeugverhalten in einer Python-Toolbox