Your Own Modules and Packages

Any .py file is a module another file can import, so a growing program is split into files by job, a folder of them with __init__.py becomes a package, and the __name__ check keeps a file's own test lines from running when it's imported.

Apprentice · Python · Updated

By

After this lesson you can

  • Split a program into modules of your own and a package, and bring them into another file with import or from … import
  • Guard a file's own code with if __name__ == "__main__" so it runs when the file is run, not when it is imported

Key takeaways

  • Any .py file is a module. A file in the same folder brings it in with import scores (the file name without .py) or from scores import add_points.
  • Importing a module runs it from top to bottom, so lines at its bottom that print or test run in every program that imports it.
  • Python sets name to "main" in the file you run, and to the module's name in a file being imported. if name == "main" uses that to keep a file's own code to itself.
  • A package is a folder of modules with an init.py file, and from gamenight.scores import add_points reaches a module inside it.

A program starts as one file and grows. At 50 lines it's fine; at 400 you scroll up and down hunting for a function, and when a second script needs that function, you copy it, and the two copies slowly drift apart. Splitting the code into files, each with one job, fixes both. It's also how every project you'll clone is organized, and how a test file reaches the code it tests.

The example is Game Night: a group of friends who play board games on Fridays, and a small program that keeps their scores.

A second file is a module

Game night's score-keeping functions are wanted by more than one script, so they move out of the big file into one of their own, scores.py, which holds those functions and nothing else:

def add_points(totals, player, points):
    """Add points to a player's total. A new player starts at 0."""
    totals[player] = totals.get(player, 0) + points


def show(totals):
    """Print each player's total, one line each."""
    for player, points in totals.items():
        print(f"{player}: {points}")

A file like this is a module: a file of Python code that another file can use. You don't need anything special to make one: every .py file is a module. In the same folder, main.py brings it in with import, followed by the file's name without .py, and calls each function through the module's name and a dot:

import scores

totals = {}
scores.add_points(totals, "Ana", 12)
scores.add_points(totals, "Ben", 9)
scores.add_points(totals, "Ana", 5)
scores.show(totals)

Running python main.py (python3 on a Mac outside a virtual environment) prints:

Ana: 17
Ben: 9

scores.add_points is read "scores dot add points": the add_points that lives in scores. To write the names on their own instead, bring them in by name with from scores import add_points, show, and then call add_points(totals, "Ana", 12).

Python looks for scores.py in the folder of the file you run, then among its own modules and the packages you've installed. A typo, such as import score, stops with ModuleNotFoundError: No module named 'score'. And never name your file after a module Python already has, such as random.py: Python finds your file first, and every import random in that folder gets yours instead.

Importing runs the file

While writing scores.py, it's natural to try it out with a few lines at the bottom:

def add_points(totals, player, points):
    """Add points to a player's total. A new player starts at 0."""
    totals[player] = totals.get(player, 0) + points


def show(totals):
    """Print each player's total, one line each."""
    for player, points in totals.items():
        print(f"{player}: {points}")


# Trying the module out while writing it
practice = {}
add_points(practice, "Test", 3)
show(practice)
Test: 3

Now run main.py, which uses from scores import add_points, show and adds Ana's 12 and Ben's 9, and a stranger turns up:

Test: 3
Ana: 12
Ben: 9

Importing a module runs it from top to bottom, once, the first time it's imported. The def lines define the functions, which is what main.py wanted; the try-out lines at the bottom run too, which it didn't.

The file being run: `__name__`

Python gives every module a variable called __name__ (read "dunder name", short for "double underscore name"). In the file you run, it's the text "__main__". In a file being imported, it's the module's name. Two one-line files show it: scores.py holds print("scores.py says its __name__ is", __name__), and main.py holds import scores, then a line that prints its own __name__:

scores.py says its __name__ is scores
main.py says its __name__ is __main__

Run scores.py by itself, and it says __main__. So a file can ask, "am I the one being run?" Put the try-out lines under that question, indented:

def add_points(totals, player, points):
    """Add points to a player's total. A new player starts at 0."""
    totals[player] = totals.get(player, 0) + points


def show(totals):
    """Print each player's total, one line each."""
    for player, points in totals.items():
        print(f"{player}: {points}")


if __name__ == "__main__":
    practice = {}
    add_points(practice, "Test", 3)
    show(practice)
Test: 3

if __name__ == "__main__": reads "if this file is the one being run". python scores.py still prints Test: 3, and python main.py prints only Ana's and Ben's scores. You'll see this line at the bottom of many Python files.

A package: a folder of modules

When the modules pile up, put them in a folder. A package is a folder of modules with a file named __init__.py (read "dunder init dot py") inside, which tells Python the folder is a package. It can be empty.

game-night/
├── main.py
└── gamenight/
    ├── __init__.py
    ├── dice.py
    └── scores.py

main.py reaches inside the package with a dot between the folder and the module, either way:

from gamenight import dice
from gamenight.scores import add_points, show

totals = {}
add_points(totals, "Cleo", dice.total([6, 4]))
show(totals)
Cleo: 10

Here dice.py holds one function, total(rolls), which returns sum(rolls). Run programs from the folder that holds the package (game-night/), so Python finds gamenight. A package can also be run as a program: python -m gamenight runs the file gamenight/__main__.py inside it, if the package has one.

Check yourself

2 questions to try on the lesson page.

So what

Small files with one job each are easier to find your way around, to reuse without copying, and to test, which is why every real Python project, and every library you'll install, is a package of modules.

Key terms

Related