Writing your own module

Understanding Writing your own module

A module is nothing more than a .py file, and the first time something imports it Python executes that file top to bottom, then keeps every name the file created as an attribute of a module object. That single fact drives every design decision: the top level of your file is running code, not a declaration section. Statements like def, class, and CONSTANT = 5 are cheap because they just bind names, while opening a file or querying a network at the top level happens as a side effect of the word import.

Because the file is a namespace you are designing for someone else, spend the first line on a module docstring: it lands in module.__doc__ and is the header help(module) shows. Inside, promote a small set of functions and constants as the public surface and prefix everything else with a single underscore, which is the universal Python signal for "internal, may change". Adding __all__ = [...] names that public surface explicitly, which controls what from mymodule import * pulls in, though it is documentation rather than enforcement since attribute access still reaches every name.

The filename is the import name, so it must be a valid identifier: money_utils.py imports fine, money-utils.py cannot be imported with the import statement at all, and a file named json.py sitting next to your script will be found before the standard library's json. Since the module object is cached after the first import, any dict, list, or open connection created at module level becomes a process-wide singleton shared by every importer, which is useful for a registry and a trap for anything you expected to be per-caller.

from pathlib import Path
import sys

# Stands in for creating tempconv.py in your editor.
Path("tempconv.py").write_text('''"""Convert between temperature scales."""

__all__ = ["c_to_f", "f_to_c"]

ABSOLUTE_ZERO_C = -273.15


def c_to_f(celsius):
    """Return degrees Celsius converted to Fahrenheit."""
    if celsius < ABSOLUTE_ZERO_C:
        raise ValueError("below absolute zero")
    return celsius * 9 / 5 + 32


def f_to_c(fahrenheit):
    """Return degrees Fahrenheit converted to Celsius."""
    return (fahrenheit - 32) * 5 / 9
''')

sys.path.insert(0, ".")   # the folder holding the file must be importable
import tempconv

print(tempconv.c_to_f(100))
print(tempconv.__doc__)
print(tempconv.c_to_f.__doc__)
print(tempconv.__all__)
print(tempconv.ABSOLUTE_ZERO_C)

Worked examples

from pathlib import Path
import sys

Path("loader.py").write_text('''print("loader body running")

DATA = None


def get_data():
    """Build the table on first use instead of at import time."""
    global DATA
    if DATA is None:
        print("building table")
        DATA = {n: n * n for n in range(4)}
    return DATA
''')

sys.path.insert(0, ".")
import loader
import loader          # cached: the body does not run again

print(loader.get_data())
print(loader.get_data())

from pathlib import Path
import sys

Path("registry.py").write_text('''_handlers = {}


def register(name, func):
    _handlers[name] = func


def names():
    return sorted(_handlers)
''')

sys.path.insert(0, ".")
import registry
from registry import names

registry.register("upper", str.upper)
print(names())
print(registry._handlers is sys.modules["registry"]._handlers)

from pathlib import Path
import sys

Path("geometry.py").write_text('''"""Area helpers."""

__all__ = ["circle_area"]

PI = 3.14159


def circle_area(r):
    return PI * r * r


def _validate(r):
    return r >= 0
''')

sys.path.insert(0, ".")
ns = {}
exec("from geometry import *", ns)
print(sorted(k for k in ns if not k.startswith("__")))

import geometry
print(geometry.PI)
print(geometry._validate(-1))

Important notes

Common mistakes

Try it yourself