Pycharm Edu 自带入门教程：Getting Started for Educators

On this page:

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

• A course is just a project of a special type. It consists of lessons.
• A lesson is a directory where the task files are stored. Each lesson can contain several tasks.
• 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, and 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.
• 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.
• If the students are not sure of themselves, they can view hints. The hints are also created by your goodself. In this guide you’ll find a detailed explanation of each action.

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 help section Configuring Python SDK 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:

• Package numpy.
• Library scikit-image.
• Package scipy.

Creating a course

You can create a project in two possible ways: either from the Welcome screen, or by choosingFile | New Project on the main menu.

In the Select project type dialog, choose the project type Course creation. You are suggested to 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:

The project for the first educational course is ready.

What’s inside this project?

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

There is a single top-level node PyCharmTutorialCourse, denoted with the icon . If you expand it, the nested elements become visible.

1. Under the number 1 (PyCharmTutorialCourse), you see all 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 lesson . 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 allows you to check the task execution ( ), move between tasks (  ), refresh task ( ), view hints ( ), and edit tasks ( ). Note the following:
   1. these actions are available to the students.
   2. the action Refresh Task() 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  in the New Project dialog.

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 clickOK.

Thus, you've performed the Rename refactoring.

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

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:

However, 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:

Writing a task text

Now it's time to write a task description. Go to the Task Description tool window and click . You see that HTML markup appeared:

Select the existing text fragment, and replace it with the following text:

<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 Education under the node Tools of the Settings/Preferences dialog. )

Instead of the existing text, type the following: 
Use <code>imread</code> function to load PyCharm logo and play with it a little bit. 
To see this text as it will be viewed by the students, just release the button .

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 file read_images.py (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  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.
   
3. In the Add Answer Placeholder dialog box, specify the text that will replace the selected fragment in the student's project:
   

   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 plus.

4. Click OK when ready.

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 on the context menu choose Course Creator | Show Preview. In the example we are working on, right-click the file read_images.py:

PyCharm EDU immediately opens a separate window with the task preview, as if it were seen by the students:

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  in the left gutter. It is the same as if you were running your program with the default run/debug configuration.

After clicking , 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.
• 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  .
• You can write your custom tests using PyCharm Edu testing framework. The filetest_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 test function 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 follows:

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")
        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 EXERCISE CODE AND TESTS

OK, let's try to execute code and tests for our example. 
To run tests for read_images.py for editing (F4), and in the Task Description tool window click the button . Results show as the popup (Congrats or Failed) above the button, and in theRun tool window:

This action allows seeing run results as the students see them. To run tests for read_images.py, click  in the left gutter of the file tests.py. PyCharm Edu shows the test output in the Runtool window:

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

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

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 Projecttool window, and press Alt+Insert.

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

The new task is created under the lesson Basic. Note that a task consists of 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 predefined 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 filetests.py.

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 (F4) 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 codefilename, 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:

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, right-click  in the 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 :

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.answer.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 andswirled2.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 ()::

<html>
<br/>
Use <b>imread </b> function to load PyCharm logo and play with it a little bit.
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  in the left gutter).

This time, when you look at the Project tool window, you see the two files swirled.png andswirled2.png. These files appear as the result of executing the code in the fileswirl_pycharm.py.

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

• Overview.answer.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: :

2. Type the archive name and location (or accept defaults) in the dialog box that opens:

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

View the archive file PyCharmTutorialCourse.zip with the actual course archive in the Projecttool window.

Students can use this archive to go through your course!

Quick creation of educational courses

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:

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

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 , then choose Add local and point to the archive in question:

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:

PyCharm Edu saves these credentials in the Educational page of the Settings/Preferencesdialog.

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

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