Writing A Modular Program In Python

Why your Python scripts quietly become unmaintainable

If you've ever had to add a feature to a five-year-old script and spent three hours finding where the logic actually lived, you already know what modularity solves. It's not about aesthetics. It's about being able to change one piece of behavior without breaking something else you didn't touch. In practice, the line between "fine for now" and "rewrite everything" usually crosses somewhere around 800 to 1,000 lines in a single file. Not because Python breaks, but because your brain does. When I started working on a telemetry pipeline that grew from a 200-line script into something with real production dependencies, the first thing that broke wasn't functionality. It was the import graph. Three modules ended up importing each other in a cycle that only surfaced during deployment, not locally. The stack trace pointed at something completely unrelated to the actual problem. That's when I stopped treating modularity as an afterthought and started designing the package structure before writing the business logic.

Writing A Modular Program In Python

The basic unit is a single .py file. You put related functions and classes in it, you manage imports at the top, and you use if __name__ == "__main__": to make that file both a reusable module and a standalone script. That pattern alone covers about 70 percent of what people mean when they talk about modular code. The rest is organization and dependency hygiene. Most tutorials show package structures that work in theory and fall apart in practice. The layout that has survived multiple refactorings on my end looks like this: The src/ layout matters more than people admit. Without it, Python can import from the project root directly, which means your tests may pass locally but fail in CI because the installed package and the source tree diverge. Installing with pip install -e . after setting up a pyproject.toml locksthe running code to the actual package, not the source directory. That single change eliminated an entire class of flaky tests for me.

Your __init__.py files shouldn't be empty by default. They define what from mypackage import ... actually exposes. If your __init__.py imports everything from every submodule, you've created a hidden coupling. Every import of mypackage now loads every submodule, which adds up quickly. I keep __init__.py minimal and let consumers import submodules directly when they need them.

The import pattern that saves you

Here's a realistic example of a properly structured module: The from __future__ import annotations line is worth keeping even if you don't currently use forward references. It defers evaluation of annotations, which prevents errors when modules reference each other during class definition. I've encountered circular import issues that this single line resolved without any architectural changes. Each module should have a single responsibility. core.py handles the main logic. utils.py contains helpers that don't belong to any specific domain. cli.py handles argument parsing and orchestration. If a function could reasonably live in another module, it probably belongs there. That's not dogma, it's just how you keep the import graph from becoming a spiderweb.

Handling circular imports

Circular imports are the most common structural problem, and they're almost always a sign that the module boundaries are wrong. The standard workaround—moving the import inside the function—is a bandage. It works but it makes the dependency graph opaque. A cleaner approach is to extract the shared dependency into its own module. In that telemetry project I mentioned, module A imported B and module B imported A. Neither could load first. Instead of moving imports around, I created a third module, shared.py, that contained the data types and constants both modules needed. Once A and B both imported from shared instead of from each other, the cycle broke. The import order became deterministic and the error disappeared permanently.

Testing structure

Modular code without tests is just code that's harder to debug. The test structure should mirror the source structure. Each module gets a corresponding test file. test_core.py tests core.py. You use pytest with fixtures in conftest.py files rather than global helper functions. Fixtures scoped to modules or functions keep your tests isolated and your setup code DRY. This is more verbose than putting test helpers in a single file, but it scales. When you have 50 test files and three of them need a database fixture, you want to know exactly which conftest.py provides it without searching through a monolithic helpers file. Splitting code into modules doesn't reduce complexity. It distributes it. A well-organized package with poor design is still hard to understand. Modularity makes the structure visible, but it doesn't make the structure good. You still need to think about what belongs where and why.

There's also a point of diminishing returns. A project with two or three files doesn't need a full package structure. The overhead of maintaining __init__.py files, pyproject.toml, namespace packages, and import routing outweighs the benefits at small scale. I stop worrying about package structure around the three-module mark and build it out progressively from there. Premature packaging creates the same problems it's meant to solve, just with extra files. Dependency management is another area where modularity can make things worse if you're not careful. Every public function in every module becomes a potential API surface. Breaking changes propagate. This is why I keep module interfaces tight and use private names (leading underscore) for anything that's internal to the module. Python doesn't enforce privacy, but it does signal intent, and that signal matters when someone two weeks from now is trying to figure out whether a function is stable.

Tooling that actually helps

ruff for linting and formatting replaces four or five individual tools. It runs in milliseconds, catches import ordering issues, and formats consistently. mypy&#x;for static type checking catches module-level import errors that runtime doesn't surface until you actually execute the code path. pytest with -x for stopping on first failure and --tb=short keeps test output readable. These three tools together cover the structural quality gates that matter most. For larger projects, uv is faster than pip and poetry combined for dependency resolution. The project bootstraps in seconds instead of minutes. If you're managing a package with many interdependent subpackages, this speed difference is noticeable every single time you install or update. The practical takeaway is straightforward. Structure your code so that each module has one reason to change, keep imports explicit and acyclic, test at the module level, and don't over-engineer the structure for small projects. The rest is just practice.