RobotnixAcademy

Unit 11 · lesson

Build a Modular System Toolkit

Core path: 35 minutes

A Python project can become hard to reason about long before it becomes "large." One file that handles menus, storage, search, IDs, and networking already has several responsibilities tangled together.

This lesson separates those responsibilities and isolates one third-party dependency inside the project environment.

Create the environment before installing packages

From the project root:

python -m venv .venv

Select or activate that environment using the method supported by your workspace.

Ignore environment artifacts:

.venv/
__pycache__/
*.pyc

The .venv directory is replaceable tooling state. Your source files are the project.

Identify boundaries before moving code

Your starting application contains several jobs:

JSON storage
system creation
random ID generation
search logic
console menus
output formatting

Do not start cutting and pasting yet.

Decide which responsibilities belong together.

A reasonable result is:

system-toolkit/
├── main.py
├── storage.py
├── systems.py
├── display.py
├── requirements.txt
├── README.md
└── .gitignore

Move storage into storage.py

Put functions such as:

load_systems()
save_systems()

in storage.py.

Import only what that module actually needs.

Move domain behavior into systems.py

Move functions such as:

generate_system_id()
create_system()
search_system()

into systems.py.

The file name should tell another developer roughly what responsibility lives there.

Move presentation into display.py

Move:

show_menu()
display_system()

into display.py.

Now main.py should look more like coordination than a warehouse for every function in the program.

Install one third-party dependency deliberately

Inside the selected environment:

python -m pip install requests

Verify the interpreter can import it:

python -c "import requests; print(requests.__version__)"

Record the installed requirement in requirements.txt:

requests

The important distinction is:

source code says what package the program imports
requirements.txt records what another environment needs
.venv contains one local installation of those packages

Do not commit .venv.

Prove the boundary

Record:

  • the command used to create .venv;
  • the Python interpreter selected for the project;
  • evidence that this interpreter imports requests;
  • git status showing .venv/ is ignored; and
  • the contents of requirements.txt.

If your workspace manages environments differently, document the actual interpreter-selection mechanism. The target is isolation, not memorizing one activation ritual.

Commit the architecture and dependency setup separately

Inspect the diffs before each commit.

A module refactor and dependency setup are different changes. Keeping them separate makes the history easier to inspect and recover.

Success evidence

Another developer should be able to answer:

  • what each module owns;
  • which file starts the program;
  • which third-party package is required;
  • how to recreate the environment;
  • why .venv is ignored; and
  • why deleting .venv does not delete the source code.

A modular project is not "more files." It is a project whose boundaries reduce the amount of code you have to hold in your head at one time.