Repository navigation
Expand file tree
/
Copy pathbptools.py
More file actions
1457 lines (1315 loc) · 49.2 KB
/
Copy pathbptools.py
File metadata and controls
1457 lines (1315 loc) · 49.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#General Toosl for These Problems
import os
import re
import random
import zlib
import sys
import inspect
import copy
import argparse
import subprocess
import tempfile
import zipfile
import pathlib
import html
import webbrowser
from collections import defaultdict
import tabulate
from qti_package_maker import package_interface
from qti_package_maker.common import anti_cheat
from qti_package_maker.common import yaml_tools
from qti_package_maker.common import string_functions
from qti_package_maker.assessment_items import validator
from qti_package_maker.assessment_items import item_types
from qti_package_maker.engines.bbq_text_upload import write_item as bbq_write_item
from qti_package_maker.engines.human_readable import write_item as human_write_item
answer_histogram = defaultdict(int)
question_count = 0
letters = 'ABCDEFGHJKMNPQRSTUWXYZ'
crc16_dict = {}
allow_insert_hidden_terms = True
allow_no_click_div = True
default_insert_hidden_terms = False
default_no_click_div = False
SINGLE_QUESTION_ATTEMPT_MULTIPLIER = 4
nocheater = anti_cheat.AntiCheat()
nocheater.use_insert_hidden_terms = default_insert_hidden_terms
nocheater.use_no_click_div = default_no_click_div
#==========================
def _patch_anticheat_insert_hidden_terms():
"""
Compatibility shim for qti_package_maker AntiCheat API changes.
Some versions call insert_hidden_terms(text, hidden_term_bank) while others define
insert_hidden_terms(text) and store the term bank on self.
"""
sig = inspect.signature(anti_cheat.AntiCheat.insert_hidden_terms)
if len(sig.parameters) == 2:
original = anti_cheat.AntiCheat.insert_hidden_terms
def insert_hidden_terms(self, text_content: str, hidden_term_bank=None) -> str:
return original(self, text_content)
anti_cheat.AntiCheat.insert_hidden_terms = insert_hidden_terms
_patch_anticheat_insert_hidden_terms()
#==========================
def _get_hidden_terms_default() -> bool:
return bool(default_insert_hidden_terms and allow_insert_hidden_terms)
#==========================
def _get_no_click_default() -> bool:
return bool(default_no_click_div and allow_no_click_div)
#==========================
def _apply_anticheat_args(args):
hidden_terms = _get_hidden_terms_default()
noclick_div = _get_no_click_default()
if hasattr(args, 'hidden_terms') and args.hidden_terms is not None:
hidden_terms = bool(args.hidden_terms)
if hasattr(args, 'noclick_div') and args.noclick_div is not None:
noclick_div = bool(args.noclick_div)
if not allow_insert_hidden_terms:
hidden_terms = False
if not allow_no_click_div:
noclick_div = False
nocheater.use_insert_hidden_terms = bool(hidden_terms)
nocheater.use_no_click_div = bool(noclick_div)
#==========================
def apply_anticheat_args(args):
"""
Apply CLI anti-cheat flags to the global AntiCheat settings.
"""
_apply_anticheat_args(args)
#==========================
def add_anticheat_args(parser):
"""
Add shared anti-cheat flags to an argparse parser.
"""
parser.add_argument(
'--hidden-terms', dest='hidden_terms', action='store_true',
help=argparse.SUPPRESS
)
parser.set_defaults(hidden_terms=_get_hidden_terms_default())
parser.add_argument(
'--noclick-div', dest='noclick_div', action='store_true',
help=argparse.SUPPRESS
)
parser.set_defaults(noclick_div=_get_no_click_default())
return parser
#==========================
def add_bbexport_args(parser: argparse.ArgumentParser) -> argparse.ArgumentParser:
"""
Add shared Blackboard export and self-test flags to an argparse parser.
"""
parser.add_argument(
'-B', '--bbexport', dest='bbexport', action='store_true',
help='Also create a Blackboard pool export ZIP.'
)
parser.set_defaults(bbexport=False)
parser.add_argument(
'-I', '--html-to-image', dest='html_to_image', action='store_true',
help='Convert all HTML tables and RDKit canvases to packaged PNGs (requires -B).'
)
parser.set_defaults(html_to_image=False)
parser.add_argument(
'-Z', '--image-scale', dest='image_scale', action=_ImageScaleAction, type=_positive_image_scale,
default=4,
help='Render packaged PNGs at this pixel scale (default: 4; requires -I).'
)
parser.set_defaults(image_scale_supplied=False)
parser.add_argument(
'--selftest', action='store_true',
help='Also save an HTML self-test of one randomly selected question.'
)
parser.add_argument(
'-O', '--open-selftest', action='store_true',
help='Save an HTML self-test and open it in the default browser.'
)
return parser
#==========================
def _positive_image_scale(value: str) -> int:
"""Parse the positive raster scale used by HTML-to-image conversion."""
try:
scale = int(value)
except ValueError as error:
raise argparse.ArgumentTypeError('image scale must be a positive integer') from error
if scale < 1:
raise argparse.ArgumentTypeError('image scale must be a positive integer')
return scale
#==========================
class _ImageScaleAction(argparse.Action):
"""Record explicit scale selection so it cannot silently do nothing."""
def __call__(self, parser, namespace, value, option_string=None) -> None:
setattr(namespace, self.dest, value)
setattr(namespace, 'image_scale_supplied', True)
#==========================
def _validate_image_scale(image_scale: int) -> None:
"""Reject invalid scale values before a PNG render can allocate pixels."""
# ASVS 2.2.1: accept only positive integer scale factors at this boundary.
if not isinstance(image_scale, int) or isinstance(image_scale, bool) or image_scale < 1:
raise ValueError('image scale must be a positive integer')
#==========================
def _get_git_root(path=None):
"""Return the absolute path of the repository root."""
if path is None:
# Use the path of the script
path = os.path.dirname(os.path.abspath(__file__))
try:
base = subprocess.check_output(['git', 'rev-parse', '--show-toplevel'], cwd=path, universal_newlines=True).strip()
return base
except subprocess.CalledProcessError:
# Not inside a git repository
return None
#==========================
def get_repo_data_path(*parts):
"""
Build an absolute path under the repo data directory.
Args:
parts (tuple): Path components under the data directory.
Returns:
str: Absolute path to the requested data file.
"""
git_root = _get_git_root()
if git_root is None:
raise FileNotFoundError("Unable to locate git root for data path resolution.")
return os.path.join(git_root, "data", *parts)
#===========================================================
#===========================================================
def number_to_ordinal(integer):
return string_functions.number_to_ordinal(integer)
#==========================
def number_to_cardinal(integer):
return string_functions.number_to_cardinal(integer)
#==========================
def makeQuestionPretty(question):
return string_functions.make_question_pretty(question)
#==========================
def html_monospace(txt, use_nbsp=True):
return string_functions.html_monospace(txt, use_nbsp)
#==========================
def colorHTMLText(text, hex_code):
return string_functions.html_color_text(text, hex_code)
#==========================
def generate_gene_letters(num_genes, shift=-1, clear=False):
return string_functions.generate_gene_letters(num_genes, shift, clear)
#==========================
def checkAscii(mystr):
return string_functions.check_ascii(mystr)
#==========================
def getCrc16_FromString(mystr):
return string_functions.get_crc16_from_string(mystr)
#===========================================================
#===========================================================
def readYamlFile(yaml_file):
return yaml_tools.read_yaml_file(yaml_file)
#===========================================================
#===========================================================
def is_valid_html(html_str: str) -> bool:
return validator.validate_html(html_str)
#===========================================================
#===========================================================
def min_difference(numbers: list) -> int:
from qti_package_maker.common import color_wheel
return color_wheel.min_difference(numbers)
#==========================
def __getattr__(name: str) -> object:
"""Load the public palette attributes only when a caller requests them."""
if name not in ('color_wheel', 'dark_color_wheel', 'light_color_wheel',
'extra_light_color_wheel'):
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
from qti_package_maker.common import color_wheel
if name == 'color_wheel':
return color_wheel
return getattr(color_wheel, name)
#==========================
def get_indices_for_color_wheel(num_colors, color_wheel_length):
from qti_package_maker.common import color_wheel
return color_wheel.get_indices_for_color_wheel(num_colors, color_wheel_length)
#==========================
def default_color_wheel(num_colors, my_color_wheel=None):
from qti_package_maker.common import color_wheel
if my_color_wheel is None:
my_color_wheel = color_wheel.dark_color_wheel
return color_wheel.default_color_wheel(num_colors, my_color_wheel)
#==========================
def light_and_dark_color_wheel(num_colors, dark_color_wheel=None, light_color_wheel=None):
from qti_package_maker.common import color_wheel
return color_wheel.light_and_dark_color_wheel(num_colors, dark_color_wheel, light_color_wheel)
#==========================
def write_html_color_table(filename):
from qti_package_maker.common import color_wheel
color_wheel.write_html_color_table(filename)
#==========================
def _default_color_wheel_calc(num_colors=4):
from qti_package_maker.common import color_wheel
return color_wheel.default_color_wheel_calc(num_colors)
#==========================
def make_color_wheel(r, g, b, degree_step=40):
from qti_package_maker.common import color_wheel
return color_wheel.make_color_wheel(r, g, b, degree_step)
#===================================================================================
#===================================================================================
#===================================================================================
#==========================
def print_histogram():
sys.stderr.write("=== Answer Choice Histogram ===\n")
keys = list(answer_histogram.keys())
keys.sort()
total_answers = 0
values_row = []
for key in keys:
count = answer_histogram[key]
total_answers += count
values_row.append(count)
headers = list(keys)
headers.append("TOTAL")
values_row.append(total_answers)
table_text = tabulate.tabulate(
[values_row],
headers=headers,
tablefmt="fancy_grid"
)
print(table_text, file=sys.stderr)
sys.stderr.write("Total Questions = {0:d}; Total Answers = {1:d}\n".format(question_count, total_answers))
#===================================================================================
#===================================================================================
#===================================================================================
#==========================
def _add_base_args(parser):
"""
Add base CLI arguments for common generators.
Args:
parser (argparse.ArgumentParser): Argument parser to extend.
Returns:
argparse.ArgumentParser: The updated parser.
"""
parser.add_argument(
'-d', '--duplicate-runs', '--duplicates', metavar='#', type=int, dest='duplicates',
help='Number of accepted questions to generate; rejected attempts are redrawn.',
default=2
)
parser.add_argument(
'-x', '--max-questions', type=int, dest='max_questions',
default=None, help='Maximum number of questions to keep.'
)
parser = add_anticheat_args(parser)
parser = add_bbexport_args(parser)
return parser
#==========================
def _add_base_args_batch(parser):
"""
Add base CLI arguments for batch generators with a default cap.
Args:
parser (argparse.ArgumentParser): Argument parser to extend.
Returns:
argparse.ArgumentParser: The updated parser.
"""
parser = _add_base_args(
parser
)
parser.set_defaults(max_questions=99)
return parser
#==========================
def make_arg_parser(description=None, batch=False):
"""
Create a standard argument parser with base args.
Args:
description (str): Optional parser description.
batch (bool): Use batch defaults when True.
Returns:
argparse.ArgumentParser: Configured parser.
"""
if description is None:
description = "Generate blackboard questions."
parser = argparse.ArgumentParser(description=description)
if batch:
parser = _add_base_args_batch(
parser
)
else:
parser = _add_base_args(
parser
)
return parser
#==========================
def add_choice_args(parser, default=5):
"""
Add a standard number-of-choices argument.
Args:
parser (argparse.ArgumentParser): Argument parser to extend.
default (int | None): Default number of choices.
Returns:
argparse.ArgumentParser: The updated parser.
"""
parser.add_argument(
'-c', '--num-choices', metavar='#', type=int, dest='num_choices',
help="Number of choices to create.", default=default
)
return parser
#==========================
def add_hint_args(parser, hint_default=True, dest='hint'):
"""
Add standard hint and no-hint boolean flags.
Args:
parser (argparse.ArgumentParser): Argument parser to extend.
hint_default (bool): Default hint setting.
dest (str): Destination name for the parsed value.
Returns:
argparse.ArgumentParser: The updated parser.
"""
parser.add_argument(
'--hint', dest=dest, action='store_true',
help='Include a hint in the question'
)
parser.add_argument(
'--no-hint', dest=dest, action='store_false',
help='Do not include a hint in the question'
)
parser.set_defaults(**{dest: hint_default})
return parser
#==========================
def add_scenario_args(parser, dest='scenario_order', default='random'):
"""
Add a standard scenario-order toggle for scripts that precompute a scenario list.
By default, we prefer random ordering for student assessment use-cases.
"""
group = parser.add_mutually_exclusive_group(required=False)
group.add_argument(
'--sorted', dest=dest, action='store_const', const='sorted',
help='Use deterministic sorted scenario order.'
)
group.add_argument(
'--random', dest=dest, action='store_const', const='random',
help='Use randomized scenario order (default).'
)
parser.set_defaults(**{dest: default})
return parser
#==========================
def add_question_format_args(parser, types_list=None, required=True, default=None):
"""
Add standard question format arguments.
Args:
parser (argparse.ArgumentParser): Argument parser to extend.
types_list (list): Allowed question formats (ma, mc, num, fib).
required (bool): Require one of the options.
default (str | None): Default when not required.
Returns:
argparse.ArgumentParser: The updated parser.
"""
if types_list is None:
types_list = ['mc', 'num']
allowed_types = ['ma', 'mc', 'num', 'fib']
clean_types = []
for format_name in types_list:
format_text = str(format_name).lower()
if format_text not in allowed_types:
sys.stderr.write(
"WARNING: unknown question format ignored ({0})\n".format(format_text)
)
continue
if format_text in clean_types:
continue
clean_types.append(format_text)
if len(clean_types) == 0:
raise ValueError("No valid question formats were provided.")
dest = 'question_type'
question_group = parser.add_mutually_exclusive_group(required=required)
question_group.add_argument(
'--format', dest=dest, type=str,
choices=tuple(clean_types),
help='Set the question format.'
)
if 'mc' in clean_types:
question_group.add_argument(
'--mc', '--multiple-choice', dest=dest, action='store_const', const='mc',
help='Set question format to multiple choice'
)
if 'ma' in clean_types:
question_group.add_argument(
'--ma', '--multiple-answer', dest=dest, action='store_const', const='ma',
help='Set question format to multiple answer'
)
if 'num' in clean_types:
question_group.add_argument(
'--num', '--numeric', dest=dest, action='store_const', const='num',
help='Set question format to numeric'
)
if 'fib' in clean_types:
question_group.add_argument(
'--fib', '--fill-in-blank', dest=dest, action='store_const', const='fib',
help='Set question format to fill in the blank'
)
if required is False and default is not None:
parser.set_defaults(**{dest: default})
return parser
#==========================
def add_difficulty_args(parser, dest='difficulty', default='medium'):
"""
Add standard difficulty arguments (easy/medium/rigorous).
Args:
parser (argparse.ArgumentParser): Argument parser to extend.
dest (str): Destination name for the parsed value.
default (str): Default difficulty.
Returns:
argparse.ArgumentParser: The updated parser.
"""
difficulty_group = parser.add_mutually_exclusive_group(required=False)
difficulty_group.add_argument(
'--difficulty', dest=dest, type=str,
choices=('easy', 'medium', 'rigorous'),
help='Set difficulty level'
)
difficulty_group.add_argument(
'-E', '--easy', dest=dest, action='store_const', const='easy',
help='Set difficulty to easy'
)
difficulty_group.add_argument(
'-M', '--medium', dest=dest, action='store_const', const='medium',
help='Set difficulty to medium'
)
difficulty_group.add_argument(
'-R', '--rigorous', dest=dest, action='store_const', const='rigorous',
help='Set difficulty to rigorous'
)
parser.set_defaults(**{dest: default})
return parser
#==========================
def _warn_shortfall(question_count: int, requested_questions: int, attempts: int) -> None:
"""
Warn when collection does not reach its requested accepted-question count.
Args:
question_count (int): Number of accepted questions.
requested_questions (int): Requested number of accepted questions.
attempts (int): Number of generation attempts made.
"""
if question_count >= requested_questions:
return
sys.stderr.write(
"WARNING: generated {0} of {1} questions after {2} attempts\n".format(
question_count, requested_questions, attempts
)
)
#==========================
def _get_single_question_limits(args: argparse.Namespace) -> tuple[int, int]:
"""Return the accepted-question target and bounded redraw budget for one-item writers."""
target_questions = args.duplicates
if args.max_questions is not None:
target_questions = min(target_questions, args.max_questions)
max_attempts = target_questions * SINGLE_QUESTION_ATTEMPT_MULTIPLIER
return target_questions, max_attempts
#==========================
def _prepare_question_text(question_text: str, question_label: str):
"""
Validate and normalize a question string.
Args:
question_text (str): Question string or None.
question_label (str): Label for warnings (usually question number).
Returns:
str | None: Normalized question string or None to skip.
"""
if question_text is None:
return None
if not isinstance(question_text, str):
sys.stderr.write(
"WARNING: non-string question skipped ({0})\n".format(question_label)
)
return None
if len(question_text.strip()) == 0:
sys.stderr.write(
"WARNING: empty question skipped ({0})\n".format(question_label)
)
return None
check_text = question_text
if check_text.endswith("\n"):
check_text = check_text[:-1]
if "\n" in check_text or "\r" in check_text:
sys.stderr.write(
"WARNING: internal newline skipped ({0})\n".format(question_label)
)
return None
if question_text.endswith("\n") is False:
question_text += "\n"
return question_text
#==========================
def _is_item_cls_like(value) -> bool:
"""
Check whether a value looks like a qti_package_maker item class.
"""
if value is None:
return False
if isinstance(value, str):
return False
if hasattr(value, "_validate") is False:
return False
if hasattr(value, "item_type") is False:
return False
return True
#==========================
def _get_item_kind(item_cls) -> str:
"""
Resolve canonical item kind name used by bbq writer functions.
"""
item_type = getattr(item_cls, "item_type", None)
if isinstance(item_type, str) and len(item_type) > 0:
item_type = item_type.upper()
if item_type == "MAT":
return "MATCH"
return item_type
class_name = item_cls.__class__.__name__.upper()
if class_name == "MAT":
return "MATCH"
return class_name
#==========================
def _serialize_item_cls_to_bbq_text(item_cls):
"""
Convert an item class into a single-line BBQ text question.
"""
item_kind = _get_item_kind(item_cls)
item_copy = copy.deepcopy(item_cls)
use_no_click_before = nocheater.use_no_click_div
if item_kind in ("FIB", "MULTI_FIB", "NUM", "ORDER"):
nocheater.use_no_click_div = False
try:
nocheat_item_cls = nocheater.modify_item_cls(item_copy)
finally:
nocheater.use_no_click_div = use_no_click_before
if item_kind == "MC":
nocheat_item_cls.answer_text = nocheat_item_cls.choices_list[nocheat_item_cls.answer_index]
elif item_kind == "MA":
nocheat_item_cls.answers_list = [nocheat_item_cls.choices_list[idx] for idx in nocheat_item_cls.answer_index_list]
elif item_kind == "FIB":
nocheat_item_cls.answers_list = item_copy.answers_list
nocheat_item_cls._validate()
writer_map = {
"MC": bbq_write_item.MC,
"MA": bbq_write_item.MA,
"MATCH": bbq_write_item.MATCH,
"FIB": bbq_write_item.FIB,
"MULTI_FIB": bbq_write_item.MULTI_FIB,
"NUM": bbq_write_item.NUM,
"ORDER": bbq_write_item.ORDER,
}
writer_fn = writer_map.get(item_kind)
if writer_fn is None:
raise TypeError(f"unsupported item type for BBQ serialization: {item_kind}")
return writer_fn(nocheat_item_cls)
#==========================
def normalize_question_output(question_value, question_label: str = "?"):
"""
Normalize a generated question output into a BBQ line string.
Args:
question_value: Either a legacy BBQ string or an item_cls object.
question_label (str): Label for warnings.
Returns:
str | None: Prepared BBQ line text or None when invalid.
"""
if _is_item_cls_like(question_value):
try:
question_text = _serialize_item_cls_to_bbq_text(question_value)
except Exception as exc:
sys.stderr.write(
"WARNING: item serialization failed ({0}): {1}\n".format(question_label, exc)
)
return None
return _prepare_question_text(question_text, question_label)
return _prepare_question_text(question_value, question_label)
#==========================
def _should_print_histogram(questions_list: list) -> bool:
"""
Check whether questions include MC/MA prefixes.
Args:
questions_list (list): List of question strings.
Returns:
bool: True when MC/MA questions are present.
"""
for question_text in questions_list:
if _is_item_cls_like(question_text):
return len(answer_histogram) > 0
if question_text.startswith("MC\t") or question_text.startswith("MA\t"):
return True
return False
#==========================
def _get_question_identity(question_value):
"""
Build a stable identity key for duplicate filtering.
"""
if _is_item_cls_like(question_value):
item_crc16 = getattr(question_value, "item_crc16", None)
if isinstance(item_crc16, str) and len(item_crc16) > 0:
return ("item_crc16", item_crc16)
return ("item_repr", repr(question_value))
if isinstance(question_value, str):
prepared = _prepare_question_text(question_value, "?")
if prepared is None:
return None
return ("string", prepared.rstrip("\n"))
return None
#==========================
def _sync_histogram_from_item_cls_questions(questions: list):
"""
Rebuild MC/MA histogram counters from accepted item_cls questions only.
"""
bptools_has_only_item_cls = True
for question_value in questions:
if _is_item_cls_like(question_value) is False:
bptools_has_only_item_cls = False
break
if bptools_has_only_item_cls is False:
return
answer_histogram.clear()
global question_count
question_count = 0
for item_cls in questions:
item_type = getattr(item_cls, "item_type", "").upper()
if item_type == "MC":
answer_histogram[letters[item_cls.answer_index]] += 1
elif item_type == "MA":
for answer_index in item_cls.answer_index_list:
answer_histogram[letters[answer_index]] += 1
question_count += 1
#==========================
def _collect_questions(write_question, args, print_histogram_flag=True) -> list:
"""
Collect questions from a single-question writer.
Args:
write_question (callable): Function that returns a question string or None.
args (argparse.Namespace): Parsed arguments with duplicates and max_questions.
print_histogram_flag (bool): Print histogram when MC/MA questions are present.
Returns:
list: List of question strings.
"""
_apply_anticheat_args(args)
questions = []
seen_question_ids = set()
skipped_duplicates = 0
n = 0
target_questions, max_attempts = _get_single_question_limits(args)
attempts = 0
for _ in range(max_attempts):
attempts += 1
question_text = write_question(n + 1, args)
if isinstance(question_text, list):
sys.stderr.write(
"WARNING: write_question returned a list; use collect_question_batches\n"
)
continue
if _is_item_cls_like(question_text):
prepared_question = question_text
else:
prepared_question = _prepare_question_text(question_text, str(n + 1))
if prepared_question is None:
continue
question_identity = _get_question_identity(prepared_question)
if question_identity is not None and question_identity in seen_question_ids:
skipped_duplicates += 1
continue
if question_identity is not None:
seen_question_ids.add(question_identity)
questions.append(prepared_question)
n += 1
if n >= target_questions:
break
if skipped_duplicates > 0:
sys.stderr.write(
"INFO: skipped {0} duplicate questions during collection\n".format(skipped_duplicates)
)
_sync_histogram_from_item_cls_questions(questions)
if print_histogram_flag and _should_print_histogram(questions):
print_histogram()
_warn_shortfall(n, target_questions, attempts)
return questions
#==========================
def collect_question_batches(write_question_batch, args, print_histogram_flag=True) -> list:
"""
Collect questions from a batch writer.
Args:
write_question_batch (callable): Function that returns a list of questions.
args (argparse.Namespace): Parsed arguments with duplicates and max_questions.
print_histogram_flag (bool): Print histogram when MC/MA questions are present.
Returns:
list: List of question strings.
"""
_apply_anticheat_args(args)
global _warned_collect_question_batches
try:
warned = _warned_collect_question_batches
except NameError:
warned = False
if warned is False:
_warned_collect_question_batches = True
sys.stderr.write(
"DEPRECATION WARNING: bptools.collect_question_batches is a legacy pattern; "
"prefer single-question writers with bptools.collect_and_write_questions, "
"and use a prebuilt SCENARIOS list with shuffle-once + modulo-N selection. "
"Only use batch writers when one attempt must emit multiple questions.\n"
)
questions = []
seen_question_ids = set()
skipped_duplicates = 0
n = 0
max_questions = args.max_questions
for _ in range(args.duplicates):
batch = write_question_batch(n + 1, args)
if batch is None:
sys.stderr.write(
"WARNING: write_question_batch returned None; expected list\n"
)
continue
if not isinstance(batch, list):
sys.stderr.write(
"WARNING: write_question_batch did not return a list; skipped\n"
)
continue
if len(batch) == 0:
continue
for question_text in batch:
if _is_item_cls_like(question_text):
prepared_question = question_text
else:
prepared_question = _prepare_question_text(question_text, str(n + 1))
if prepared_question is None:
continue
question_identity = _get_question_identity(prepared_question)
if question_identity is not None and question_identity in seen_question_ids:
skipped_duplicates += 1
continue
if question_identity is not None:
seen_question_ids.add(question_identity)
questions.append(prepared_question)
n += 1
if max_questions is not None and n >= max_questions:
break
if max_questions is not None and n >= max_questions:
break
if skipped_duplicates > 0:
sys.stderr.write(
"INFO: skipped {0} duplicate questions during collection\n".format(skipped_duplicates)
)
_sync_histogram_from_item_cls_questions(questions)
if print_histogram_flag and _should_print_histogram(questions):
print_histogram()
if max_questions is not None:
_warn_shortfall(n, max_questions, args.duplicates)
return questions
#==========================
def make_outfile(*parts) -> str:
"""
Build a bbq output filename with optional suffix parts.
Args:
parts (tuple): Optional suffix parts to append to the filename.
Returns:
str: Output filename.
"""
# Backward compatibility:
# - historical call sites used `make_outfile(None, ...)` or `make_outfile(__file__, ...)`
# even though the base name is already derived from sys.argv[0].
# - some older call sites used `make_outfile("MC")` intending "MC" as a suffix part.
if len(parts) > 0 and parts[0] is None:
parts = parts[1:]
elif len(parts) > 0:
first = str(parts[0]).strip()
looks_like_path = (
(os.sep in first)
or ("/" in first)
or ("\\" in first)
or first.endswith(".py")
)
if looks_like_path:
parts = parts[1:]
main_file = getattr(sys.modules.get("__main__"), "__file__", None)
if isinstance(main_file, str) and main_file.endswith(".py") and main_file not in ("<stdin>", "<string>"):
script_path = main_file
else:
script_path = sys.argv[0]
if isinstance(script_path, str):
if script_path in ("-c", "-m") or (not script_path.endswith(".py")):
# Wrapper fallback: when argv[0] is not a useful script path, check for a
# nearby *.py argument.
for idx in (1, 2):
if len(sys.argv) <= idx:
break
cand = sys.argv[idx]
if isinstance(cand, str) and cand.endswith(".py") and cand not in ("<stdin>", "<string>"):
script_path = cand
break
if script_path is None or len(str(script_path)) == 0:
script_name = "script"
else:
script_name = os.path.splitext(os.path.basename(script_path))[0]
suffix = ""
for part in parts:
if part is None:
continue
part_text = str(part)
if len(part_text) == 0:
continue
suffix += f"-{part_text}"
outfile = f"bbq-{script_name}{suffix}-questions.txt"
return outfile
#==========================
def _get_blackboard_export_path(outfile: str | os.PathLike) -> tuple[str, str, str]:
"""
Validate a BBQ filename and derive its adjacent Blackboard export ZIP path.
ASVS 2.1.1, 2.2.1, and 5.3.2: the filename follows the documented
``bbq-<name>-questions.txt`` structure before its trusted basename controls
another path.
"""
outfile_path = os.fspath(outfile)
filename = os.path.basename(outfile_path)
match = re.fullmatch(r"bbq-(.+)-questions\.txt", filename)
if match is None:
raise ValueError(
f"BBQ filename '{filename}' does not match "
"'bbq-<name>-questions.txt'."
)
core_name = match.group(1)
output_dir = os.path.dirname(outfile_path)
export_name = f"bez-{core_name}.zip"
if output_dir:
export_path = os.path.join(output_dir, export_name)
else:
export_path = export_name
return outfile_path, export_path, core_name
#==========================
def _validate_blackboard_export_zip(export_path: str) -> None:
"""Validate the minimum Blackboard pool files in an export ZIP."""
if zipfile.is_zipfile(export_path) is False:
raise RuntimeError(f"Blackboard export is not a valid ZIP: {export_path}")
with zipfile.ZipFile(export_path, "r") as export_zip:
bad_member = export_zip.testzip()
if bad_member is not None:
raise RuntimeError(
f"Blackboard export contains an unreadable file ({bad_member}): "
f"{export_path}"
)
archive_names = set(export_zip.namelist())
required_names = {"imsmanifest.xml", "res00002.dat"}
missing_names = sorted(required_names - archive_names)
if missing_names:
missing_text = ", ".join(missing_names)
raise RuntimeError(
f"Blackboard export is missing required files ({missing_text}): {export_path}"
)
#==========================
def export_bbq_to_blackboard(
outfile: str | os.PathLike,
html_to_image: bool = False,
*, image_scale: int = 4) -> str:
"""
Convert a BBQ text file into an adjacent Blackboard pool export ZIP.
The BBQ file remains available if conversion fails. The ZIP is built at a
temporary adjacent path and replaces the destination only after validation.
When requested, all HTML tables and RDKit canvases become packaged PNGs.
"""
_validate_image_scale(image_scale)
outfile_path, export_path, package_name = _get_blackboard_export_path(outfile)
if os.path.isfile(outfile_path) is False:
raise FileNotFoundError(f"BBQ input file not found: {outfile_path}")
qti_packer = package_interface.QTIPackageInterface(