Getting Started for EducatorsHow to create a course with PyCharm Edu
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.
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:
Creating a course
You can create a project in two possible ways: either from the Welcome screen, or by choosing File | 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.
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
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.pyis a library of auxiliary functions, which help you write custom checks and tests for your tasks. This file is grey.
- The folder lesson1 denoted with the icon lesson . This folder contains two stub files:
- 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:
- these actions are available to the students.
- the action Refresh Task() is disabled for the educators.
- 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.
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 click OK.
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 press Shift+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:
<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
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:
- Select a fragment of your exercise code you'd like to replace with some text. In our
case, these are the
- Right-click selection, and on the context menu, choose Add answer placeholder.
- In the Add Answer Placeholder dialog box, specify the text that will replace the selected fragment in the student's project:
- Click OK when ready.
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.
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
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
available for each task. These tests help you make sure that the students have completed
your task in the way
- All tests for a task should be written in the file
tests.py, located under each task.
- A test file
tests.pyis 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.pyfor a task is launched in the background when a student clicks .
- 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
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.pycontains 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
placeholders = get_answer_placeholders() placeholder = placeholdersRather simple, isn't it?
- First, you have to make use of the functions
- Explore the file
test_helper.pyfor 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
from test_helper import run_common_tests, failed, passed, get_answer_placeholders () def test_answer_placeholders(): placeholders = get_answer_placeholders() placeholder = placeholders 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 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
and in the Task Description tool window click the button
. 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
in the left gutter of the file
shows the test output in the Run tool window:
All tests passed, because our exercise code was a correct solution.
PyCharm.png to something else in your exercise
read_images.answer and try to re-run the tests.
This time the result is different:
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:
The new task is created under the lesson Basic. Note that a task consists of following files:
The task's files immediately open in the editor. However, before proceeding, let's rename
task.py. To do that, click this file in the Project
tool window, press Shift+F6 and specify the new name
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
Enter the following text in the Task Description tool window :
Load picture with coffee and save it to the proper file.
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 code
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, "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
7. Run the test. To do that, right-click in the gutter
of the task file
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
(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
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
from test_helper import run_common_tests, failed, passed, get_answer_placeholders def test_answer_placeholders(): placeholders = get_answer_placeholders() placeholder = placeholders 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
swirled2.png. These files
appear as the result of executing the code in the file
And to round up, create one more task under the lesson Advanced. Let it be the task Overview with the following files:
Overview.answer.txtwith the following text:
Hope you enjoyed our tutorial! Create your own courses and have fun!
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 Project tool 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/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.