← First principles STAGE 01 · 30 MIN

From a script to a small tool

Organize your first program so another person can run, inspect, and extend it.

Open in the laboratory ↗

BY THE END, YOU CAN

Separate reusable code from an entry point
Explain imports and module boundaries
Define a reproducible local workflow

A small tool: one entrance, modules by responsibility, and tests that check the core.

01SECTION 1 OF 3

Give the program an entrance

A script (a code file you run directly) becomes a useful tool when its inputs, outputs, and invocation are clear.

Put reusable decisions in functions and keep command-line interaction in a main function, the entry point where running the program starts. The __name__ guard prevents the command-line workflow from running merely because another module imports your code. This is also what makes the functions easier to test.

For a first version of Relay, accept a job name, validate it, process it, and print a clear result. Small, predictable behavior is a solid starting point.

Python

def describe_job(name):
    return f"Queued: {name}"

def main():
    print(describe_job("daily-report"))

if __name__ == "__main__":
    main()

02SECTION 2 OF 3

Organize by responsibility

A module is a Python file with its own namespace (its own set of names, so two modules can both define a function called main).

Split code when a boundary makes responsibilities clearer: queue behavior, input parsing, and storage are plausible early boundaries. Creating many tiny files before the responsibilities are understood adds navigation without clarity. Imports execute module-level statements, so avoid network calls or destructive actions at import time.

Keep configuration separate from the core logic and pass it in explicitly. Someone should be able to inspect how Relay works without discovering hidden setup scattered through unrelated modules.

03SECTION 3 OF 3

Make the first run boring

A reproducible workflow states the supported Python version, how dependencies are installed, and the command that runs the program.

A virtual environment isolates project packages from unrelated projects; it is not a security sandbox. Include a README (the front-page instructions of a project) with one working example and the expected output. Do not add external packages for a task the standard library (the modules that come with Python) already handles comfortably.

At this stage, a good deliverable is a small program another learner can run and explain, plus an honest list of its limits.

COMMON FAILURE MODE

Code that runs correctly only from one personal working directory is not a reproducible tool. Resolve file paths deliberately.

TRY IT YOURSELF

Separate a small script into a reusable function and main(). Import it from another file and verify the command-line interaction does not run during import.

RETRIEVAL CHECK / APPLY THE IDEA

Make the call in the laboratory.

The two-question checkpoint, your notes, and your saved progress are in the laboratory. Free, with no account.

Open in the laboratory ↗

CONNECT IT TO RELAY

Package Relay v0 as a small command-line tool with a README, a clear entry point, and a documented in-memory-only limitation.

GO TO THE SOURCEPython: modules ↗Python: virtual environments ↗