- Make generator scripts easier to read and maintain while preserving current CLI behavior.
- Reduce copy/paste in
main()and argument parsing. - Keep per-script question logic clear and local.
- Standardize how single-question scripts collect accepted questions with
-d/--duplicate-runs(alias--duplicates) and-x/--max-questions. - Provide a shared way to add base CLI args while allowing custom flags.
- Migrate incrementally; no mass refactor required.
- Prefer small helper functions over base classes.
- Keep script-specific logic in plain functions, not hidden in inheritance.
- Avoid lambdas; use direct function references.
- Preserve existing CLI semantics and output filenames.
- Single-question helpers treat
-d/--duplicate-runs(alias--duplicates) as the requested accepted-question count. They redraw rejected or duplicate attempts up to a fixed four-attempt budget per requested question, then return a smaller set with an explicit warning if necessary.-x/--max-questionsremains a hard cap.
- Single-question writers:
write_question(N, args)returns a non-empty string orNone.Nonemeans "no question generated." Empty strings are invalid and should be skipped with a warning. - Batch writers:
write_question_batch(N, args)returns a list of non-empty strings. An empty list means "no questions this attempt." The list must not containNonevalues.
- Each emitted question string must be a single line and end with
\\n. - Helpers may append a trailing newline if missing.
- If a question contains internal newlines (after trimming the final
\\n), helpers should warn and skip the question.
parse_arguments()should calladd_base_args(parser)first, then add custom flags. This keeps-d/--duplicate-runs(alias--duplicates) and-x/--max-questionsconsistent across scripts.- Recommended default help text:
-d/--duplicate-runs: "Number of accepted questions to generate; rejected attempts are redrawn."-x/--max-questions: "Maximum number of questions to keep."
- Defaults remain
duplicates=2andmax_questions=Noneunless a script explicitly needs different values.
- Scripts that write inside loops should be converted to return lists and use helpers, but only when the script is otherwise being edited.
Two helpers cover the main cases without a separate normalize step.
The single-question helper treats -d/--duplicate-runs (alias --duplicates) as an
accepted-question target and -x/--max-questions as a hard cap. Batch helpers retain
attempt-based -d semantics because one batch can legitimately emit many questions.
Both preserve a stable N that only advances when a question is accepted.
Writers should accept the full args namespace for consistency.
-
collect_questions(write_question, args)- Use when
write_question(N, args)returns a single question string orNone. - Redraws toward the
-daccepted-question target and caps at-xquestions. - Passes
Nas the next successful question number (1-based).
- Use when
-
collect_question_batches(write_question_batch, args)- Use when a generator produces multiple questions per attempt.
- Expects
write_question_batch(N, args)to return a list of question strings. - Enforces
-dattempts and caps at-xquestions. - Passes
Nas the starting question number for the batch and advances by the number of accepted questions.
make_outfile(script_path=None, *parts)- Builds
bbq-<script>-<parts>-questions.txtwhile skipping empty parts. - Uses
sys.argv[0]whenscript_pathis omitted.
- Builds
collect_and_write_questions(write_question, args, outfile)- Convenience helper that calls
collect_questions(...)and writes the output. - Standardizes status messages and pluralization.
- Convenience helper that calls
- Batch generators that return large fixed lists should rely on the batch parser default cap of 99.
- Keep the global default
duplicate_runs=2for quick testing.
Helpers may print the answer histogram when MC/MA questions are present, instead of relying on CLI flags. The detection rule should be simple and consistent:
- If any emitted question string starts with
MCorMA(for exampleMC\t), callbptools.print_histogram().
Add a shared function that scripts can opt into:
add_base_args(parser)- Adds
-d/--duplicate-runs(alias--duplicates) and-x/--max-questions. - Returns the parser so scripts can chain custom arguments.
- Adds
This keeps scripts consistent while still allowing custom flags and defaults.
Use a helper to avoid repeating parser construction and base args:
make_arg_parser(description=None, batch=False)- Creates an
argparse.ArgumentParserand applies base args. - When
batch=True, uses batch defaults (duplicate_runs=2,max_questions=99).
- Creates an
Use a batch-specific helper so large fixed lists are capped by default:
add_base_args_batch(parser)- Same flags as
add_base_args(...). - Defaults to
duplicate_runs=2andmax_questions=99.
- Same flags as
These can be added later to reduce boilerplate, without forcing all scripts to adopt them at once.
-
add_choice_args(parser, default=5)- Adds
-c/--num-choiceswith a standard help string and default.
- Adds
-
add_hint_args(parser)- Adds
--hintand--no-hintwith a standard default.
- Adds
-
add_question_format_args(parser, types_list=None)- Adds
--formatwith allowed types fromtypes_list. - Adds long flags for requested types:
--mc,--ma,--num, and--fib. - Adds expanded aliases:
--multiple-choice,--multiple-answer,--numeric, and--fill-in-blank.
- Adds
-
add_scenario_args(parser)- Adds
--random(default) and--sortedfor scripts that build a fixedscenarioslist. - Recommended behavior: prebuild
scenariosonce inmain(), shuffle when random, then select with modulo-N.
- Adds
-
add_difficulty_args(parser)- Adds
--difficultyand--easy/--medium/--rigorousshortcuts.
- Adds
-
add_output_args(parser)- Optional
--outfileoverride for scripts that want it. - Scripts that do not use
--outfilekeep their current naming rules.
- Optional
-
add_format_args(parser)- Only for scripts that truly need a question format flag.
- Most scripts can infer MC/MA from emitted strings and avoid this arg.
Single-question generators:
write_question(N, args) -> str | Nonequestions = collect_questions(write_question, args)
Batch generators:
write_question_batch(N, args) -> list[str]questions = collect_question_batches(write_question_batch, args)
- Add helpers to
bptools.py. - Update
TEMPLATE.pyto demonstrate the new flow. - Convert 2-3 representative scripts to validate the pattern.
- Convert scripts as they are touched for content updates.
- Favor high-duplication scripts first (largest maintenance win).
- Keep diffs small and focused.
- Review YAML-driven tools in
problems/multiple_choice_statements/andmatching_sets/. - Decide if they adopt the helpers or keep their bespoke pipelines.
- YAML-driven tools that batch-generate across many files may keep their own flow.
- Scripts that write directly to file inside loops can move to list returns over time when convenient.
- Helper-only scripts that generate standalone HTML assets (for example,
problems/biostatistics-problems/make_html_box_plot.py) should be excluded from the upgrade list and left as utilities rather than wrapped in question helpers.
This is the common refactor for scripts that currently emit a fixed "grid" of questions
via nested loops inside write_question_batch(...).
- Reduce nested loops and keep
main()small. - Keep
-d/--duplicatesand-x/--max-questionssemantics unchanged. - Keep
Nmeaning unchanged:- For single-question writers,
Nis the next successful question number (1-based). - For batch writers,
Nis the starting number for the batch.
- For single-question writers,
Pick one approach and document it in the script.
- Option 1 (deterministic round-robin, simple):
scenario = SCENARIOS[(N - 1) % len(SCENARIOS)]
- Option 2a (deterministic modulo N, same idea but explicit):
idx = (N - 1) % len(SCENARIOS)scenario = SCENARIOS[idx]
- Option 2b (random order, no repeats until exhausted):
- Shuffle once in
main():random.shuffle(SCENARIOS)
- Then select with modulo:
scenario = SCENARIOS[(N - 1) % len(SCENARIOS)]
- Shuffle once in
Avoid random.choice(SCENARIOS) for scenario selection; it can repeat scenarios and
skip others.
- Identify the "scenario" inputs that define one unique question (for example
(mode, vmax, km)or(sugar_name, anomeric)). - Prebuild a single
SCENARIOSlist once (typically inmain()). - Select exactly one scenario per question number
N(usually via modulo). - Derive all per-question values (tables, distractors, formatting) from that one scenario.
Notes:
- Prefer keeping derived state out of
args(reserved for CLI args); store prebuilt scenarios in a module-level cache likeSCENARIOSinitialized inmain(). - For huge cartesian products, avoid building a massive
SCENARIOSlist; instead compute mixed-radix indices fromNfor deterministic enumeration only. Pedigree homework now samples independently accepted cases; see PEDIGREE_PIPELINE.md. - Avoid "fully random batch writers" where
write_question_batch(...)returns a list of random scenarios each attempt. This often repeats scenarios, skips others, and makes output coverage hard to reason about. Prefer a single-question writer with a prebuiltSCENARIOSlist (shuffled once inmain()) plus modulo selection.
For scripts that build a fixed SCENARIOS list, expose:
bptools.add_scenario_args(parser):--random(default): shuffleSCENARIOSonce inmain()to reduce predictable cycling.--sorted: deterministicSCENARIOSorder for debugging/reproducibility.
Both --sorted and --random use the same modulo selection pattern:
scenario = SCENARIOS[(N - 1) % len(SCENARIOS)]The difference is whether SCENARIOS is shuffled once in main():
--sorted: deterministic order, even coverage, fully reproducible.--random: shuffle once inmain(), then modulo selection gives random order with even coverage and no repeats until all scenarios are exhausted.
Avoid random.choice(SCENARIOS) since it can repeat scenarios and skip others.
- Do not change the meaning of
-d/--duplicatesand-x/--max-questions: -dis the number of accepted questions requested from a single-question generator.-xis the maximum number of accepted questions to keep.
- A single-question writer should return
Noneto "skip" a failed attempt; the helper redraws until it reaches the requested count, the cap, or its bounded retry budget. - For batch lists that return pre-numbered questions (for example, matching
sets), add a
start_numparameter to the helper that creates the list so the numbering can begin at the batch startN. - When upgrading scripts that used custom signatures (for example
write_question(N, seqlen)or class methods), either update the signature towrite_question(N, args)or add a thin wrapper that forwardsargsfields. - Scripts that emit multiple questions per attempt (for example paired
highest/lowest prompts) should use
write_question_batch(...)withcollect_question_batches(...), then write viawrite_questions_to_file(...). - For scripts that iterate over a fixed item list (for example restriction
enzymes), build and shuffle the list once in
main(), store it in a module-level cache, and select from it inwrite_question(N, args)(orwrite_question_batch(...)if the script remains a batch writer).
- Cross-product ("grid") generators:
- If the script currently does nested loops in
write_question_batch(...), either:- keep it as a batch writer (still fine), or
- flatten into
SCENARIOSand convert towrite_question(N, args).
- If the script currently does nested loops in
- Shared data loads (CSV/YAML/word lists):
- Load once in
main()and cache it sowrite_question(...)does not re-open files.
- Load once in
- Mixed output modes (MC vs NUM/FIB):
- Use
bptools.add_question_format_args(...)and return a formatted Blackboard string viabptools.formatBB_*_Question(...)instead of printing directly to stdout.
- Use
- Fixed item lists (enzymes, amino acids, etc.):
- Build and (optionally) shuffle the list once in
main(), store it in a module-level cache, then select byidx = (N - 1) % len(SCENARIOS).
- Build and (optionally) shuffle the list once in
- Scripts that previously computed their own default run count to hit an
approximate total should now rely on the default of 2 and let users set
-dexplicitly when they want more.
- When a script manually constructs Blackboard text (for example
"MC\t..."), replace that block withbptools.formatBB_MC_Question(...)so numbering, histogram tracking, and formatting stay consistent. - For scripts that emit pure HTML (not an MC/MA/NUM/FIB Blackboard line), use
collect_questions(..., print_histogram_flag=False)and write the raw HTML strings without a question formatter.
- Scripts that already use
-xfor a different option (for example--max-length) should move that short flag to avoid colliding with the unified-x/--max-questionsbase arg. Prefer a nearby alternative like-M.
- Helper/plot utilities and explicitly broken scripts should be removed from
phase-1 upgrade lists and tracked separately (for example
problems/inheritance-problems/population_logistic_map_chaos.py).
These are common in older scripts and are the first candidates for cleanup when a file is otherwise being edited.
- Direct-to-file loops in
main()instead of returning question strings and using helpers. - Custom
argparseflags forduplicates/max_questions(or missing them), which creates inconsistent defaults and warnings. - Manual outfile construction in
main()that repeats the bbq naming logic. - Histogram printing scattered across scripts instead of using the helper.
- Scripts that embed both attempts and cap logic in nested loops that are hard to scan (the helper handles this).
- Batch scripts that generate large fixed lists without a default
-xcap. - Scripts that hard-code
--num-questions(or-q) should be migrated to the shared-d/--duplicatesand-x/--max-questionsflags to keep defaults consistent across the repo. - Scripts that read local data assets (HTML tables, word lists, CSVs) should
use
bptools.get_repo_data_path(...)when the file is indata/, or a__file__-relative path when the asset lives beside the script. Cache large reads so per-question generation does not re-open the file.
- Should helpers accept a
start_indexoverride for special cases? - Should histogram printing be toggled by a helper flag or always auto-detected?