Splitting a Program Into Pieces

People use these three words as if they mean the same thing, and mixing them up makes documentation harder to read than it needs to be. A module is one file — shapes.py is a module. A package is a folder of modules that Python can import as a single unit, which the next section shows. A library is neither of those specifically — it is the general word for a chunk of published, reusable code, and it might be shipped as a single module, a package, or several packages together.

requests, the package almost every Python program that talks to the internet ends up importing, is a library. So is the standard library itself — the collection of modules that ship with Python before you install anything, like json or pathlib. Calling json “a library” and calling it “a module” are both correct, at different levels of description; calling your own single shapes.py file “a package” is not, because nothing about it is a folder.

Any .py file can be imported by another. Put the shared logic in its own file, and every other file that needs it imports it by name — the file name becomes the module name, minus the .py.

def area_of_circle(radius):    return 3.14159 * radius * radius

import shapes print(shapes.area_of_circle(4))

Nothing about shapes.py changed to make it importable — every .py file already is. What changed is that main.py now reaches into it by name instead of duplicating area_of_circle inside itself, which is the entire point of splitting a program up in the first place.

The first time a module is imported anywhere in a running program, Python actually runs the entire file top to bottom, once, then keeps the result cached. Every later import shapes, anywhere else in the program, reuses that same cached result rather than running the file again.

A module's top level runs the moment anything imports it — the previous section already showed that. That becomes a problem the instant a file is meant to work two ways: as a script you run directly, and as a module something else imports. Code meant to run only in the first case needs a way to say so.

def fetch_forecast(city):    return f"Sunny in {city}" print(fetch_forecast("London"))

Import this from anywhere else in the program, and that print runs immediately, every time — reporting London's forecast into output that has nothing to do with weather, the moment the import line executes.

def fetch_forecast(city):    return f"Sunny in {city}" if __name__ == "__main__":    print(fetch_forecast("London"))

Try itAdd print(__name__) as the last line and run it: here, the file is run directly.

__name__ is a variable Python sets automatically in every module. Run the file directly and Python sets it to the string "__main__". Import the same file from somewhere else and Python sets it to the module's own name instead — "weather", not "__main__" — so the condition is false, and the print never runs. Nothing magic is happening here; it is an ordinary if statement checking an ordinary variable that happens to be set differently depending on how the file started.

A regular package is a folder of modules with one marker file, __init__.py, that tells Python to treat the folder as a single importable unit rather than an ordinary directory. The file can be completely empty; its presence is the signal. Python 3 can also import a folder without one, as a namespace package, but that exists for splitting one package across several locations. For your own packages, include the file.

$ geometry/    __init__.py    shapes.py    angles.py

From outside the folder, from geometry import shapes reaches into it the same way import shapes reached into a single file — the folder structure is invisible to the code that uses it.

import shapes works because Python searches a specific list of locations, in order, called sys.path: the folder the running script lives in first, then the standard library, then installed third-party packages. That is also why a typo like import shpaes fails immediately with ModuleNotFoundError instead of finding something similar — the search is exact, not fuzzy.

import mathimport random print(math.sqrt(16))print(random.randint(1, 6))

Try itRun it a few times, then misspell one of the imports and run it again.

Inside a package, an import can be written two ways. An absolute import spells out the full path from the top of the package, the same way outside code would; a relative import uses dots to mean “from here” instead.

# absolute — same path anyone outside the package would writefrom geometry.shapes import area_of_circle # relative — "from the module next to me in this same package"from .shapes import area_of_circle

Relative imports save typing inside a large package and keep working if the whole package is ever renamed or moved, since the dot just means “my neighbour” rather than repeating the package's name. They only work inside a package, though — a plain script run directly cannot use one, because a single file run on its own has no package to be relative to.