Physics & Computer Science

Using Eclipse with PyDev

Introduction

This document refers to Eclipse 4.8 (Photon) for Windows, the most current version as of this writing. Note that different computer set ups and themes may mean that the appearance of the screen shots in this document may not match exactly your computer system. In particular, the Mac version of Eclipse looks significantly different, although it has the same functionality as the Windows version.

Note: Installation instructions for a specific operation system are boxed and preceeded by the following icons:

Windows
Mac
Linux

This is a short primer on using Eclipse / PyDev (Python Development Environment) on Laurier's network.

Eclipse organizes your work into workspaces and projects. A workspace may contain many projects, and a project may contain many modules and/or files. The Eclipse organization hierarchy looks like this:

The Eclipse Hierarchy

In CP104 you should have one workspace for the course. All programs must be created as Eclipse projects. Each workspace and project represents a folder in your operating system's file system. A project contains one or more .py Python source code files, and may contain other types of files as required. A project can be saved as a .zip (zip-encoded) file for submission or for moving to another computer. A project typically represents a lab or an assignment.

Installing Eclipse

Please see CP104 Software Installation.

The Eclipse Main Window

The Eclipse main window is generally displayed with four sections:

Eclipse Main Window
The Eclipse Main Window

The Editor Pane

Use the Editor pane to edit multiple source code files, although only one file is visible at a time. In the example the file t2.py is open in the editor. The editor allows typical editing functions (input, deletion, searching, replacing, etc.) as well as code formatting and code completion. Different parts of the code are displayed differently depending on their purpose. This helps you write and debug code. In this example Python keywords are in blue, text in green, variables in black, and numeric values in red. Line numbering helps you locate execution errors.

Editor Pane
The Editor Pane

The Console Pane

Python programs with only text input/output can be run in the Console pane. The Console pane allows you to enter values, copy output, or terminate the running program. The Console pane also displays messages caused by execution errors. The example shows that the user has entered a value of 500 in response to the program's prompt for the size of a tract of land. Note that the input is in green to distinguish it from the program output. Error messages are displayed in red.

Console
The Console Pane

The square red icon at the top centre of the Console pane is the Terminate button. If a programs does not end normally, use this button to cancel its execution. Failing to do so can leave multiple programs running under Eclipse. Leaving too many of these programs running degrades Eclipse's performance or even causes it to crash.

The Console pane may also contain a Problems tab. Warnings and errors in program syntax and compilation are displayed in the Problems tab. (The Problems tab is not initially displayed if there are no problems with the code being edited.) Double-clicking on an error or warning moves the cursor to the location of that warning or error in the Editor pane. This example shows that there is one error and one warning in the programs currently being edited.

Problem Tab
The Problems Tab

The Eclipse main window can be customized and these various panes can be be dragged to different positions within the main window or even be hidden. If a section seems to be hidden you can display it by selecting Window / Show View from the main menu, or choose Reset Perspective to return the Eclipse screen setup to its default values.

Views
The Window Menu

Creating Projects

Creating a new PyDev project consists of a number of steps:

Setting a Workspace

Before creating a new Eclipse project, make sure you are in the correct workspace. The first thing to do upon starting Eclipse is to change the workspace to your own folder, either on your own laptop or on a device such as a USB memory stick. Do not put a workspace on the local drive of a lab machine as it will be erased when the machine is rebooted. To set a workspace select File / Switch Workspace from the main menu. This brings up the Workspace Launcher dialog box:

Workspace Window
The Workspace Dialog

From here browse to your own workspace using the Select Workspace Directory dialog box:

Select Workspace Directory
Workspace Selection Dialog

If you do not yet have a workspace, use the Make New Folder button to create a new workspace folder. You may have multiple workspaces - we recommend at one workspace per course that uses Eclipse. More than one workspace for a course is unnecessary.

Customizing a Template

Eclipse can be set up to save you time by automatically creating default documentation whenever you create a new PyDev module. To set this documentation up with your own information, follow these steps:

Creating a New PyDev Project

Once in your own workspace, create a new PyDev project by right-clicking in an empty area of your Package Explorer and choosing New / Project / PyDev Project from the pop-up menu. This brings up the PyDev Project dialog.

If the Eclipse workspace has not yet been set up to work with a version of Python, you will see the warning Project interpreter not specified (outlined in red):

notSpecified (25K)
Interpreter Not Specified

To specify the Python interpreter you will use in your workspace, click on the Please configure an interpreter before proceeding link. This brings up the Configure interpreter dialog:

configureInterpreter (39K)
Configure Interpreter Dialog

Click on . (Older version may say instead). Depending on how many different versions of Python are installed on your computer, you must select one of them:

multipleInterpreters (11K)
Multiple Interpreters Dialog

Choose a version of Python that is 3.0 or higher. Generally pick the most recent one.

This brings up the Selection needed dialog box:

selectionNeeded (20K)
Selection needed Dialog

Simply click on until you get back to the PyDev Project dialog box.

Having set up the proper version of Python for your workspace, in the PyDev Project dialog:

as shown below:

newProject (32K)
PyDev Project Dialog

All other options can be left with their default values.

In this example, the project creates a new folder named barn4520_a02 and stores it in the cp104 workspace. (This workspace is actually the E:\workspaces\cp104 folder.) The project itself is stored in the folder E:\workspaces\cp104\barn4520_a02 ; i.e. the folder name matches the workspace and project names. By default the project creates a separate folder ( src ) for source files. Click on .

The project barn4520_a02 is now added to the Package Explorer pane, and contains a src folder and a reference to the Python interpreter (in this case the Python 3.6 interpreter). Put your Python source code files (files that end in .py ) in the src folder. The interpreter reference is a system element and must be left alone.

New Project Package Listing
New Project Contents

Adding Source Code Files (PyDev Modules)

Add source code files to the source code folder of a project by right clicking on the src folder of your project in the Package Explorer pane and selecting New / PyDev Module from the pop-up menu:

Right Click New Module
Right Click New PyDev Module

This brings up the Create a new Python module dialog:

New Module
New Module

Give the module a name, and click on to continue. This brings up the Template dialog:

selectTemplate (12K)
Select Template

Select the appropriate template (in this example, <Empty>, and click on . In this example a file named t1.py is created in the src folder of the someProject project.

The module is now added to the selected package in the Navigator pane and is opened in the Editor pane, as in this example:

newFile (17K)
New Module

You can now fill in the [program description] parts of the documentation, enter Python code, edit it, and execute the resulting program.

Executing a Python Program

To execute a program from within Eclipse, open the file in the editor, right click anywhere in the body of the program, then select Run / Python Run from the pop-up menu. The program is then executed either in the console or in its own window. Python text-based programs execute within the console. Python GUI-based programs open their own windows.

In order to enter keystrokes into the Console pane it must have focus; i.e. you must click on the Console tab before you can start typing into the Console. When the Console has focus, its tab is white. If it does not have focus, its tab is the same grey as the menu bar background.

Console
Console

Sometimes is it necessary to kill an executing program - either because you don't want to go to the trouble of running it because you've already found an error, or perhaps because you have an endless loop and the program will never stop otherwise. Having too many Python programs running inside Eclipse can literally slow down your machine, and if enough programs are running cause it to crash.

The following Python code never ends on its own:

while True:
    print( "Never ends!" )

To kill it, click on the red double-square: Terminate All. All Python programs currently running in Eclipse are stopped.

Terminate a Program
Terminate a Program

You may then clear out the console by clicking the grey double-x: Remove All Terminated Launches. The console is cleared and ready to run the next program.

Clear Console
Clear Console

Copying and Pasting Results

To create a test results file (typically named testing.txt), create the file in a project's src folder by right-clicking on the src folder and choosing New / File:

New Text File
Create Test Results File

In the New File dialog, enter the file name:

New File Dialog
New File Dialog

You may copy the contents of the Console to the clipboard by right-clicking on the Console and choosing Select All from the pop-up menu, and then Copy with a second right-click, as in this example:

Copy Paste
Copy - Paste

You may then paste the contents of the clipboard to the test results file.

Exporting a Project

In order to submit Python programming assignments or copy projects to other computers you must export a project. Projects can be exported in a number of ways, but normally you will export a project as an archive (i.e. a .zip file). To export a project, right click on the project name in the Package Explorer pane then select Export... from the pop-up menu.

Export Dialog
Right Click Export

This brings up the Export dialog box:

Export Dialog
Export Dialog

From this dialog box select the General / Archive File option and click on . On the next page of the Export dialog box, enter the name and location of the archive file and click on . By default the export dialog selects all files in a project, as well as recreating its directory structure in the resulting .zip file:

Important!

Export Dialog
Export Dialog

If you see the error: Resource is out of sync with the file system... , Eclipse thinks that a project file has been changed by a non-Eclipse program. (This can happen if you edit anything in the project folder from outside Eclipse.)

resourceSync (11K)
Resource Synchronization

Your .zip file has actually been exported. To get rid of the error anyways, go back to the project, right click on the project name and choose Refresh . (You may also just press the F5 function key.) This 'resyncs' the project, and you may export it without annoying error messages. You may have to overwrite the original .zip file.

Importing a Project

Upon occasion you may wish to import a project into a workspace - perhaps you want to copy a project from one computer to another, or you want to consolidate two workspaces into one, or you want to import a sample project to examine. For CP104, all assignment solutions will be provided as an archive file which you can import to view and run the assignment solutions.

There are two typical types of imports. The first is to import an archive file containing a project that was exported as in the section above. The second is to import projects directly from another workspace. Both import methods start with a right click in the Package Explorer pane and choosing Import... from the pop-up menu.

Import Dialog
Right Click Import

This brings up the Import dialog box:

Import Dialog
Import Dialog

From this dialog box select the General / Existing Projects into Workspace option and click on . To import an archive file containing a project, click on the Select archive file radio button, and then to the location of the archive file you wish to import. The Projects box lists all of the projects in the archive file. Click on the checkbox of the project(s) you wish to import, and click on . (If you do not see any projects listed in the Projects box, then the archive file does not contain any valid Eclipse projects! If you get the warning Some projects cannot be imported because they already exist in the workspace, then some of the selected projects already exist in the workspace, and if you import them you overwrite the existing projects. Be careful!)

Import Browse
Import Browse Dialog

Note that if you already have a project in your workspace with the same name as a project you wish to import, Eclipse displays a warning message to that effect at the top of the Import dialog box, and does not allow you to click on that project's checkbox in the projects list. (See the example above.)

Renaming a Project

Open the project to be renamed if it is closed. In the Package Explorer right-click on the project name and choose Rename…:

Right-Click Rename
Rename Selection

Then simply rename the project in the Rename Resource dialog box:

Rename Dialog
Rename Dialog

Multiple Python Interpreters

If you have a workspace that is used on multiple computers - a workspace stored on a USB memory stick, a portable drive, or a network drive - this workspace must be configured to work with different computer set ups. Typically, the location of the Python interpreter differs from computer to computer, or the Python interpreters may even be of different versions.

A workspace can be set up to work with different Python interpreter locations and versions. Note, however, that interpreter versions must be of the same major version. i.e. a workspace compatible with Python 3 works with Python 3.0 or any higher versions 3.1, 3.2 to 3.X , but not with any version of Python 2.

You may add a second or subsequent Python interpreter to a workspace in the same way you added the first Python interpreter to a workspace. (See the instructions in the Configuring PyDev section of the Installing Python, Eclipse, and PyDev tutorial. The following example shows a workspace configured with two Python interpreters on two different drives (on different computers):

Multiple Interpreters
Multiple Python Interpreters

Thus, if the workspace shown here is on a USB memory stick, it will work with a computer that has a Python interpreter on drive C:, and on a second computer with its Python interpreter on drive E: (in the folders shown). You may configure a workspace to work on multiple operating systems. Thus a workspace may have simultaneously listings for interpreters on a Windows PC, a Mac laptop, and a linux box.

If upon moving a workspace to another computer the PyDev projects complain that they cannot find a Python interpreter, you may have to change the order the interpreters are listed in the workspace. In the Python Interpreters dialog box, select the interpreter appropriate to the computer being used and move it to the top of the interpreter list by clicking on the Up button. In the example above, this would move the interpreter on drive E: to the top of the list, making it the default interpreter for the workspace. You may move interpreters up and down the list at any time. If necessary, close and re-open the project for it to recognize the new default interpreter.

Running Python on a Command Line

You may start a Python session on a command line without invoking a program simply by typing python at a command line prompt:

Python Command Line
Python Command Line

You can now enter and test simple Python commands without having to enter and save an entire program. Press Ctrl-Z to exit this mode.

Invoking a command line differs amongst various operating systems. Getting to a command line in Windows, a Mac, or on Linux are beyond the scope of this document.

Project Reference

Code reuse is an important part of good programming practices. Although code can be copied between packages, a far better approach is to set up references to packages, source code, and classes between projects. Create a reference from one project to another by right-clicking on a project in the Package Explorer pane and select Properties / Project References from the pop-up menu. This displays the Properties for ... dialog box:

Project References
Project References

From this dialog box select any external projects you wish to reference from the current project. Note: this step is only necessary if this project needs to reference another one. If the project is stand alone there is no need to reference any other project.

When exporting projects, you must explicitly select any referenced projects to be included in the exported .zip file:

exportReferences (38K)
Exporting Referenced Projects

Resources

http://www.eclipse.org/
The Eclipse home page.
http://www.oracle.com/technetwork/java/index.html
The Java home page.
https://www.python.org/
The Python home page.
http://www.pydev.org/
The PyDev home page.
http://www.python.org/dev/peps/pep-0008/
A style guide for Python code.
http://wiki.python.org/moin/
The Python wiki.