Using the console

While you briefly used the QGIS Console in the previous chapter, it is worth examining the QGIS Console window in more detail, so that you are aware of the various features that are available.

If you don't already have it open, choose the Python Console item from the Plugins menu to open the console. The following screenshot shows the various parts of the console window:

Let's take a closer look at these various parts:

As we've already seen, you can type Python commands in the shell and press the Return key to execute them. The commands you type, along with the Python interpreter's output, appear in the Interpreter Log.

The Python Shell has been designed to make it easier to work with Python interactively. The following features are currently supported:

While typing commands into the Python Shell is a useful way of exploring the QGIS Python libraries, and is good for one-off commands, it quickly gets tedious if you have to type multiple lines of Python text or repeat the same set of commands over and over. After all, this is why we store Python code in .py files and execute them, rather than just typing everything into the Python command-line interface.

The QGIS Console comes with its own editor, allowing you to write Python scripts and execute them directly within the console. Let's take a quick look at how this works.

With the QGIS Console open, click on the Show Editor icon (). The console window will be split in half, with the Python source code editor now taking up the right-hand side of the window:

The various toolbar icons provide standard editing behavior such as loading and saving files, copying and pasting text, checking syntax, and executing your script:

You'll probably want to memorize the top three icons as there are currently no keyboard shortcuts to open and save Python scripts.

Let's use the console editor to create a simple Python program and run it. With a QGIS project loaded, type the following into the editor:

for layer in iface.legendInterface().layers():
    print layer.name() 

As you can probably guess, this program prints out the names of the various layers within the current project. To run this program, save it by clicking on the Save As... toolbar icon; then, either click on the Run script toolbar icon (), or type the keyboard shortcut, Ctrl + Shift + E (that's command + Shift + E on Mac). You should see something like the following appear in the Interpreter Log:

>>> execfile(u'/.../tmp1NR24f.py'.encode('utf-8'))
water
urban
basemap

Note that QGIS uses the execfile() function (which is part of the Python standard library) to execute your script.

Of course, there is a lot more that we can do with the QGIS Console and its built-in Python editor, and we'll be using it to do useful work shortly. Before we do, though, there are two final things you should know about the QGIS Console.

Firstly, the console itself is written in Python using PyQt and the PyQScintilla2 editor. You can learn a lot about how QGIS has been implemented by looking through the source code to the console, which is available at https://github.com/qgis/QGIS/tree/master/python/console.

The second thing you should know is that the console is implemented as a Qt "Dockable" window; that is, it can be dragged into a pane within the main QGIS window. If you click and hold the console's title bar, you can drag it inside the main window, as shown in the following illustration:

The console can be moved into any of the existing panes within the QGIS window, and it will stay there until you move it out.

To turn the console into a window again, click on the title bar and drag it out of the QGIS window. Alternatively, you can double-click on the console's title bar to switch between having it as a standalone window or a docked pane.

This docking behavior can be annoying if you're working on a small screen, where you can accidentally dock the console window while moving it out of the way so you can see what is beneath it. Fortunately, since the QGIS Console is implemented in PyQt, you can disable this quite easily by running the following Python code:

from console import console
from PyQt4.QtCore import Qt
console._console.setAllowedAreas(Qt.DockWidgetAreas(Qt.NoDockWidgetArea))

If you want, you can create a startup script that automatically shows the console and makes it nondockable whenever QGIS starts up. The startup script is stored in a hidden directory in your user or home folder. Using your file manager, look for a hidden directory named .qgis2 (or .qgis, depending on which version of QGIS you are running) in your user or home directory (for Mac OS X, you can use the Go to Folder... item in the Finder's Go menu). Inside this directory, there will be a subdirectory named python. Inside the python directory, create a file named startup.py and place the following into this file:

from console import console
from PyQt4.QtCore import Qt
console.show_console()
console._console.setAllowedAreas(Qt.DockWidgetAreas(Qt.NoDockWidgetArea))

As you can see, the only thing we changed was to add a call to console.show_console() to open the console window when QGIS starts.