Packaging Console Apps — I can package a console app with clear instructions, sample runs, and documented assumptions. - Computer Programming 1 Python

SECTION 1

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.

1970s • README is Born

Early Unix programmers start including a file called README with their tapes and disks, asking users to read it before doing anything else.

1991 • Python 0.9 Released

Guido van Rossum releases Python with a philosophy of readability and simplicity, making it ideal for shareable scripts.

2004 • setuptools & PyPI

The Python Package Index (PyPI) and setuptools give developers a standard way to distribute Python libraries and applications.

2008 • GitHub Launches

GitHub popularizes hosting code with built-in README rendering, making clear documentation a social norm for developers worldwide.

2020s • Modern Packaging Tools

Tools like PyInstaller and zipapp let you freeze Python apps into single executables, while README conventions continue to mature.

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.

SECTION 2

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)

A README file tells the user what the program does, how to install dependencies, and how to run it. It should be readable in under two minutes.

Sample Runs

Copy-paste examples of actual input and output show users exactly what to expect. They serve as proof that the program works.

Documented Assumptions

Every program assumes something — Python version, operating system, valid input range. Spelling these out prevents mysterious errors.

Organized File Structure

Group your source code, README, and any data files into a single folder with logical names. A messy project folder is a red flag.

Version & Authorship

Include your name, the date, and a version number. This helps users know if they have the latest copy and whom to contact for help.

✦

KEY TAKEAWAY

Think of packaging like writing a recipe card. The code is the ingredients, the README is the step-by-step directions, the sample runs are the photo of the finished dish, and the documented assumptions are the dietary notes ("contains nuts"). Without all four, someone trying your recipe will get lost.

SECTION 3

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.

A minimal but complete project folder. The README.txt sits at the top because it is the first thing a user should open. The source code, sample run, assumptions, and requirements are each in their own clearly-named file.

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.

SECTION 4

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:

💡

README 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"

SECTION 5

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.

The seven-step packaging workflow. Steps 1–3 produce the raw materials. Steps 4–6 organize them into a professional package. Step 7 is delivery — usually a .zip file or a repository link.

✓	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

Seven-item packaging checklist

SECTION 6

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.

Packaging a Tip Calculator

1
Step 1 — Write the Code

Create a file called 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}")

File created: tip_calculator.py
2
Step 2 — Run and Test

Open a terminal, navigate to the folder, and run python 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).

Tested with 4 different input sets.
3
Step 3 — Capture Sample Runs

Copy-paste two terminal sessions into a section of your README. Here is the normal run:> 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.00

Two sample runs captured: normal and edge case.
4
Step 4 — Write the README

Create README.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.

File created: README.txt
5
Step 5 — Document Assumptions

List everything you assumed while coding. For this project: (a) The user enters valid numbers. (b) Negative bills or percentages are mathematically handled but don't make real-world sense. (c) Requires Python 3.6+ for f-strings. (d) Tested on Windows 11. (e) No input validation — the program will crash if the user types non-numeric input.

Five assumptions documented in the README.
6
Step 6 — Organize and Deliver

Place tip_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.

✅ Package complete — ready for submission!

SECTION 7

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

Strengths versus pitfalls in console app packaging

✦

KEY TAKEAWAY

Imagine downloading an app from the internet with zero instructions. You would probably delete it immediately. Your classmates and teachers feel the same way when they receive a project folder with no README. Good packaging is an act of respect for the person on the other end.

SECTION 8

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

Beginner versus professional packaging approaches

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.

ℹ

Looking Ahead

If you want to explore further, look into PyInstaller (turns a Python script into a standalone .exe), GitHub Pages (host your README as a website), or Markdown (a simple formatting language that makes your README look polished).

SECTION 9

Practice Problems

Question 1: CONCEPTUAL

A classmate sends you a Python file called project.py with no other files or explanation. List three specific things you do not know that a good README would have told you.

Show answer

Without a README, you do not know: (1) what the program is supposed to do, so you cannot tell if the output is correct; (2) which version of Python is required, so it may crash with a syntax error on your machine; and (3) whether the program expects any specific input format, so you might enter something the code cannot handle. A README resolves all three of these unknowns before you even run the file.

Question 2: BASIC CALCULATION

You wrote a program that converts Fahrenheit to Celsius using the formula 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.

Show answer

Sample Run 1 (normal):


> python temp_converter.py
Enter temperature in Fahrenheit: 212
212.0°F = 100.0°C

Sample Run 2 (edge — freezing point):


> python temp_converter.py
Enter temperature in Fahrenheit: 32
32.0°F = 0.0°C

Both runs start with the command used to launch the program, include the user's input, and show the calculated output. Notice that 212°F maps to the boiling point (100°C) and 32°F to freezing (0°C), which makes these good verification inputs.

Question 3: INTERMEDIATE

Below is a short Python program. Identify at least four assumptions it makes that should be documented.

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.")

Show answer

Four assumptions to document: (1) The user enters a whole number for the score — entering a decimal like 85.5 or a word will crash the program because of int(). (2) A passing score is defined as 60 or above; other schools may use different cutoffs. (3) The program expects exactly one student per run — there is no loop for multiple students. (4) The score is assumed to be in the range 0–100, but the code does not enforce this, so a score of 999 would still say "passed." Each of these should appear in the assumptions section of the README.

Question 4: APPLIED

You built a grade-book program that reads a file called 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.

Show answer

=== Grade Book Analyzer ===
Author: Your Name
Date: January 2025
Version: 1.0

--- Description ---
Reads grades.csv and prints each student's
average score.

--- Requirements ---
Python 3.8+; no extra libraries.

--- How to Run ---
1. Place grades.csv in the same folder as
   grade_book.py.
2. Open a terminal and run:
   python grade_book.py

--- Sample Run ---
> python grade_book.py
Alice: 88.5
Bob: 72.0
Carla: 95.3

--- Assumptions ---
- grades.csv must exist in the same directory.
- CSV format: Name, Score1, Score2, Score3
  (header row expected).
- All scores are numeric.
- Tested on Windows 11 with Python 3.10.

This README answers all five key questions: what, prerequisites, how, example, and caveats. A stranger could follow these instructions and successfully run your program.

Question 5: CRITICAL THINKING

A teammate argues that writing a README is a waste of time because "the code speaks for itself." Write a three-to-four-sentence argument explaining why documented packaging matters, even when the code is well-written. Use at least one real-world analogy in your response.

Show answer

Even beautifully written code cannot tell the user which Python version to install, what operating system was tested, or what kind of input to type. A well-organized appliance may be intuitive once you open the box, but you still need the quick-start guide to know which outlet to plug it into and which buttons to press first. Documented packaging respects the user's time by eliminating guesswork and reducing trial-and-error. In professional software development, projects without documentation are routinely rejected during code review, no matter how elegant the code itself is — because code that no one can run is code that delivers zero value.

SUMMARY

Lesson Summary

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.