When the Python window is first opened, it will look similar to this:
The left section is the primary Python window prompt, where Python commands are executed. The right section is the help and syntax window, where execution messages are shown when tools are run and where help will be shown for the current tool, function, or class as code is entered.
The first step to accessing tools and other arcpy functionality in the Python window is to type arcpy. at the prompt, displaying a drop-down list of all arcpy tools, functions, and classes. This list can be scrolled through using the pointer or the UP and DOWN keys of the keyboard. As additional characters are entered, the drop-down list will be filtered to match only the tools or methods that match the characters entered. For example, if arcpy.addf is entered in the Python window, the drop-down list contains only the tools or methods that start with those characters. If arcpy.AddField_management is scrolled down to or clicked, the TAB key will autocomplete the full tool name at the prompt. When an opening parenthesis ( is entered, the arcpy.AddField_management tool's help will be shown in the help and syntax window. By default, the first parameter will be highlighted.
In Python, the tool name is used instead of the tool label. The tool label is displayed at the top of a tool dialog box or in the Catalog window. Tool names are typically similar to tool labels but do not contain spaces. In Python, the toolbox alias is also included along with the tool name.
Once all required parameters have been entered, press the ENTER key to execute the tool. Execution messages will appear in the help and syntax section of the Python window. The messages will have different text colors depending on the type of message. The default text colors and their meanings are as follows:
| Color | Meaning |
|---|---|
Black | Normal informational messages. |
Red | Error message. Results were not created. |
Orange | Warning message. Results may not be what you expect. |
You can change these colors by right-clicking in the Python window help and syntax section and selecting Format.
Required versus optional parameters
Tool parameters can be either required or optional. Optional parameters are surrounded by braces { }; required parameters are not.
| Parameter Type | Symbol | Meaning |
|---|---|---|
Required | Required parameter. These parameters are always the first parameters in the command. You must provide a value for required parameters. | |
Optional | { } | Optional parameter. These parameters always follow the required parameters. If you don't enter a value for an optional parameter, the default value is calculated and used. A parameter's default value can be found in the tool's help. |
Tools may have multiple optional parameters. Sometimes, only some of a tool's optional parameters are of interest and need to be set. There are three ways to skip, or move over, an optional parameter:
- Set the optional parameter to an empty set of quotation marks ("").
- Set the optional parameter to a pound sign in quotation marks ("#").
- Explicitly specify the parameter name to use, along with its value (bypass all but the named parameter).
In the following example, the Add Field tool is used, but the fourth and fifth parameters are left to their defaults using these three techniques:
# Use empty strings to skip optional parameters
arcpy.AddField_management("c:/data/streets.shp", "Address", "TEXT", "", "", 120)
# Use the # sign to skip optional arguments
arcpy.AddField_management("c:/data/streets.shp", "Address", "TEXT", "#", "#", 120)
# Use the parameter name to bypass unused optional arguments
arcpy.AddField_management("c:/data/streets.shp", "Address", "TEXT", field_length=120)
Default values
- Optional parameters have default values. If you enter a quoted # (pound sign), "" (two double quotation marks), '' (two single quotation marks), or a Python None for an optional parameter, the default parameter value will be used. For keywords, the default value is the first keyword in the list. See the help for an individual tool for its default parameter values.
- It is common to skip some optional parameters to get to the parameter you want to change.
Parameter drop-down lists
Drop-down lists are provided in the Python window whenever a tool recognizes available options for a specific parameter. As in a tool dialog box, the parameter will identify and filter appropriate values. For example, the tool AddXY_management accepts only point feature classes or layers for the input features, so the drop-down list for this parameter will only contain available point feature layers; similarly, the tool DeleteField_management will provide a drop-down list of fields based on the input table.
Multivalue parameters
A tool parameter can accept a single value or many values, depending on the parameter. When multiple values are acceptable, the parameter value can be specified as a Python list.
The Delete Field tool accepts multiple fields for deletion. To delete multiple fields using Delete Field, enter the field names as strings within a Python list.
arcpy.DeleteField_management("c:/base/rivers.shp", ["Type", "Turbidity", "Depth"])
Some tools, such as the Union_analysis and Intersect_analysis overlay tools, have parameters that are represented like a table; that is, they have multiple rows, with multiple values for each row. In the case of Union_analysis, the Input Features parameter supports the use of priority ranks, which are used to preserve features with high accuracy. A rank is assigned to each input feature class as an optional value, where 1 is the highest rank.
Parameters that are represented like a table are called Value Tables. Value Tables are input as a Python list of lists. For the Input Features parameter in Union_analysis, the rank is specified after the name of the feature class with a comma separating the values. Each feature class rank pair is contained within a higher list (hence, a list of lists). The example below shows how to create such a list. The workspace environment has been set to save you from repeating the same workspace for each feature class.
arcpy.env.workspace = "D:/St_Johns/data.mdb/neighborhoods"
input_list = [["east", 1], ["west", 1], ["south", 1], ["north", 2]]
arcpy.Union_analysis(input_list, "D:/base/data.gdb/land_use")
Parameter conventions
In general:
- Parameter names for all input datasets are prefixed with in_, and output datasets are prefixed with out_.
- The input dataset is usually the first parameter, and the output dataset is usually the last required parameter. Other required parameters are placed between the input and output datasets.
- Optional parameters always follow the required parameters.
Getting help in the Python window
Once you have entered the command name, there are several ways to get its usage and tool-specific help:
- Type the tool name at the prompt followed by an opening parenthesis: arcpy.Buffer_analysis(. This will display the tool's usage and help information in the help and syntax window.
- Use Python's built-in help function and pass in the name of the tool you need help with. The help will be displayed in the main Python section.
- Use Python's built-in function attribute __doc__ following the tool to show the documentation string. The help will be displayed in the main Python section.
>>> arcpy.Buffer_analysis(
>>> help(arcpy.Buffer_analysis)
>>> print arcpy.Buffer_analysis.__doc__