Techniques for sharing Python scripts
Release 9.3 Last modified October 19, 2010	Print all topics in : "Sharing tools and toolboxes"

The following are some techniques you can use when sharing your Python scripts with others.

Finding data relative to the script location

Your script may need to use "hard-wired" pathnames—pathnames to project data that exists and is not passed as an argument. For example, you may need to set the symbology property of your output parameter to an existing layer file, or clip your data to a known dataset.
If you are sharing your tool with others, you need to make sure that your script can find the project data it needs. A good way to do this is to use the ToolShare folder structure and place your project data in the ToolData folder and your scripts in the Scripts folder. If you follow this pattern, then you can always find your data relative to the location of your script.
When your script is run, the pathname to the script can be found using the following:

scriptPath = sys.path[0]

Once this location is known, you can find your project data relative to this location. The following code snippet demonstrates this.

import arcgisscripting, os, sys
gp = arcgisscripting.create(9.3)

# Get the pathname to this script
#
scriptPath = sys.path[0]
gp.AddMessage("Script folder: " + scriptPath)

# Get the pathname to the ToolShare folder
#
toolSharePath = os.path.dirname(scriptPath)
gp.AddMessage("ToolShare folder: " + toolSharePath)

# Now construct pathname to the ToolData folder
#
toolDataPath = toolSharePath + os.path.sep + "ToolData"
gp.AddMessage("ToolData folder: " + toolDataPath)

# Create the pathname to the parks feature class found in the ToolData folder
#
parkPath = toolDataPath + os.path.sep + "Project.gdb" +               os.path.sep + "Parks"
gp.AddMessage("Parks feature class: " + parkPath)

Finding a scratch workspace

If you create scratch data within your script, you need a scratch workspace where you can create and subsequently delete your scratch data.
Here are some things to keep in mind about finding a scratch workspace:

• You need write permission to the workspace.
  
• If the scratch workspace environment is set, use it—you have to assume it has been intentionally set by the user to a writeable location. In the case of a geoprocessing service running on an ArcGIS server, the scratch workspace will be set by ArcGIS Server to a specific writeable location.
  
• Be cautious of using the current workspace environment as a scratch workspace—it may be a remote database, and you never want to use a remote database as a scratch location since the overhead of communicating with the remote database defeats the purpose of quickly creating, writing, and deleting scratch data.
  
• If the scratch workspace environment has not been set, you need to find a writeable location. If this is the case, there a several options:
  


• If you're using the ToolShare folder structure, then you can use scratch.gdb in the Scratch folder. If you are practicing defensive programming, you should check that scratch.gdb exists—the user may have deleted it.
  
• If one of your script parameters is an output dataset, such as a feature class, you can safely assume you have write permission to the location of the output dataset, and you can use that as a scratch workspace. However, you need to check if the location is a feature dataset or a remote database. (As mentioned above, you never want to use a remote database as a scratch location because the overhead of communicating with the remote database defeats the purpose of quickly creating, writing, and deleting scratch data.)
  
• When all else fails, you can always use the system temp directory.
  



• Feature classes within shapefile and personal geodatabase workspaces have a two–gigabyte size limit. While two gigabytes is a lot of data, it is still limited. A file geodatabase workspace has a default limit of one terabyte (1,024 gigabytes) for a dataset. If you think that your scratch datasets could exceed two gigabytes, use a file geodatabase as the scratch workspace.
  
• Use gp.CreateScratchName() to create a unique dataset name in your scratch workspace.
  

The following code example shows a defensive implementation of finding a scratch workspace. This code

• Doesn't use the current workspace as a scratch workspace but can be easily modified to do so
  
• Assumes you're using the ToolShare folder structure
  
• Attempts to find and use a file geodatabase and uses a shapefile workspace as a last resort
  

import arcgisscripting, sys, os
gp = arcgisscripting.create(9.3)

def getScratchWorkspace(outDataset):
  # outDataSet is assumed to be the full pathname to a dataset. Typically,
  #  this would be a tool's output parameter value.
  #
  # Get the scratch workspace environment. If it's set, just return it.
  #
  scratchWS = gp.scratchWorkspace
  if scratchWS:
    return scratchWS

  # Let's go fishing...
  #
  # If you're using the ToolShare folder structure, look for scratch.gdb in
  #  the Scratch folder.
  #
  scriptPath      = sys.path[0]
  toolSharePath   = os.path.dirname(scriptPath)
  scratchWS       = toolSharePath + os.path.sep + "Scratch" +                     os.path.sep + "scratch.gdb"
  if not gp.Exists(scratchWS):
    scratchWS = ""

  # No scratch workspace environment and no scratch.gdb in the ToolShare folder
  #
  if not scratchWS:
    # Get the workspace of the output dataset (if any passed in)
    #  by going up one level
    #
    if outDataset:
      scratchWS = os.path.dirname(str(outDataset))

      # If this isn't a workspace, go up another level and
      #  test again. 
      #
      desc = gp.Describe(scratchWS)
      if desc.DataType.upper() <> "WORKSPACE":
        scratchWS = os.path.dirname(scratchWS)
        desc = gp.Describe(scratchWS)
        if desc.DataType.upper() <> "WORKSPACE":
          scratchWS = ""

  # If we have a workspace, make sure it's not a remote (SDE) database.
  #  If it is remote, set workspace to the system temp directory.
  #
  # If we don't have a workspace, just set it to the system temp directory.
  #
  usingTemp = False
  if scratchWS:
      desc = gp.Describe(scratchWS)
      if desc.WorkspaceType.upper() == "REMOTEDATABASE":
          scratchWS = gp.GetSystemEnvironment("TEMP")
          usingTemp = True
  else:
      scratchWS = gp.GetSystemEnvironment("TEMP")
      usingTemp = True

  # If we're using the system temp directory (a shapefile workspace), look 
  #  for a scratch file geodatabase.  If it exists, use it.  If it doesn't, 
  #  create it.
  #
  if usingTemp:
    scratchWS = scratchWS + os.path.sep + "scratch.gdb"
    if gp.Exists(scratchWS):
      return scratchWS
    else:
      gp.CreateFileGDB_management(gp.GetSystemEnvironment("TEMP"),                                   "scratch.gdb") 

  return scratchWS

# Main demonstration routine
#  One optional input parameter, a feature class. 
#
gp.LogHistory = True
aDatasetpath = gp.GetParameterAsText(0)
scratch = getScratchWorkspace(aDatasetpath)
gp.AddMessage("Scratch workspace: " + scratch)

# Create a scratch feature class in the scratch workspace
#
scrname = gp.CreateScratchName("temp", "","featureclass", scratch)

gp.AddMessage("Scratch feature class is: " + scrname)
gp.CreateFeatureClass(scratch, os.path.basename(scrname), "point")
gp.AddMessage(gp.GetMessages())

Sharing Python modules

Like any modern programming language, Python allows you to call routines found in other Python scripts. As you develop more and more Python code, you'll probably want to develop Python routines to share among scripts. The purpose of this section is to briefly show you how you can share routines, and give you enough information that you can effectively research and implement sharing of routines, starting with the official Python Web site (http://www.python.org).

Here are the contents of a script, helloworld.py:

def dosomething():
    print "Hello world"
def somethingelse():
    print "Goodbye world"

Here are the contents of a script, main.py:

import sys, os, helloworld
helloworld.dosomething()
helloworld.somethingelse()

The script main.py imports the helloworld module (a module name is equal to the script name minus the .py extension), along with the sys and os module. Note that the .py extension on helloworld is not needed (and, in fact, not allowed).
The script helloworld.py implements two routines (using the def statement) called dosomething, which prints the ubiquitous "Hello world," and somethingelse, which prints the less ubiquitous "Goodbye world." When main.py executes, it will call these two routines, which will print "Hello world" and "Goodbye world."

The two modules shown above lack a number of capabilities, such as importing the arcgisscripting module, fetching geoprocessing environments, error handling, and the like. These topics are all covered in Automating your work with scripts.

Where Python looks for modules

When main.py is executed, the import directive causes Python to look for a file named helloworld.py in its list of system directory paths. The first place Python looks is the current directory—the same directory as the script containing the import directive (in this case, main.py). You can display a list of these paths in the interactive window of PythonWin with the following:

import sys
sys.path

You cannot enter a pathname in the import directive such as

import E:\SharedScripts\helloworld

Rather, you must alter the list of directories where Python looks for modules. This list of directories is contained in the Windows environment setting called PYTHONPATH, which is installed by ArcGIS. To alter this setting, do the following:

1. Under Windows Start menu, click Settings > Control Panel.
   
2. Locate and open the System file.
   
3. Click the Advanced tab, then click Environment Variables.
   
4. Under System Variables, scroll to the PYTHONPATH variable and click to select it.
   
5. Click Edit.
   
The contents of PYTHONPATH should have <ArcGIS install directory>\bin as the first entry. This is where the arcgisscripting module resides. You can append more pathnames to directories containing your Python modules. The pathnames are separated by semicolons, and there must not be any spaces around each semicolon.

You can also append a pathname within your code with the following:

sys.path.append("e:\sharedmodules")

Sharing Python modules

If you are delivering script tools to other users and the scripts are importing other modules, you have two choices:

1. All scripts are to reside in the same directory.
   
2. You instruct users to install the additional modules somewhere on their system and have them modify the PYTHONPATH variable.
   

Using sys.path.append() is not recommended since it requires that the Python code be altered by users.

Pathnames and the escape character

Programming languages that have their roots in Unix and the C programming language, like Python, treat the backslash (\) as the escape character. For example, "\n" is used to insert a carriage return when writing text output; "\t" is used to insert a tab character. If a pathname in your script uses backslashes as the separator, Python will scan it and substitute a carriage return when it encounters a "\n" and a tab for a "\t". (There are other escape character sequences besides \n and \t.)
The easiest way to guard against this is to convert pathnames into Python rawstrings using the r directive, as shown below. This instructs Python to ignore backslashes.

thePath = r"E:\data\teluride\newdata.gdb\slopes"

Learn more about setting paths to data

Checking for licenses

If your script is using extensions or relies on tools that unavailable at the ArcView or ArcEditor product level, you need to first check for licenses and product levels.

Learn more about license checking in scripts

View lists of tools by license and product level

Please visit the Feedback page to comment or give suggestions on ArcGIS Desktop Help.
Copyright © Environmental Systems Research Institute, Inc.