11.5. Creating Modules

Up until now, we have imported modules that are already part of the Python libraries. Now let’s look at how to define our own modules and save them in a form we can use in other programs.

11.5.1. Create a New Python File

The first step in making a module is to decide which values and functions belong in that module. These should all perform similar tasks and/or be related to each other in some way.

For example, let’s assume we want to create a module called turtle_shapes. Functions like draw_square, draw_polygon, and draw_sprite would be good choices to put in the module, but something like calculate_average_grade definitely does NOT belong.

The next step is to open a new file in our code editor and give it a name that:

1. begins with a letter and contains only lowercase letters,

2. is as short as possible but still descriptive,

3. separates words with an underscore _,

4. ends with the extension .py (for example, turtle_shapes.py).

Note

The .py extension tells a code editor that the contents of the file follow the Python programming syntax.

Finally, we add the functions and values we want in the module. We code these just like any other program, with import statements first, then function definitions, then variable assignments.

That’s pretty much it. Once we save the file, we can use the syntax we learned to import the entire module or specific parts of it into another program:

import turtle_shapes
from turtle_shapes import draw_polygon

Note that we do NOT need to include the .py extension when we import the module.

Let’s build a module to practice this process.

11.5.2. Setting Turtle Properties

You probably noticed that every time we use a turtle in an example or exercise, we include a set of statements that define properties for that turtle:

Example

Count the number of “prep” steps we need before our turtle draws its first line:

import turtle

bob = turtle.Turtle()
bob.color('blue')
bob.shape('turtle')
bob.pensize(3)
bob.speed(8)

bob.circle(75)

Line 3 creates the new turtle object, called bob. Lines 4 - 7 set the properties, and line 9 finally draws something on the screen.

It takes one line of code to set each of the properties for a turtle. If we need to define multiple turtles, this gets tedious really fast.

We can help ourselves by moving the setup code into a pair of functions, and then calling those functions for each new turtle:

Example

By including some default values, we can call the create_new_turtle function with no arguments, with values for some of the properties, or with arguments for each property.

import turtle

def create_new_turtle(t_color='black', t_shape='turtle', t_pen=3, t_speed=8):
   turtle_name = turtle.Turtle()
   set_turtle_properties(turtle_name, t_color, t_shape, t_pen, t_speed)
   return turtle_name

def set_turtle_properties(t_name, t_color='black', t_shape='turtle', t_pen=3, t_speed=8):
   t_name.color(t_color)
   t_name.shape(t_shape)
   t_name.pensize(t_pen)
   t_name.speed(t_speed)

bob = create_new_turtle()
lin = create_new_turtle('purple', 'square')

This is better, since it reduces the repetition in the program. However, if we want to use this shortcut in ALL of our turtle programs, we need to create a module to hold the code.

11.5.2.1. Create the turtle_prep Module

In the editor below, notice that there are two file tabs open—main.py and turtle_prep.py. The first file contains the code that directs what gets drawn on the screen. The second file is currently empty, but it will eventually hold all of the setup steps to get each turtle ready.

Follow these instructions to create the turtle_prep module:

1. Run the program as-is to see how it works.

2. Click on the turtle_prep.py tab to access the editor for that file. (The workspace should be empty).

3. Return to main.py. REMOVE lines 1 - 12 from main.py and paste them into turtle_prep.py.

4. In main.py, add the statement import turtle_prep on line 1.

5. Use dot notation to update bob = create_new_turtle() to bob = turtle_prep.create_new_turtle(). Do the same for lin.

6. Click Run to verify that the program still works.

7. Change the arguments in the create_new_turtle function calls to see how that affects the drawing.

8. In main.py, call the set_turtle_properties function to change the properties of the turtles after they draw the circles. Add a new line or shape to check your work.

Cool, we now have a set of code that we can pull into future turtle projects!

11.5.3. File Locations

One important thing to note is that when we import a module into a program, Python needs to know exactly where to find that file.

When Python reads import module_name, it first checks to see if the module is one of the built-in Python files. Python knows exactly where these modules are stored on our device, so the import occurs easily.

If a built-in module is not found, Python looks in the current directory, which is the folder that holds the main program. If it finds a module_name.py file, it imports that into the program.

If the module is NOT in the same folder, Python expands its search to a larger list of directories. This is a more complicated process, and it requires the programmer to either save the new module in one of these directories or give Python a detailed path to follow.

We will learn more about navigating different paths much later in the course. For now, we will keep things simple by saving new modules in the same location as main.py.

11.5.4. Try It!

Let’s add another module to our turtle program.

In the editor above, click on the New File button to the right of the file tabs. Name the new file turtle_shapes.py.

New File button.

1. Open the turtle_shapes.py tab and enter import turtle on line 1.

2. Paste in copies of the draw_square, draw_polygon, and draw_sprite functions you created in the last chapter. Be sure to include only the function code and NOT any turtle drawing commands.

3. In main.py, import the turtle_shapes module.

4. Instead of the circle, have bob draw a different shape. Use dot notation to call one of the functions from turtle_shapes. Make sure you include the required arguments in the proper order.