Homework

Personalized common-core math worksheets for my first grader.

The goal: skip the search for a worksheet that's almost what I want and generate exactly the right mix of problems on demand. Each script in this repo produces a printable PDF (for the actual homework) plus an editable Markdown file (for tweaking before printing).

Setup

The project uses a Python virtualenv at env/ (gitignored). To recreate it from scratch:

python -m venv env
env\Scripts\python.exe -m pip install reportlab

Then run any script via env\Scripts\python.exe <script>.py.

Scripts

math_homework.py

Generates a single-page math worksheet with a configurable mix of addition, subtraction, multiplication, and division problems. Each problem is rendered in the missing-number style — one of the three slots (left operand, right operand, or result) is blank for the student to fill in, with the missing slot randomized per problem.

Two files are written for every run:

• <prefix>.md — numbered problems in a Markdown table. Easy to scan, edit, or hand-tweak before printing.
• <prefix>.pdf — printable worksheet, two-column grid by default, modern Segoe UI font on Windows (falls back to Helvetica elsewhere).

Usage

env\Scripts\python.exe math_homework.py [options]

Options

Flag	Default	Description
--add N	0	Number of addition problems
--sub N	0	Number of subtraction problems
--mul N	0	Number of multiplication problems
--div N	0	Number of division problems
--min N	0	Smallest number that may appear in any equation
--max N	20	Largest number that may appear in any equation
--columns N	2	Number of columns in the worksheet grid
--title TEXT	auto-generated	Worksheet title (e.g. "Addition to 20")
--instructions TEXT	"Write the missing number in each equation."	Instruction line shown under the title
--output PREFIX, -o	worksheet_<YYYY-MM-DD>	Output path prefix; produces <prefix>.md and <prefix>.pdf
--seed N	random	Seed for reproducible worksheets — same seed produces the same problems

At least one of --add, --sub, --mul, or --div must be greater than 0.

Examples

A worksheet matching the classic "Addition to 10 — Missing Addends" format (12 problems, two columns, 0–10):

env\Scripts\python.exe math_homework.py --add 12 --max 10 --output addition_to_10

Mixed addition and subtraction up to 20:

env\Scripts\python.exe math_homework.py --add 6 --sub 6 --max 20 --output mixed

Three-column worksheet with all four operations (smaller range so multiplication is realistic for a first grader):

env\Scripts\python.exe math_homework.py --add 4 --sub 4 --mul 4 --div 4 --max 12 --columns 3

Reproducible worksheet — re-run with the same seed to get the same problems:

env\Scripts\python.exe math_homework.py --add 12 --seed 42 --output today

How values are constrained

All numbers in every problem stay within [--min, --max]:

• Addition — a + b = c, all in range.
• Subtraction — a − b = c, never produces a negative result.
• Multiplication — both factors are forced to ≥ 1, which avoids ambiguous puzzles like 0 × □ = 0 where any answer would be correct.
• Division — divisor ≥ 1 (no divide-by-zero) and quotient ≥ 1 (avoids the same ambiguity as multiplication). Always evenly divisible.

The missing slot is chosen independently per problem with equal probability across the three positions, so a worksheet with twelve addition problems will roughly contain four of each shape: □ + b = c, a + □ = c, and a + b = □.

Adding a new operation

Three steps, all in math_homework.py:

1. Add the operator symbol to OPERATORS and a display name to OP_NAMES.
2. Write a generate_<op>(min_v, max_v, rng) -> Problem function and register it in GENERATORS.
3. Add a CLI flag in build_parser() and include its count in the counts dict inside main().

The Markdown and PDF renderers are operation-agnostic — they just read Problem.operator_symbol() and Problem.missing, so no rendering changes are needed.

License

See LICENSE.