PyCharm Edu 4.0 Help

Educator's Guide

In this section:

Overview

This guide is intended for the educators who want to create their courses and assignments with PyCharm Edu. You will learn how to create a course, add lessons and tasks, write exercise code and tests for a task, how to pack your project into a course archive and upload this archive to be shared with the students.

Note: PyCharm Edu runs on Windows, Linux and Mac platforms. We used Windows to prepare this guide. On Linux and Mac some menu names or workflows may slightly differ.

PyCharm Edu basics

Course

A course is just a project of a special type. It consists of lessons.

Lesson

A lesson is a directory where the task files are stored. Each lesson can contain several tasks.

Task

A task is a directory where the following files are stored:

  • Task description which you have to type in the Task Description tool window
  • The file with the extension .py, that contains the exercise code and can contain answer placeholders
  • the test file tests.py that helps you make sure that the students have fulfilled your task correctly.

Also a task can contain more files required for fulfilling it.

Answer placeholder

An answer placeholder is a frame shown to the students that replaces and hides a part of your initial code. These placeholders should contain descriptions of actions to be taken by the students to complete the tasks. You have to create descriptions of these actions yourself.

The first mouse click inside the answer placeholder selects the entire placeholder; the second mouse click removes selection.

Hints

If the students are not sure of themselves, they can view hints. The hints are also created by the educators.

Prerequisites

Make sure that the following prerequisites are met:

  • You are working with the latest version of PyCharm Edu.
  • You have a Python interpreter properly installed on your computer. Refer to the section Configuring Python Interpreter for details.

You can opt to install the Anaconda or Canopy libraries, which include the superset of the scientific stack comprising most of the mentioned libraries as recommended by Google engineers. Note that the libraries are really huge!

For this particular course the following packages are required:

Enabling the Course Creator features

This step is mandatory! Unless the course creator features are enabled, you cannot create a course!

Course Creator features are disabled by default. You can enable course creator feature in one of the following ways:

  • When you first start PyCharm Edu, you see the following image:
    /help/img/idea/2017.2/pe_student_or_teacher.png
    Choose the option "teacher", and then proceed with creating project.
  • If you already have an open project, select the check-command Enable Course Creator Features on the Help menu:
    /help/img/idea/2017.2/enable_course_creator_features.png

The commands that allow you to create courses appear.

Creating a course

You can create a project in two possible ways: either from the Welcome Screen by choosing the Create new course command, or by choosing File | Create New Course on the main menu:

/help/img/idea/2017.2/pe_create_course1.png

In the Create Project dialog, specify the location of your course project, the Python interpreter that will be used for your course, the name of your course, and its description. Note that the availability of the Python interpreter depends on your platform. When ready, click Create:

/help/img/idea/2017.2/pe_create_course.png

The project for the first educational course is ready.

What’s inside this project?

As you see in the Project view, PyCharm Edu has created some infrastructure:

/help/img/idea/2017.2/pe_course1.png

There is one top-level node in the Project tool window: PyCharmTutorialCourse /help/img/idea/2017.2/course_icon.png. If you expand it, the nested elements become visible.

  1. Under the number 1 (PyCharmTutorialCourse), you see the files and folders pertaining to your new project. As you can see, there is not so much so far…
    • The folder lesson1 denoted with the icon /help/img/idea/2017.2/lesson.png. This folder contains two stub files: task.py and tests.py. These files are color-coded: the black file is visible to the students (task.py), and the grey file (tests.py) is not visible to them.
    • The file test_helper.py is a library of auxiliary functions, which help you write custom checks and tests for your tasks. This file is grey.
  2. The opened Task Description tool window. It features the toolbar with the icons that allow you to check the task execution (/help/img/idea/2017.2/check_task.png), move between tasks (/help/img/idea/2017.2/arrowBack.png/help/img/idea/2017.2/arrowForward.png), refresh task (/help/img/idea/2017.2/refresh_task.png), view hints (/help/img/idea/2017.2/intentionBulb.png), and edit tasks (/help/img/idea/2017.2/edit1.png).

    Note the following:

    1) these actions are available to the students.

    2) the action Refresh Task(/help/img/idea/2017.2/refresh_task.png) is disabled for the educators.

  3. There is the now empty space, which will be occupied by the editor - if you press F4 on a file in the Project tool window, its content will appear in a separate tab in the editor.

Python interpreter

Why do we need a Python interpreter at all? You will write programs in Python, that’s why an interpreter is mandatory.

You know that the availability of the Python interpreter depends on your platform. Increase the list of available interpreters by clicking /help/img/idea/2017.2/cogwheel_framed.png in the Select Project Type dialog.

Refer to the section Configuring Python Interpreter for details.

Note that different versions of Python have different syntax and features. For example, Python 2.x and Python 3.x significantly differ from each other. That’s why the students should refer to the same interpreter that was used in the course. However, there are no rigid rules. A student may successfully use Python 3.3, while the lecturer in his/her course may use Python 3.4.

Creating the first lesson

Now it’s time to flesh out the project.

Note: PyCharm Edu has already created templates for the first lesson and the first task for your convenience.

In the Project tool window, select lesson1 and press Shift+F6. In the dialog box that opens, type the new name of the lesson (here it is Basics), and then click OK:

/help/img/idea/2017.2/pe_rename_lesson.png

Thus, you've performed the rename refactoring.

Next, let's rename the task task1 of the Basic lesson. To do that, click this task and press Shift+F6:

/help/img/idea/2017.2/pe_rename_task.png

Note that other refactorings work for the lessons and tasks too: Copy, Move, Safe Delete.

Next, let's add an image file that should be read. PyCharm Edu makes importing such a file quite easy - just drag it to the Project tool window, and then specify the target directory in the Move dialog:

/help/img/idea/2017.2/pe_add_image.png

This image file does not belong to the Read Images task - so, let's add it. To do so, right-click the image file, and choose Course Creator | Make Visible to Students:

/help/img/idea/2017.2/pe_add_as_task_file.png

Writing a task text

Now it’s time to write a task description. Go to the Task Description tool window and click /help/img/idea/2017.2/edit1.png. You see that HTML markup appeared:

<html> Write your task text here. <br> </html>

(Note that you can also use Markdown to write your description… The language is configured in the page Tools | Education of the Settings/Preferences dialog.)

Instead of the existing text, type the following:

<html> Use <b>imread</b> function to load PyCharm Edu logo and play with it a little bit. <br> </html>

To see this text as it will be viewed by the students, just release the button /help/img/idea/2017.2/edit1.png.

Writing an exercise code for a task

Why do we need to write an exercise code? An exercise code is a part of a task. Some fragments of this exercise code will be replaced with the answer placeholders, which we'll create later. The students, when performing a task, will have to fill in these fragments with their own code.

For example, we are going to create a console application that reads an image file. To fulfil this example, open for editing the read_images.py file (F4), and type the exercise code:

from skimage import io image_name = "PyCharm.png" img = io.imread(image_name) print(img.shape) img_gray = io.imread(image_name, as_grey=True) print(img_gray.shape)

Note: It is advisable to write a valid code as a working solution for your own task!

As you see, the icon /help/img/idea/2017.2/run.png appears in the left gutter. This action is required ro run the exercise code. Before we explain this action in detail, let’s create answer placeholders first.

Creating answer placeholders

Now that we have the answer, we need to define the question, i.e. what the student has to actually do to get to that answer. PyCharm Edu suggests so called answer placeholder — frames, that will replace some parts of your original exercise code, where the students will have to write their solutions.

These answer placeholders are created easily:

  1. Select a fragment of your exercise code you’d like to replace with some text. In our case, these are the fragments PyCharm.png and io.imread.
  2. Right-click selection, and on the context menu, choose Add answer placeholder:
    /help/img/idea/2017.2/pe_add_answer_placeholder.png
    PyCharm Edu shows the Add Answer Placeholder dialog box.
  3. Use this dialog box to specify the text that will replace the selected fragment in the students’ project. If you want to show a prompt to your students, or a theoretical help for the specific answer placeholders, If you want to show a prompt to your students, or a theoretical help for the specific answer placeholder, just type the hint text. If you want to add more hints, click /help/img/idea/2017.2/new.png:
    /help/img/idea/2017.2/pe_add_hint.png
  4. Click OK when ready.

That’s it! The task with a question is ready. If you now open the context menu of the answer placeholder in question, you will notice three more menu items: Edit Answer Placeholder, Delete Answer Placeholder and Delete All Answer Placeholders, which are quite self-explanatory.

Previewing a task

You would probably like to see how your task will be viewed by your students. To do that, right-click the task file in the Project tool window, and choose Course Creator | Show Preview on the context menu. In the example we are working on, right-click the file read_images.py:

/help/img/idea/2017.2/pe_preview_task.png

PyCharm Edu immediately opens in the editor the file read_images.py, as it will be seen by the students:

/help/img/idea/2017.2/pe_preview_task1.png

Note that actually the file read_images.py is temporary. It does not appear in the Project view of the Project tool window. As soon as you close this file, it just vanishes.

Executing your exercise code

Just to make sure that everything has been done correctly, you’d probably need to run your exercise code and check that it works properly and solves the task you’ve created.

So, click /help/img/idea/2017.2/run.png in the left gutter. It is the same as if you run your program with the default run/debug configuration.

After clicking /help/img/idea/2017.2/run.png, PyCharm Edu shows the expected result - console with the program output.

Writing tests for a task

The fragments of the exercise code which you replace with answer placeholders are not intended to verify the student’s input. The actual checks are accomplished by the tests that should be placed in the files tests.py, available for each task. These tests help you make sure that the students have completed your task in the way you've specified.

Testing basics

  • All tests for a task should be written in the file tests.py, located under each task in the Project view.
  • A test file tests.py is created automatically, when you create a task. Such file already has some predefined common tests. Modify this file by adding your custom tests to check the students’ solutions.
  • tests.py for a task is launched in the background when a student clicks /help/img/idea/2017.2/check_task.png.
  • You can write your custom tests using PyCharm Edu testing framework. The file test_helper.py, located inside each course project, contains useful functions, which you can use to write your own custom tests. Let’s explore some of these functions.
    • First, you have to make use of the functions failed() and passed(), which print test results in a legible and parsable format. You can pass a string to the function failed() - this string will be shown as an error message to a student who failed to execute a task properly.
    • Second, as mentioned earlier, a typical test is created automatically. It contains calls to the base tests run_common_tests. These common tests make sure that a file does not contain syntactical errors, is not empty, that a user did not just delete the contents of a task window, but changed something.
    • test_helper.py contains a handy function get_answer_placeholders() that returns a list of answer placeholders filled in by a student. Try to access the first answer placeholder PyCharm.png.

      To do that, write the following code in the file tests.py:

      placeholders = get_answer_placeholders() placeholder = placeholders[1]

      Rather simple, isn’t it?

  • Explore the file test_helper.py for the other useful functions.

Writing a test

Open a file tests.py for editing (select this file in the Project tool window, and press F4). The following code opens in the editor:

from test_helper import run_common_tests, failed, passed, get_answer_placeholders def test_answer_placeholders(): placeholders = get_answer_placeholders() placeholder = placeholders[0] if placeholder == "": # TODO: your condition here passed() else: failed() if __name__ == '__main__': run_common_tests() # test_answer_placeholders() # TODO: uncomment test call

Then change this file as required. For example, the test file checking the first task window will look like the following:

from test_helper import run_common_tests, failed, passed, get_answer_placeholders from test_helper import import_task_file def test_answer_placeholders(): placeholders = get_answer_placeholders() placeholder = placeholders[1] if placeholder == "io.imread": passed() else: failed("Try to use imread() function from io module") task_file = import_task_file() if task_file.image_name == "PyCharm.png": passed() else: failed("PyCharm logo filename is incorrect") if __name__ == '__main__': run_common_tests() test_answer_placeholders()

Check your tests and exercise code

OK, let's try to execute exercise code and tests for our example. To run the exercise code, open the file read_images.py for editing (F4), and in the Task Description tool window click the button /help/img/idea/2017.2/check_task.png. Results show as the popup (Congrats or Failed) above the button, and in the Run tool window.

This action allows seeing run results as the students see them.

To run tests for read_images.py, click /help/img/idea/2017.2/run.png in the left gutter of the file tests.py. PyCharm Edu shows the test output in the Run tool window:

/help/img/idea/2017.2/pe_test_result.png

All tests passed, because our exercise code was a correct solution.

Next, change PyCharm.png to something else in your exercise code read_images.py and try to re-run the tests. This time the result is different.

/help/img/idea/2017.2/pe_test_result_failed.png

Wrapping everything

Creating the second task

Next, let's create the other task in the lesson Basic. To do that, click this lesson in the Project Tool Window, and press Alt+Insert.

Choose the option Task, specify the task name (here it is Write Images), and click OK.

/help/img/idea/2017.2/pe_create_task.png

The new task is created under the lesson Basic. Note that a task consists of the following files:

  • task.py
  • tests.py

The task’s files immediately open in the editor. However, before proceeding, let's rename the file task.py. To do that, click this file in the Project tool window, press Shift+F6 and specify the new name (here write_image.py) .

All the task files already have some pre-defined contents. However, we have to edit them in order to produce something meaningful.

Writing contents of the second task

You have already created the second task. Now specify the actual text of the task in the Task Description tool window, its exercise code in the file write_image.py, and its test in the file tests.py.

  1. Enter the following text in the Task Description tool window:
    <html> Load picture with coffee and save it to the proper file. </html>
  2. Open the file write_image.py for editing and enter the following code:
    from skimage import io from skimage import data coffee = data.coffee() filename = "coffee.png" io.imsave(filename, coffee)
  3. In the file write_image.py, create the task window. To do that, select the piece of code filename, coffee and choose Add Answer Placeholder from the context menu of the selection.
  4. In the Add Answer Placeholder dialog, write the text that will be shown to the students, and the hint:
    /help/img/idea/2017.2/pe_task_window.png
  5. Open for editing the file tests.py. It already contains some predefined code. Change this code as follows:
    import filecmp import os import sys from test_helper import run_common_tests, failed, passed def match_pictures(): answer_path = os.path.join(sys.argv[1], "coffee-answer.png") if filecmp.cmp("coffee.png", answer_path): passed() else: failed("Hey! It's a mistake!") if __name__ == '__main__': run_common_tests() match_pictures()
  6. Add the image file coffee-answer.png to the root of the project.
  7. Run the test. To do that, click /help/img/idea/2017.2/run.png in the left gutter of the task file write_image.py.

Creating another lesson and the nested tasks

Next, let's create another lesson. To do that, in the Project Tool Window, press Alt+Insert and choose the option Lesson:

/help/img/idea/2017.2/pe_create_lesson.png

In the Create New Lesson dialog box, specify the name of the new lesson (in this case, the name is Advanced).

Next, to prepare for running, do the following:

  1. In the Project Tool Window, select the lesson Advanced, and press Alt+Insert again to create a new task named Let's swirl PyCharm.
  2. Rename the file task.py to swirl_pycharm.py (Shift+F6), open it for editing (F4) and type the following code:
    from skimage import io from skimage.transform import swirl image_name = "PyCharm.png" img = io.imread(image_name) swirled = swirl(img, rotation=0, strength=20, radius=120, order=2) io.imsave("swirled.png", swirled) swirled2 = swirl(img, rotation=0, strength=20, radius=120, order=2) io.imsave("swirled2.png", swirled2)

    This code reads the file PyCharm.png, and then creates two "swirled" files swirled.png and swirled2.png.

  3. Then, add the answer placeholder to the code rotation=0, strength=20, radius=120, order=2 of the statement swirled2 = swirl(img, rotation=0, strength=20, radius=120, order=2) with the text “Сhoose your parameters”.
  4. Add the image PyCharm.png to the root of the task Let's swirl PyCharm.
  5. Add new contents to the file tests.py:
    from test_helper import run_common_tests, failed, passed, get_answer_placeholders def test_answer_placeholders(): placeholders = get_answer_placeholders() placeholder = placeholders[0] if "=" in placeholder: passed() else: failed("play") if __name__ == '__main__': run_common_tests() test_answer_placeholders()
  6. Write the task text in the Task Description tool window (/help/img/idea/2017.2/edit1.png):
    <html> Use <b>imread</b> function to load PyCharm logo and play with it a little bit. </br> Find more information <a href="http://scikit-image.org/docs/dev/auto_examples/plot_swirl.html">here</a> </html>

Finally, run the file swirl_pycharm.py and its test (click /help/img/idea/2017.2/run.png in the left gutter).

This time, when you look at the Project tool window, you see the two files: swirled.png and swirled2.png.

These files appear as the result of executing the code in the file swirl_pycharm.py.

And to round up, create one more task under the lesson Advanced. Let it be the task Overview with the following files:

  • Overview.txt with the following text:
    Hope you enjoyed our tutorial! Create your own courses and have fun!
  • tests.py

Creating the course archive to share it with students

OK, your first course is ready. What’s next?

  1. Right-click anywhere in the Project tool window and choose Course Creator | Generate Course Archive:
    /help/img/idea/2017.2/pe_create_archive.png
  2. Type the archive name and location (or accept defaults) in the dialog box that opens:
    /help/img/idea/2017.2/create_course_archive.png

    After clicking OK, PyCharm Edu notifies that the course has been created successfully:

    /help/img/idea/2017.2/pe_course_archive_success.png

    View the archive file PyCharmTutorialCourse.zip with the actual course archive in the Project tool window:

    /help/img/idea/2017.2/pe_course_archive_in Project_tool_window.png

    Students can use PyCharmTutorialCourse.zip to go through your course!

Quick creation of educational course

PyCharm Edu provides an action that allows you to quickly create a students’ course from the current educators’ course. This action is called Preview Course, and it’s invoked from the Course Creator node:

/help/img/idea/2017.2/pe_preview_course.png

As a result, the New Project dialog shows the Educational project type only, with the current course as the basis:

/help/img/idea/2017.2/pe_preview_course_project.png

From the student’s viewpoint...

To make sure that everything has been done properly, create a new educational project (File | New Project… -> Educational).

When creating such a project, point to the course you’ve produced. To do that, click /help/img/idea/2017.2/cogwheel_framed.png, then choose Add local and point to the archive in question:

/help/img/idea/2017.2/pe_choose_course_archive.png

Click Create. The new educational project opens. Note that the texts of your tasks now show in the Task Description tool window, and the files *.py contain the task windows hiding the correct solution.

The rest is left to the students. They have to fill in the task windows to fulfil the task, leaving you with the job to check whether they were right in their guesses.

Publishing a course to Stepik

We encourage you to make your course available publicly for other educators and students. In order to publish it to Stepik, you need to create you own account.

Next, right-click the Project tool window and on the context menu choose Course Creator | Upload Course to Stepik.PyCharm Edu shows the login dialog:

/help/img/idea/2017.2/pe_login_to_stepic.png

PyCharm Edu saves these credentials in the Education page of the Settings/Preferences dialog.

Note that your course is private by default. To make it public, you have to clear the check box Private course (invite learners by private invitation link) of the course settings.

That's it, folks... Congrats! You've created you first educational course.

Last modified: 26 October 2017

See Also

External Links: