Hands-on lab — Day 49: Your First Real Program

#!/usr/bin/env python3
"""Convert a temperature between Celsius and Fahrenheit.

This is a complete, small, real program: it reads input from the command
line, validates it, does one useful job, prints clear output, and fails
gracefully (a readable message and a non-zero exit code) on bad input.

Usage:
    python3 converter.py <value> <unit>

<value> is a number; <unit> is the unit you are converting FROM: C or F.

Examples:
    python3 converter.py 100 C   ->  100.0 C = 212.0 F
    python3 converter.py 32 F    ->  32.0 F = 0.0 C
"""
import sys

# Coldest physically possible temperature, used as a sanity-check edge case.
ABSOLUTE_ZERO_C = -273.15


def celsius_to_fahrenheit(celsius):
    """Return the Fahrenheit equivalent of a Celsius temperature."""
    return celsius * 9 / 5 + 32


def fahrenheit_to_celsius(fahrenheit):
    """Return the Celsius equivalent of a Fahrenheit temperature."""
    return (fahrenheit - 32) * 5 / 9


def parse_args(args):
    """Validate raw [value, unit] arguments and return (number, unit).

    Raises ValueError with a human-readable message on any bad input:
    wrong argument count, a non-numeric value, an unknown unit, or a
    temperature below absolute zero.
    """
    if len(args) != 2:
        raise ValueError("expected 2 arguments: <value> <unit> (e.g. 100 C)")
    value_text, unit_text = args
    try:
        value = float(value_text)
    except ValueError:
        raise ValueError(f"'{value_text}' is not a number")
    unit = unit_text.strip().upper()
    if unit not in ("C", "F"):
        raise ValueError(f"unit must be C or F, not '{unit_text}'")
    limit = ABSOLUTE_ZERO_C if unit == "C" else celsius_to_fahrenheit(ABSOLUTE_ZERO_C)
    if value < limit:
        raise ValueError(f"{value} {unit} is below absolute zero")
    return value, unit


def convert(value, unit):
    """Convert value from unit to the other unit; return (result, result_unit)."""
    if unit == "C":
        return celsius_to_fahrenheit(value), "F"
    return fahrenheit_to_celsius(value), "C"


def format_result(value, unit, result, result_unit):
    """Return the one-line, human-readable result string."""
    return f"{value:.1f} {unit} = {result:.1f} {result_unit}"


def main(argv):
    """Program entry point. Returns an exit code: 0 on success, 1 on bad input."""
    try:
        value, unit = parse_args(argv[1:])
    except ValueError as err:
        print(f"error: {err}", file=sys.stderr)
        print("usage: python3 converter.py <value> <unit>   (unit is C or F)",
              file=sys.stderr)
        return 1
    result, result_unit = convert(value, unit)
    print(format_result(value, unit, result, result_unit))
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

lesson_id: D049
day: 49
kind: python-program
languages: [python]
setup_commands:
  - cd labs/sections/programming-with-python/day-049-your-first-real-program
  - python3 --version
run_commands:
  - python3 examples/converter.py 100 C
  - python3 examples/converter.py 32 F
  - python3 starter/converter.py 212 F
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- starter/converter.py  # optional: reset your work'
requires_network: false
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-12'
executed_on: 'macOS (Apple Silicon), Python 3.14.0, bash tests/run_tests.sh → 12 checks, 0 failure(s), exit 0'

# Dependencies — Day 049 lab

**Python 3 only. No third-party packages.**

- `python3` (3.8 or newer; tested on 3.14). Preinstalled on most Linux
  distributions and installable on macOS; you set this up on Day 43.
- `bash` for the test runner (preinstalled on macOS and Linux).
- Only the Python standard library is used — specifically the `sys` module,
  which ships with Python. There is deliberately no `requirements.txt`: a
  first real program should run on a plain Python install with nothing to
  install first.

Check your Python is present and new enough:

```bash
python3 --version
```

If that prints `Python 3.8` or higher, you are ready. Windows users: run the
commands inside WSL, or use `python` in place of `python3` if that is how
Python is exposed on your system.

#!/usr/bin/env python3
"""Temperature converter — YOUR working file.

Build this program one exercise at a time. Each numbered exercise below
names exactly what to write. The finished reference is in
examples/converter.py — try each exercise yourself before peeking.

When you have completed all five exercises, this file should behave just
like the reference:

    python3 starter/converter.py 100 C   ->  100.0 C = 212.0 F
    python3 starter/converter.py hot C   ->  error (exit code 1)

Then run:  bash tests/run_tests.sh
"""
import sys

ABSOLUTE_ZERO_C = -273.15


def celsius_to_fahrenheit(celsius):
    """Return the Fahrenheit equivalent of a Celsius temperature."""
    # Exercise 1: WRITE A FUNCTION.
    # Return the Fahrenheit value: multiply by 9, divide by 5, add 32.
    # Verify by hand: celsius_to_fahrenheit(100) must be 212.0.
    raise NotImplementedError("Exercise 1: implement celsius_to_fahrenheit")


def fahrenheit_to_celsius(fahrenheit):
    """Return the Celsius equivalent of a Fahrenheit temperature."""
    # (Provided so the program is complete once Exercise 1 is done.)
    return (fahrenheit - 32) * 5 / 9


def parse_args(args):
    """Validate raw [value, unit] arguments and return (number, unit)."""
    # Exercise 3: VALIDATE INPUT.
    # 1. If len(args) != 2, raise ValueError with a clear message.
    # 2. Convert args[0] to float inside try/except; on failure raise
    #    ValueError(f"'{args[0]}' is not a number").
    # 3. Normalize args[1] with .strip().upper(); if it is not "C" or "F",
    #    raise ValueError naming the allowed units.
    # Exercise 5: HANDLE AN EDGE CASE.
    # 4. Reject temperatures below absolute zero (use ABSOLUTE_ZERO_C for C,
    #    and celsius_to_fahrenheit(ABSOLUTE_ZERO_C) for F).
    # Return (value, unit).
    raise NotImplementedError("Exercises 3 & 5: implement parse_args")


def convert(value, unit):
    """Convert value from unit to the other unit; return (result, result_unit)."""
    # (Provided.)
    if unit == "C":
        return celsius_to_fahrenheit(value), "F"
    return fahrenheit_to_celsius(value), "C"


def format_result(value, unit, result, result_unit):
    """Return the one-line, human-readable result string."""
    # Exercise 4: FORMAT OUTPUT.
    # Return an f-string like "100.0 C = 212.0 F", showing each number to
    # one decimal place (use the :.1f format specifier).
    raise NotImplementedError("Exercise 4: implement format_result")


def main(argv):
    """Program entry point. Returns an exit code: 0 on success, 1 on bad input."""
    try:
        value, unit = parse_args(argv[1:])
    except ValueError as err:
        print(f"error: {err}", file=sys.stderr)
        print("usage: python3 converter.py <value> <unit>   (unit is C or F)",
              file=sys.stderr)
        return 1
    result, result_unit = convert(value, unit)
    print(format_result(value, unit, result, result_unit))
    return 0


# Exercise 2: ADD THE MAIN GUARD.
# Below this comment, add the guard so the program runs only when this file
# is executed directly (not when it is imported):
#
#     if __name__ == "__main__":
#         sys.exit(main(sys.argv))

# Program design worksheet — Day 049

Design your program *before* you code it. Fill this in for the temperature
converter first (to practise), then reuse a blank copy for the practice
assignment's second program. Keep this file — the Command-Line Calculator
week project builds on exactly this design habit.

## 1. What one useful job does the program do?

One sentence:

> _e.g. Convert a temperature between Celsius and Fahrenheit._

## 2. Inputs — what does it need, and from where?

| Input | Type | Source |
| ----- | ---- | ------ |
|       |      |        |
|       |      |        |

## 3. Processing — what does it do with the inputs?

List the steps in order (include validation):

1.
2.
3.

## 4. Outputs — what does it produce, and where?

- On success:
- On failure (bad input):
- Exit code on success ______  on failure ______

## 5. Edge cases — at least three

What weird or wrong input might arrive, and how should the program respond?

| Edge case | What the program should do |
| --------- | -------------------------- |
| e.g. value is not a number |  |
| e.g. missing an argument   |  |
| e.g. impossible value      |  |

## 6. Behaviour on real inputs (fill in after building)

- One GOOD input you ran: `___________________`
  - What it printed: `___________________`
  - Exit code: ____
- One BAD input you ran: `___________________`
  - What it printed (to stderr): `___________________`
  - Exit code: ____

## 7. Prove it is importable (main-guard payoff)

Paste the `python3 -c` one-liner you used to import one function and check
its return value, and the output you saw:

```text

```

#!/usr/bin/env bash
# Tests for the Day 049 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# Exercises the complete reference program (examples/converter.py) on known
# good and bad inputs, checking both the printed output and the process exit
# code, then imports a function from the module and checks its return value.
# Finally it checks the learner's starter: structurally while exercises are
# unfinished, and to the same strict standard once they are complete.
# No network, non-interactive. Exits 0 only if every check passes.
set -u

# Keep the working tree clean: do not let imported modules write __pycache__.
export PYTHONDONTWRITEBYTECODE=1

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
ref="${lab_dir}/examples/converter.py"
starter="${lab_dir}/starter/converter.py"
failures=0
checks=0

check() {
  local label="$1" ok="$2"
  checks=$((checks + 1))
  if [ "${ok}" = "yes" ]; then
    echo "  ok: ${label}"
  else
    echo "  FAIL: ${label}"
    failures=$((failures + 1))
  fi
}

# check_run <label> <script> <expect_exit> <needle> <arg...>
# Runs the program, checks its exit code equals expect_exit and that its
# combined output contains needle.
check_run() {
  local label="$1" script="$2" expect_exit="$3" needle="$4"
  shift 4
  local out code
  out="$(python3 "${script}" "$@" 2>&1)"
  code=$?
  if [ "${code}" -eq "${expect_exit}" ] && printf '%s' "${out}" | grep -qF "${needle}"; then
    check "${label}" "yes"
  else
    check "${label}" "no"
    echo "    (exit ${code}, expected ${expect_exit}; output: ${out})"
  fi
}

run_program_checks() {
  local script="$1"
  echo "Testing ${script} ..."
  # Good inputs: correct conversion, exit 0.
  check_run "100 C -> 212.0 F"      "${script}" 0 "100.0 C = 212.0 F" 100 C
  check_run "32 F -> 0.0 C"         "${script}" 0 "32.0 F = 0.0 C"    32 F
  check_run "98.6 F -> 37.0 C"      "${script}" 0 "98.6 F = 37.0 C"   98.6 F
  # Bad inputs: clear error, non-zero exit.
  check_run "non-number rejected"   "${script}" 1 "is not a number"   hot C
  check_run "bad unit rejected"     "${script}" 1 "unit must be C or F" 100 K
  check_run "wrong arg count"       "${script}" 1 "expected 2 arguments" 100
  check_run "below absolute zero"   "${script}" 1 "below absolute zero" -300 C
}

# --- Reference program: always tested strictly ---
run_program_checks "${ref}"

# --- Import a function and check its return value (main-guard payoff) ---
echo "Testing importability of examples/converter.py ..."
if python3 -c "import sys; sys.path.insert(0, '${lab_dir}/examples'); \
from converter import celsius_to_fahrenheit; \
assert celsius_to_fahrenheit(100) == 212.0"; then
  check "import celsius_to_fahrenheit(100) == 212.0" "yes"
else
  check "import celsius_to_fahrenheit(100) == 212.0" "no"
fi
if python3 -c "import sys; sys.path.insert(0, '${lab_dir}/examples'); \
from converter import fahrenheit_to_celsius; \
assert fahrenheit_to_celsius(32) == 0.0"; then
  check "import fahrenheit_to_celsius(32) == 0.0" "yes"
else
  check "import fahrenheit_to_celsius(32) == 0.0" "no"
fi

# --- Learner starter ---
echo "Testing starter/converter.py ..."
if python3 -c "compile(open('${starter}').read(), '${starter}', 'exec')" 2>/dev/null; then
  check "starter is valid Python" "yes"
else
  check "starter is valid Python" "no"
fi

if grep -q 'NotImplementedError' "${starter}"; then
  echo "Note: starter/converter.py still has unfinished exercises — testing structure only."
  # Structural checks while the learner works.
  grep -q 'def celsius_to_fahrenheit' "${starter}" && check "starter defines celsius_to_fahrenheit" "yes" || check "starter defines celsius_to_fahrenheit" "no"
  grep -q 'def main' "${starter}" && check "starter defines main" "yes" || check "starter defines main" "no"
else
  # Learner finished: hold the starter to the same strict standard.
  run_program_checks "${starter}"
  grep -q '__name__ == "__main__"' "${starter}" && check "starter has the main guard" "yes" || check "starter has the main guard" "no"
fi

echo
echo "${checks} checks, ${failures} failure(s)."
[ "${failures}" -eq 0 ]