The Script Runner plugin allows you to manage and execute a collection of scripts in QGIS to automate tasks and perform custom processing.
Version 0.6 of Script Runner has been released and includes these changes:
- Arguments can be passed to a script using keyword arguments
- Script output is logged to the Script Runner window
- Script output can be logged to disk
- Preferences dialog allows control of output and logging options
- Exceptions in scripts are displayed without interfering with console/logging output
- Context menu (right-click) to access script functions
- Edit script function uses system default editor or one you specify in preferences
For a basic introduction to Script Runner see this post: Script Runner: A Plugin to Run Python Scripts in QGIS
Working with Scripts
To run a script, you must add it to Script Runner using the
Add Script tool on
the toolbar. Select the script from the file dialog to add it to a list in the left panel. The list of scripts
is persisted between uses of QGIS.
Running a Script
To run a script, select it from your list of scripts and click the
Run tool. Output from the script will be displayed in the Script Runner console
Remove a Script
You can remove a script by selecting it from the list and clicking the
Remove Script tool. This just removes it from the list; it does nothing to the script
file on disk.
Info tool will populate
the Info and Source tabs in the panel on the right. The Info tab contains the
docstring from your module and then a list of the classes, methods, and
functions found in the script. Having a proper docstring at the head of your
script will help you determine the purpose of script.
At version 0.6 the
Info tool is only needed if you have disabled automatic display of info/source (see Preferences).
Viewing the Source
You can view the source of the script on the Source tab. This allows you to quickly confirm that you are using the right script and it does what you think it will.
Version 0.6 implements a number of new features.
Passing Arguments to a Script
You can pass arguments to your script using keywords. Your run_script function must have two arguments:
def run_script(iface, **args):
Running your script is done using the
Run script with arguments tool. This prompts you to enter your argument(s) in a key=value format:
All strings must be quoted and multiple arguments should be separated by a comma.
When your script is run, the arguments are contained in args, which is a Python dict. In the example above, you could access them like this:
my_path = args['path'] my_buffer_size = args['buffer_size']
Scripts that accept keyword arguments are displayed in the list with two asterisks appended to their name:
See Passing Arguments for a complete example.
Printing messages to the console can be useful for both development and status updates in long running scripts. You can clear the console using the
Clear Console tool. There is also an option in Preferences to clear the console each time a script is run.
Logging to Disk
You can choose to log everything that goes to the output console to disk. Use the Preferences dialog to setup the directory where the scriptrunner.log will be written.
Editing a Script
You can open the selected script in an external editor by right-clicking on it and choosing
Edit script in external editor from the popup menu. The default system editor for .py files will be used to open the script. In Preferences, you can specify a different editor by entering the full path to the executable.
The Preferences dialog allows you to set the following options:
Here are three script examples: a simple script that has only a run_script function, one that uses a Python class, and one that passes keyword arguments.
This simple script contains only a run_script function:
""" Load a layer and change the fill color to red. """ from PyQt4.QtCore import * from PyQt4.QtGui import * from qgis.core import * from qgis.gui import * def run_script(iface): mapreg = QgsMapLayerRegistry.instance() mapreg.removeAllMapLayers() wb = QgsVectorLayer('/data/world_borders.shp', 'world_borders', 'ogr') mapreg.instance().addMapLayer(wb) renderer = wb.rendererV2() symb = renderer.symbol() symb.setColor(QColor(Qt.red)) wb.setCacheImage(None) wb.triggerRepaint() iface.refreshLegend(wb)
When executed by Script Runner, the script removes any layers currently
on the map, then loads the
world_borders shapefile, sets its fill color to
red, and updates the map canvas and the legend. The
run_script function does all the work. You could expand this script by
adding additional functions that are called from run_script.
A Script with a Class
This script uses a class that is initialized from the run_script function to load some layers:
"""Load all shapefiles in a given directory. """ from glob import glob from os import path from qgis.core import * from qgis.gui import * import qgis.utils class Loader: def __init__(self, iface): """Initialize using the qgis.utils.iface object passed from the console. """ self.iface = qgis.utils.iface def load_shapefiles(self, shp_path): """Load all shapefiles found in shp_path""" print "Loading shapes from %s" % path.join(shp_path, "*.shp") shps = glob(path.join(shp_path, "*.shp")) for shp in shps: (shpdir, shpfile) = path.split(shp) print "Loading %s" % shpfile lyr = QgsVectorLayer(shp, shpfile, 'ogr') QgsMapLayerRegistry.instance().addMapLayer(lyr) def run_script(iface): ldr = Loader(iface) print "Loading all shapefiles in /qgis_sample_data/vmap0_shapefiles" ldr.load_shapefiles('/qgis_sample_data/vmap0_shapefiles')
In this example, the run_script function creates an instance (
ldr) of a
class named Loader that is defined in the same source file. It then calls a
method in the Loader class named load_shapefiles to do something
useful---in this case, load all the shapefiles in a specified directory.
This script illustrates passing an argument (a path) to load all shapefiles in a directory:
"""Load all shapefiles in a given directory.""" from glob import glob from os import path from qgis.core import * from qgis.gui import * import qgis.utils class Loader: def __init__(self, iface): """Initialize using the qgis.utils.iface object passed from the console. """ self.iface = qgis.utils.iface def load_shapefiles(self, shp_path): """Load all shapefiles found in shp_path""" print "Loading shapes from %s" % path.join(shp_path, "*.shp") shps = glob(path.join(shp_path, "*.shp")) for shp in shps: (shpdir, shpfile) = path.split(shp) print "Loading %s" % shpfile lyr = QgsVectorLayer(shp, shpfile, 'ogr') QgsMapLayerRegistry.instance().addMapLayer(lyr) def run_script(iface, **args): ldr = Loader(iface) print "Loading all shapefiles in %s" % args['path'] ldr.load_shapefiles(args['path'])
Lines 29 and 30 illustrate using the passed argument to print a message to the console and call the method to add the shapefiles to the map.
The script examples are minimalistic---they don't do error checking in a number of places, such as checking to see if a QgsVectorLayer is valid or if needed arguments were actually passed to the script. Don't take the scripts as examples of complete, solid code.
Comments on this post are welcome, as are bug reports. The link to the bug tracker for Script Runner can be found in the About box, along with the link to the code repository and my email address.