009-the_secret_auction_program/docs/plan.md

Plan: Secret Auction Program (Day 9)

Context

Udemy 100 Days of Code blind-auction CLI. The repository uses a Python .gitignore, an AGPL LICENSE and a git-ignored .env (tokens, never printed or committed). Python 3.13 or newer is required.

Working method

Work on ONE milestone at a time. Each milestone is one branch (milestone/NN-name) and one pull request. When a milestone is finished, stop, verify it and review before starting the next. Milestones and issues are also tracked on the Gitea repository (via API, token from .env).

Milestone 1 - Project scaffold and repo metadata (milestone/01-scaffold)

• Create src/secret_auction/__init__.py, tests/, docs/
• pyproject.toml: requires-python >=3.13, src layout, no runtime deps, dev extra (pytest), pytest config, console script
• .env.example; .env and .venv/ ignored; add docs/doxygen/ to .gitignore
• constants.py
• Doxyfile
• Set repository description and topics (python, udemy, 100-days-of-code, blind-auction, beginner) via API
• Create milestones and issues on the host (milestones M1-M4, issues #1-#12)
• Verify: create .venv, upgrade pip, pip install -e ".[dev]"
• Save plan and milestones in docs/plan.md

Milestone 2 - Core auction logic and env loader (milestone/02-core-logic)

• auction.py (Doxygen comments): add_bid, find_winner (uses max(bids, key=bids.get), ValueError on empty)
• env.py: stdlib .env loader (no python-dotenv); does not override existing environment variables
• tests/test_auction.py (.env loader is for private use and intentionally not tested)
• Verify: pytest passes

Milestone 3 - CLI program (milestone/03-cli)

• main.py: prompt name and numeric bid (re-prompt on invalid), bids dict kept outside the loop, "other bidders? yes/no", clear screen with newlines between bidders, announce the winner
• tests/test_main.py with monkeypatched input
• Verify: pytest; scripted run python -m secret_auction.main with two bidders

Milestone 4 - Documentation (milestone/04-docs)

• README.md from the template (Overview, Requirements, Setup incl. creating/activating .venv and python -m pip install --upgrade pip, Run, Tests, License AGPL, Links)
• docs/flowchart.md (Mermaid plus link to the diagrams.net chart)
• Generate Doxygen docs if doxygen is installed
• Verify: README commands work verbatim; .env stays untracked