Historical Context & Motivation
Have you ever sent a friend a Python file only to hear back, "It doesn't work on my computer"? You are not alone. Since the earliest days of programming, developers have struggled with the problem of software distribution — getting code from the developer's machine into someone else's hands in a way that actually runs. The challenge is older than Python itself, stretching back to the era of punch cards and floppy disks.
In the early days, programs were tied to specific hardware. As personal computers became widespread in the 1980s and 1990s, developers began bundling their code with README files — simple text documents that explained how to install and run the software. This humble practice became the backbone of open-source culture and is still considered essential today.
The core question has not changed in fifty years: How do I hand my program to someone else and make sure it works? This lesson answers that question for your Python console apps by teaching you to write clear instructions, provide sample runs, and document every assumption your code makes.
Core Principles of Packaging
Packaging a console app is not just about zipping up your code. It means creating a complete, self-explanatory bundle that a stranger — or future-you — can understand without any extra help. Think of it like handing someone a board game: if the box is missing the rules, the pieces are unlabeled, and there is no picture of the finished game, nobody is going to have fun. A well-packaged app includes all the equivalent pieces.
Clear Instructions (README)
Sample Runs
Documented Assumptions
Organized File Structure
Version & Authorship
Anatomy of a Packaged Console App
The diagram below shows a typical project folder for a well-packaged Python console app. Notice how every file has a clear purpose and the folder is named with the project title. This structure is what you should aim for whenever you hand off a project.
Some teachers or projects may ask you to combine the README, sample run, and assumptions into a single README file. That is perfectly fine — the key is that all three categories of information are present. For larger projects, separating them keeps each file short and easy to update.
How to Write Each Piece
The README: Your Project's Front Door
A good README answers five questions in this order: (1) What does this program do? (2) What do I need to have installed? (3) How do I run it? (4) What does a typical session look like? (5) What should I watch out for? You can use plain .txt format or Markdown (.md). Here is a template:
=== My Calculator ===
Author: Jane Doe
Date: January 2025
Version: 1.0
--- What It Does ---
A simple command-line calculator that performs
addition, subtraction, multiplication, and division
on two numbers entered by the user.
--- Requirements ---
Python 3.8 or newer (no extra libraries needed)
--- How to Run ---
1. Open a terminal / command prompt.
2. Navigate to this folder: cd my_calculator
3. Run: python calculator.py
4. Follow the on-screen prompts.
--- Sample Run ---
> python calculator.py
Enter first number: 10
Enter second number: 3
Choose operation (+, -, *, /): /
Result: 3.3333
--- Assumptions ---
- User enters valid numbers (no letters).
- Division by zero will display an error message.
- Tested on Windows 11 and macOS Ventura.Sample Runs: Show, Don't Tell
A sample run is a copy-paste of an actual terminal session. It includes the command you typed, every prompt the program printed, the user's input, and the final output. Include at least two sample runs: one that shows normal, expected behavior and one that shows edge-case or error handling. This proves to the reader that your program handles more than just the happy path.
Documented Assumptions: What You Took for Granted
Every program makes assumptions. Maybe you assumed the user would type a number, not a word. Maybe you assumed the file data.csv lives in the same folder. Maybe your code only works on Python 3.10 because you used match statements. Writing these down is not admitting weakness; it is a sign of professional maturity. Real software teams document assumptions in every design document they write.
- Python version — e.g., "Requires Python 3.8+"
- Operating system — e.g., "Tested on Windows 11 and macOS Sonoma"
- Input format — e.g., "User enters integers only, no decimals"
- External files — e.g., "scores.txt must exist in the same directory"
- Known limitations — e.g., "Does not handle negative numbers"
The Packaging Checklist
Before you submit or share your project, walk through the checklist below. Think of it as a quality-control inspection. Each item maps to one of the five core principles you learned in Section 2. The diagram that follows visualizes the flow from writing code to delivering a finished package.
| ✓ | Checklist Item | Where to Put It |
|---|---|---|
| 1 | Program description (1–2 sentences) | README — top |
| 2 | Author name, date, version | README — header |
| 3 | Installation/setup instructions | README — Requirements |
| 4 | Run command (e.g., python app.py) | README — How to Run |
| 5 | At least 2 sample runs (normal + edge case) | README or sample_run.txt |
| 6 | All assumptions listed | README or assumptions.txt |
| 7 | Folder named, files named meaningfully | Project folder |
Worked Example: Packaging a Tip Calculator
Let's walk through the entire process for a small project — a tip calculator that asks for a bill amount and tip percentage, then prints the tip and total. We will write the code, test it, create sample runs, write the README, and document assumptions.
tip_calculator.py with the following content:
# tip_calculator.py
# Author: Alex Rivera
# Date: January 2025
# Version: 1.0
bill = float(input("Enter the bill amount: $"))
percent = float(input("Enter tip percentage (e.g., 20): "))
tip = bill * (percent / 100)
total = bill + tip
print(f"Tip: ${tip:.2f}")
print(f"Total: ${total:.2f}")tip_calculator.pypython tip_calculator.py. Try several inputs: a normal bill ($50, 20%), a zero tip ($30, 0%), and a large tip ($100, 50%). Also try typing a word instead of a number to see what happens (spoiler: the program crashes with a ValueError — that is an assumption to document).
> python tip_calculator.py
Enter the bill amount: $50
Enter tip percentage (e.g., 20): 20
Tip: $10.00
Total: $60.00
And here is the edge-case run with zero tip:
> python tip_calculator.py
Enter the bill amount: $30
Enter tip percentage (e.g., 20): 0
Tip: $0.00
Total: $30.00README.txt using the template from Section 4. Fill in the project title, author, date, description, requirements (Python 3.6+, no libraries), run instructions, the sample runs from Step 3, and the assumptions from Step 5.README.txttip_calculator.py and README.txt into a folder named tip_calculator. Right-click the folder and choose "Compress" or "Send to → Compressed folder" to create tip_calculator.zip. Submit the zip file.Common Strengths & Pitfalls
When teachers and professional code reviewers evaluate a packaged console app, they look for specific strengths and watch for common mistakes. The table below contrasts what good packaging looks like versus what often goes wrong.
| Area | ✅ Strong Packaging | ❌ Common Pitfall |
|---|---|---|
| README | Answers all 5 questions; a stranger can run the app in under 2 minutes | Missing or says only "Run my code" with no details |
| Sample Runs | Includes 2+ runs showing normal and edge-case behavior | No sample run, or only one run with ideal input |
| Assumptions | Lists Python version, OS, input constraints, and known limitations | Not mentioned at all; user discovers limits by crashing the program |
| File Names | Descriptive names like grade_book.py, README.txt | Files named untitled.py, test123.py, or final_FINAL_v3.py |
| Folder | Everything in one clearly-named folder; no stray files | Code emailed as a loose attachment; no README at all |
Connection to Professional Practices
The skills you are learning here are a simplified version of what professional developers do every day. In industry, packaging grows more complex — but the principles stay the same. The table below compares what you are doing now with what you might encounter in a college course or a job.
| This Course | Professional / Advanced |
|---|---|
| README.txt with run instructions | README.md with Markdown formatting, badges, and auto-generated docs |
| Copy-pasted sample runs | Automated test suites (pytest, unittest) that verify output programmatically |
| Manually listed assumptions | Type hints, docstrings, and input validation built into the code |
| Zip file submission | GitHub repo, PyPI package, Docker container, or compiled executable |
| requirements.txt (if any) | Virtual environments (venv), poetry, or conda environment files |
Do not be intimidated by the professional column. Every expert started exactly where you are: writing a README in a text file and zipping up a folder. The habits you build now — clear communication, honest documentation, and organized delivery — will scale naturally as your projects grow.
Practice Problems
project.py with no other files or explanation. List three specific things you do not know that a good README would have told you.C = (F − 32) × 5 / 9. Write a sample run for the input 212°F and another for 32°F. Show the exact text the user would see in the terminal.name = input("Enter student name: ")
score = int(input("Enter test score: "))
if score >= 60:
print(f"{name} passed!")
else:
print(f"{name} did not pass.")grades.csv and prints each student's average. Write a complete README for this program. Include: title/author/date, description, requirements, run instructions, one sample run, and at least three assumptions.Lesson Summary
Packaging a console app means delivering more than just a Python source file. A complete package includes a README that answers five essential questions (what, prerequisites, how to run, sample output, and caveats), at least two sample runs showing both normal and edge-case behavior, and a thorough list of documented assumptions covering Python version, operating system, input constraints, and known limitations.
The seven-step packaging workflow — write code, test, capture runs, write the README, document assumptions, organize the folder, and deliver — turns a loose script into a professional-quality deliverable. These habits mirror real-world software distribution practices and will serve you well in advanced courses, open-source contributions, and careers in technology. Remember: code that no one can run delivers zero value — so package with care.