thousandproblems 0.3.0__cp315-cp315-win_amd64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
File without changes
@@ -0,0 +1,549 @@
1
+ """Search a local TPTP library by problem properties, like the TPTP2T form on tptp.org.
2
+
3
+ >>> from thousandproblems.search import search # doctest: +SKIP
4
+ >>> hits = search("/data/TPTP-v10.0.0", form="FOF", status="THM",
5
+ ... equality="none", rating="0.5..1", formulae="..50") # doctest: +SKIP
6
+ >>> [r.name for r in hits][:3] # doctest: +SKIP
7
+ ['AGT001+1', 'AGT001+2', 'AGT002+1']
8
+
9
+ Everything TPTP2T matches on comes from the problem headers: the ``% SPC`` line (logical
10
+ form, status, order, equality, arithmetic ...), the ``% Rating`` line, the ``% Version`` line
11
+ and the ``% Syntax`` statistics. Reading the headers of a whole library takes a little while,
12
+ so they are kept in an index under :func:`thousandproblems.library.default_cache_dir`, which
13
+ is rebuilt when the library changes.
14
+
15
+ Criteria are written as strings, the same as on the command line:
16
+
17
+ * lists are comma-separated and match any item: ``status="THM,UNS"``;
18
+ * numbers take ``N``, ``MIN..MAX``, ``MIN..``, ``..MAX``, ``>N``, ``>=N``, ``<N`` or ``<=N``:
19
+ ``formulae="10..100"``, ``predicates=">1"``;
20
+ * a ``not:`` prefix negates a criterion, like TPTP2T's ``~`` box: ``form="not:CNF"``.
21
+
22
+ TPTP2T's solution properties (system results, solution sizes ...) come from the TSTP
23
+ solution library, not the problem library, so they are not available here.
24
+ """
25
+
26
+ from __future__ import annotations
27
+
28
+ import fnmatch
29
+ import hashlib
30
+ import json
31
+ import math
32
+ import os
33
+ import re
34
+ import tarfile
35
+ from dataclasses import asdict, dataclass, field
36
+ from pathlib import Path
37
+ from typing import Callable, Iterable, Iterator, Optional, Union
38
+
39
+ from .library import (DirectoryLibrary, Library, LibraryError, TarballLibrary, _NAME_RE,
40
+ default_cache_dir, open_library)
41
+ from .nodes import Comment, Header, _parse_header
42
+ from .stats import SPC, STATUS_CODES, syntax_stats
43
+
44
+ __all__ = ["ProblemRecord", "Query", "build_index", "read_header", "search", "CRITERIA"]
45
+
46
+ _INDEX_FORMAT = 1
47
+
48
+ # ---------------------------------------------------------------------------------
49
+ # Headers and records
50
+ # ---------------------------------------------------------------------------------
51
+
52
+
53
+ def read_header(lines: Iterable[str], max_lines: int = 2000) -> Optional[Header]:
54
+ """Parse the standard header from the first lines of a problem, without reading the
55
+ formulae. ``lines`` can be an open text file."""
56
+ comments: list[Comment] = []
57
+ rules = 0
58
+ for number, line in enumerate(lines, 1):
59
+ text = line.rstrip("\r\n")
60
+ if text.startswith("%"):
61
+ comments.append(Comment(text, number))
62
+ if re.fullmatch(r"%-{5,}\s*", text):
63
+ rules += 1
64
+ if rules == 2:
65
+ break
66
+ elif text.strip() and comments:
67
+ break
68
+ if number >= max_lines:
69
+ break
70
+ return _parse_header(tuple(comments))
71
+
72
+
73
+ _VERSION_WORDS = (("Unbiased", "UNB"), ("Biased", "BIA"), ("Incomplete", "INC"),
74
+ ("Augmented", "AUG"), ("Especial", "ESP"))
75
+
76
+
77
+ @dataclass
78
+ class ProblemRecord:
79
+ """What the index knows about one problem.
80
+
81
+ ``syntax`` holds the ``% Syntax`` statistics as ``{key: [value, {detail: number}]}``,
82
+ with the keys of :func:`thousandproblems.stats.syntax_stats`; a range detail such as
83
+ ``aty`` is a two-item list.
84
+ """
85
+
86
+ name: str
87
+ path: str
88
+ spc: Optional[str] = None
89
+ status: Optional[str] = None # SZS name from the % Status line
90
+ rating: Optional[float] = None
91
+ version: str = "STD" # STD, INC, AUG, ESP, BIA or UNB
92
+ syntax: dict = field(default_factory=dict)
93
+
94
+ @property
95
+ def domain(self) -> str:
96
+ return self.name[:3]
97
+
98
+ @property
99
+ def form(self) -> Optional[str]:
100
+ return SPC(self.spc).form if self.spc else None
101
+
102
+ @property
103
+ def flags(self) -> frozenset[str]:
104
+ return SPC(self.spc).flags if self.spc else frozenset()
105
+
106
+ @property
107
+ def status_code(self) -> Optional[str]:
108
+ if self.spc and SPC(self.spc).status:
109
+ return SPC(self.spc).status
110
+ return STATUS_CODES.get(self.status or "")
111
+
112
+ def stat(self, *keys: str, detail: Optional[str] = None):
113
+ """The first of the ``% Syntax`` statistics ``keys`` present (or its ``detail``)."""
114
+ for key in keys:
115
+ if key in self.syntax:
116
+ value, details = self.syntax[key]
117
+ if detail is None:
118
+ return value
119
+ found = details.get(detail)
120
+ return tuple(found) if isinstance(found, list) else found
121
+ return None
122
+
123
+ @classmethod
124
+ def from_header(cls, name: str, path: str, header: Optional[Header]) -> "ProblemRecord":
125
+ if header is None:
126
+ return cls(name, path)
127
+ version_line = header.get("Version") or ""
128
+ version = next((code for word, code in _VERSION_WORDS if word in version_line), "STD")
129
+ syntax = {k: [s.value, {d: list(v) if isinstance(v, tuple) else v for d, v in s.details.items()}]
130
+ for k, s in syntax_stats(header).items()}
131
+ return cls(name, path, header.spc, header.status, header.rating, version, syntax)
132
+
133
+ def as_dict(self) -> dict:
134
+ return {**asdict(self), "domain": self.domain, "form": self.form}
135
+
136
+
137
+ # ---------------------------------------------------------------------------------
138
+ # The index
139
+ # ---------------------------------------------------------------------------------
140
+
141
+
142
+ def _problem_parts(rel: str) -> Optional[str]:
143
+ """``'Problems/SET/SET001-1.p'`` -> ``'SET001-1'``, or None if it is not a problem file."""
144
+ parts = rel.split("/")
145
+ if len(parts) == 3 and parts[0] == "Problems" and parts[2].endswith(".p"):
146
+ stem = parts[2][:-2]
147
+ if _NAME_RE.fullmatch(stem) and stem[:3] == parts[1]:
148
+ return stem
149
+ return None
150
+
151
+
152
+ def _directory_signature(root: Path) -> list:
153
+ problems = root / "Problems"
154
+ signature = []
155
+ for domain in sorted(problems.iterdir()):
156
+ if domain.is_dir():
157
+ signature.append([domain.name, domain.stat().st_mtime_ns, sum(1 for _ in domain.iterdir())])
158
+ return signature
159
+
160
+
161
+ def _scan_directory(root: Path, progress) -> Iterator[ProblemRecord]:
162
+ files = sorted((root / "Problems").glob("*/*.p"))
163
+ for count, file in enumerate(files, 1):
164
+ rel = file.relative_to(root).as_posix()
165
+ name = _problem_parts(rel)
166
+ if name is None:
167
+ continue
168
+ try:
169
+ with open(file, encoding="utf-8", errors="replace") as handle:
170
+ header = read_header(handle)
171
+ except OSError:
172
+ header = None
173
+ if progress:
174
+ progress(count, len(files))
175
+ yield ProblemRecord.from_header(name, rel, header)
176
+
177
+
178
+ def _scan_tarball(path: Path, progress) -> Iterator[ProblemRecord]:
179
+ try:
180
+ with tarfile.open(path, "r|*") as tar: # one sequential pass
181
+ count = 0
182
+ for member in tar:
183
+ name_in_tar = member.name[2:] if member.name.startswith("./") else member.name
184
+ parts = name_in_tar.split("/")
185
+ if not member.isfile() or "Problems" not in parts[:-1]:
186
+ continue
187
+ rel = "/".join(parts[parts.index("Problems"):])
188
+ name = _problem_parts(rel)
189
+ if name is None:
190
+ continue
191
+ handle = tar.extractfile(member)
192
+ # a streamed member is not seekable, so TextIOWrapper can't be used
193
+ header = read_header(line.decode("utf-8", errors="replace")
194
+ for line in iter(handle.readline, b"")) if handle else None
195
+ count += 1
196
+ if progress:
197
+ progress(count, None)
198
+ yield ProblemRecord.from_header(name, rel, header)
199
+ except (tarfile.TarError, OSError, EOFError) as e:
200
+ raise LibraryError(f"cannot read {path}: {e}") from e
201
+
202
+
203
+ def build_index(library: Union[str, os.PathLike, Library, None] = None, *, cache: Union[bool, str, os.PathLike] = True,
204
+ refresh: bool = False, progress: Optional[Callable[[int, Optional[int]], None]] = None
205
+ ) -> list[ProblemRecord]:
206
+ """Read the header of every problem in a local library (folder or tarball).
207
+
208
+ The result is cached (``cache=True``: under :func:`default_cache_dir`; or a folder;
209
+ ``False`` for no cache) and reused until the library changes. ``refresh`` rebuilds it.
210
+ ``progress(done, total)`` is called as files are read; ``total`` is None for a tarball.
211
+ """
212
+ lib = open_library(library)
213
+ try:
214
+ if isinstance(lib, DirectoryLibrary):
215
+ source = lib.root.resolve()
216
+ signature = _directory_signature(source)
217
+ scan = lambda: _scan_directory(source, progress) # noqa: E731
218
+ elif isinstance(lib, TarballLibrary):
219
+ source = lib.path.resolve()
220
+ st = source.stat()
221
+ signature = [st.st_size, st.st_mtime_ns]
222
+ scan = lambda: _scan_tarball(source, progress) # noqa: E731
223
+ else:
224
+ raise LibraryError("searching needs a local copy of the TPTP library (a folder or tarball); "
225
+ "the website cannot be searched. Get one with 'thousandproblems download'.")
226
+ finally:
227
+ if lib is not library:
228
+ lib.close()
229
+
230
+ cache_file = None
231
+ if cache:
232
+ folder = default_cache_dir() if cache is True else Path(cache)
233
+ digest = hashlib.sha1(str(source).encode()).hexdigest()[:16]
234
+ cache_file = folder / "indexes" / f"{digest}.json"
235
+ if not refresh:
236
+ try:
237
+ data = json.loads(cache_file.read_text(encoding="utf-8"))
238
+ if data.get("format") == _INDEX_FORMAT and data.get("signature") == signature:
239
+ return [ProblemRecord(**r) for r in data["problems"]]
240
+ except (OSError, ValueError, TypeError, KeyError):
241
+ pass
242
+
243
+ records = sorted(scan(), key=lambda r: r.name)
244
+ if cache_file is not None:
245
+ try:
246
+ cache_file.parent.mkdir(parents=True, exist_ok=True)
247
+ temporary = cache_file.with_name(f".{cache_file.name}.{os.getpid()}.tmp")
248
+ temporary.write_text(json.dumps({
249
+ "format": _INDEX_FORMAT, "source": str(source), "signature": signature,
250
+ "problems": [asdict(r) for r in records]}), encoding="utf-8")
251
+ os.replace(temporary, cache_file)
252
+ except OSError:
253
+ pass
254
+ return records
255
+
256
+
257
+ # ---------------------------------------------------------------------------------
258
+ # Criteria
259
+ # ---------------------------------------------------------------------------------
260
+
261
+
262
+ @dataclass(frozen=True)
263
+ class _Range:
264
+ low: float = -math.inf
265
+ high: float = math.inf
266
+ low_open: bool = False
267
+ high_open: bool = False
268
+
269
+ def __contains__(self, x) -> bool:
270
+ if x is None:
271
+ return False
272
+ return ((x > self.low) if self.low_open else (x >= self.low)) and \
273
+ ((x < self.high) if self.high_open else (x <= self.high))
274
+
275
+
276
+ def parse_range(text: str) -> _Range:
277
+ """``'5'``, ``'1..10'``, ``'1-10'``, ``'3..'``, ``'..3'``, ``'>1'``, ``'>=1'``, ``'<1'``, ``'<=1'``."""
278
+ t = text.strip().replace(" ", "")
279
+ number = r"\d+(?:\.\d*)?|\.\d+"
280
+ try:
281
+ if m := re.fullmatch(rf"(>=|<=|>|<)({number})", t):
282
+ op, value = m[1], float(m[2])
283
+ return {">": _Range(low=value, low_open=True), ">=": _Range(low=value),
284
+ "<": _Range(high=value, high_open=True), "<=": _Range(high=value)}[op]
285
+ if m := re.fullmatch(rf"({number})?(?:\.\.|-)({number})?", t):
286
+ if m[1] is None and m[2] is None:
287
+ raise ValueError
288
+ return _Range(float(m[1]) if m[1] else -math.inf, float(m[2]) if m[2] else math.inf)
289
+ value = float(t)
290
+ return _Range(value, value)
291
+ except ValueError:
292
+ raise ValueError(f"{text!r} is not a number or range (try 5, 1..10, 3.., ..3, >1)") from None
293
+
294
+
295
+ def _items(text: str) -> list[str]:
296
+ return [item.strip() for item in text.split(",") if item.strip()]
297
+
298
+
299
+ _FORM_GROUPS = {"TFF": {"TF0", "TF1"}, "TXF": {"TX0", "TX1"}, "THF": {"TH0", "TH1"},
300
+ "NXF": {"NX0", "NX1"}, "NHF": {"NH0", "NH1"}, "DHF": {"DH0", "DH1"}}
301
+ _FORMS = {"FOF", "CNF", "TF0", "TF1", "TX0", "TX1", "TH0", "TH1", "NX0", "NX1", "NH0", "NH1", "DH0", "DH1"}
302
+ _ORDER_WORDS = {"PROPOSITIONAL": "PRP", "EFFECTIVELYPROPOSITIONAL": "EPR", "FINITEHU": "FHU",
303
+ "FINITE": "FHU", "REAL": "RFO", "REALFIRSTORDER": "RFO"}
304
+ _EQUALITY = {"NONE": "NEQ", "NO": "NEQ", "SOME": "SEQ", "PURE": "PEQ", "ANY": "EQU",
305
+ "NEQ": "NEQ", "SEQ": "SEQ", "PEQ": "PEQ", "EQU": "EQU"}
306
+ _QUANTIFIERS = {"^": "^", "!": "!", "?": "?", "!>": "!>", "LAMBDA": "^", "FORALL": "!",
307
+ "EXISTS": "?", "TYPEFORALL": "!>", "VAL": "^", "VAU": "!", "VAE": "?", "VAP": "!>"}
308
+ _YES = {"YES", "Y", "TRUE", "SOME", "1"}
309
+ _NO = {"NO", "N", "FALSE", "NONE", "0"}
310
+
311
+
312
+ def _choice(value: str, table: dict[str, str], what: str) -> str:
313
+ key = re.sub(r"[\s_-]", "", value).upper()
314
+ if key in table:
315
+ return table[key]
316
+ raise ValueError(f"unknown {what} {value!r}; expected one of {', '.join(sorted(set(table.values())))}")
317
+
318
+
319
+ def _yes_no(value: str, what: str) -> bool:
320
+ key = value.strip().upper()
321
+ if key in _YES:
322
+ return True
323
+ if key in _NO:
324
+ return False
325
+ raise ValueError(f"{what} must be yes or no, not {value!r}")
326
+
327
+
328
+ def _numeric(*keys: str, detail: Optional[str] = None, default=None, arity: bool = False):
329
+ def build(value: str):
330
+ wanted = parse_range(value)
331
+
332
+ def test(r: ProblemRecord) -> bool:
333
+ found = r.stat(*keys, detail=detail)
334
+ if arity and isinstance(found, tuple):
335
+ found = found[1] # the maximal arity
336
+ return (default if found is None else found) in wanted
337
+ return test
338
+ return build
339
+
340
+
341
+ def _domain(value: str):
342
+ patterns = [p.upper() for p in _items(value)]
343
+ return lambda r: any(fnmatch.fnmatchcase(r.domain, p) for p in patterns)
344
+
345
+
346
+ def _name(value: str):
347
+ patterns = _items(value)
348
+ return lambda r: any(fnmatch.fnmatchcase(r.name, p) for p in patterns)
349
+
350
+
351
+ def _form(value: str):
352
+ wanted: set[str] = set()
353
+ for item in _items(value.upper()):
354
+ if item in _FORM_GROUPS:
355
+ wanted |= _FORM_GROUPS[item]
356
+ elif item in _FORMS:
357
+ wanted.add(item)
358
+ else:
359
+ raise ValueError(f"unknown logical form {item!r}; expected one of "
360
+ f"{', '.join(sorted(_FORMS | set(_FORM_GROUPS)))}")
361
+ return lambda r: r.form in wanted
362
+
363
+
364
+ def _order(value: str):
365
+ table = {**_ORDER_WORDS, **{c: c for c in ("PRP", "EPR", "FHU", "RFO")}}
366
+ wanted = {_choice(v, table, "order") for v in _items(value)}
367
+ return lambda r: bool(wanted & r.flags)
368
+
369
+
370
+ def _version(value: str):
371
+ table = {c: c for c in ("STD", "INC", "AUG", "ESP", "BIA", "UNB")}
372
+ table.update({"STANDARD": "STD", "INCOMPLETE": "INC", "AUGMENTED": "AUG", "ESPECIAL": "ESP",
373
+ "BIASED": "BIA", "UNBIASED": "UNB"})
374
+ wanted = {_choice(v, table, "version") for v in _items(value)}
375
+ return lambda r: r.version in wanted
376
+
377
+
378
+ def _status(value: str):
379
+ table = {c: c for c in STATUS_CODES.values()}
380
+ table.update({k.upper(): v for k, v in STATUS_CODES.items()})
381
+ wanted = {_choice(v, table, "status") for v in _items(value)}
382
+ return lambda r: r.status_code in wanted
383
+
384
+
385
+ def _rating(value: str):
386
+ word = value.strip().lower()
387
+ if word in ("easy", "esy"):
388
+ return lambda r: r.rating == 0.0
389
+ if word in ("difficult", "dif", "hard"):
390
+ return lambda r: r.rating is not None and 0.0 < r.rating < 1.0
391
+ if word in ("unsolved", "uso"):
392
+ return lambda r: r.rating == 1.0
393
+ wanted = parse_range(value)
394
+ return lambda r: r.rating in wanted
395
+
396
+
397
+ def _has_equality(r: ProblemRecord) -> bool:
398
+ if r.flags & {"SEQ", "PEQ", "EQU", "UEQ"}:
399
+ return True
400
+ if "NEQ" in r.flags:
401
+ return False
402
+ return bool(r.stat("atoms", "literals", detail="equ"))
403
+
404
+
405
+ def _equality(value: str):
406
+ code = _choice(value, _EQUALITY, "equality")
407
+ if code == "NEQ":
408
+ return lambda r: not _has_equality(r)
409
+ if code == "EQU":
410
+ return _has_equality
411
+ return lambda r: code in r.flags
412
+
413
+
414
+ def _unit_equality(value: str):
415
+ yes = _yes_no(value, "unit equality")
416
+ return lambda r: ("UEQ" in r.flags) == yes
417
+
418
+
419
+ def _arithmetic(value: str):
420
+ yes = _yes_no(value, "arithmetic")
421
+
422
+ def test(r: ProblemRecord) -> bool:
423
+ has = "ARI" in r.flags or bool(r.stat("arithmetic"))
424
+ return has == yes
425
+ return test
426
+
427
+
428
+ def _variables(value: str):
429
+ word = value.strip().upper()
430
+ if word in _YES:
431
+ return lambda r: bool(r.stat("variables"))
432
+ if word in _NO:
433
+ return lambda r: r.stat("variables") == 0
434
+ return _numeric("variables")(value)
435
+
436
+
437
+ def _quantifiers(value: str):
438
+ wanted = [_choice(v, _QUANTIFIERS, "quantifier") for v in _items(value)]
439
+
440
+ def test(r: ProblemRecord) -> bool:
441
+ cnf = r.form == "CNF"
442
+ for q in wanted:
443
+ count = r.stat("variables") if cnf and q == "!" else r.stat("variables", detail=q)
444
+ if not count:
445
+ return False
446
+ return True
447
+ return test
448
+
449
+
450
+ def _spc(value: str):
451
+ pattern = re.compile(value, re.IGNORECASE)
452
+ return lambda r: bool(r.spc and pattern.search(r.spc))
453
+
454
+
455
+ #: Every criterion: name -> (builder, help text). Names match the keyword arguments of
456
+ #: :func:`search` and, with ``_`` as ``-``, the command-line options.
457
+ CRITERIA: dict[str, tuple[Callable[[str], Callable[[ProblemRecord], bool]], str]] = {
458
+ "domain": (_domain, "domain codes, e.g. SET,SEU (wildcards allowed: SE?)"),
459
+ "name": (_name, "problem name patterns, e.g. 'SET0*-1'"),
460
+ "form": (_form, "logical form: FOF CNF TFF TXF THF TF0 TF1 TX0 TX1 TH0 TH1 NXF NHF DHF NX0 NX1 NH0 NH1 DH0 DH1"),
461
+ "order": (_order, "first-order subform: PRP (propositional), EPR (effectively propositional), "
462
+ "FHU (finite Herbrand universe), RFO (real first-order)"),
463
+ "version": (_version, "problem version: STD INC AUG ESP BIA UNB (standard, incomplete, augmented, "
464
+ "especial, biased, unbiased)"),
465
+ "status": (_status, "THM CAX CSA UNK UNS SAT OPN, or SZS names such as Theorem"),
466
+ "rating": (_rating, "easy (0.00), difficult (between), unsolved (1.00), or a range such as 0.5..1"),
467
+ "formulae": (_numeric("formulae", "clauses"), "number of formulae (clauses in CNF)"),
468
+ "unit_formulae": (_numeric("formulae", "clauses", detail="unt"), "number of unit formulae"),
469
+ "atoms": (_numeric("atoms", "literals"), "number of atoms (literals in CNF)"),
470
+ "equality": (_equality, "none, some (some but not pure), pure, or any"),
471
+ "unit_equality": (_unit_equality, "yes or no: a unit equality (UEQ) problem"),
472
+ "types": (_numeric("types", default=0), "number of types"),
473
+ "datatypes": (_numeric("types", detail="dat", default=0), "number of datatypes"),
474
+ "codatatypes": (_numeric("types", detail="cdt", default=0), "number of codatatypes"),
475
+ "symbols": (None, "number of symbols (predicates + functors; THF symbols)"),
476
+ "predicates": (_numeric("predicates"), "number of predicates"),
477
+ "predicate_arity": (_numeric("predicates", detail="aty", arity=True), "maximal predicate arity"),
478
+ "functions": (_numeric("functors"), "number of functors (including constants)"),
479
+ "function_arity": (_numeric("functors", detail="aty", arity=True), "maximal functor arity"),
480
+ "variables": (_variables, "none, some, or a number/range"),
481
+ "quantifiers": (_quantifiers, "binders that must be used: ^ ! ? !> (comma-separated)"),
482
+ "arithmetic": (_arithmetic, "yes or no"),
483
+ "spc": (_spc, "regular expression matched against the SPC, e.g. '_NHN'"),
484
+ }
485
+
486
+
487
+ def _symbols(value: str):
488
+ wanted = parse_range(value)
489
+
490
+ def test(r: ProblemRecord) -> bool:
491
+ count = r.stat("symbols")
492
+ if count is None:
493
+ p, f = r.stat("predicates"), r.stat("functors")
494
+ count = None if p is None and f is None else (p or 0) + (f or 0)
495
+ return count in wanted
496
+ return test
497
+
498
+
499
+ CRITERIA["symbols"] = (_symbols, CRITERIA["symbols"][1])
500
+
501
+
502
+ @dataclass
503
+ class Query:
504
+ """A conjunction of criteria; see :data:`CRITERIA` for the names."""
505
+
506
+ tests: list[tuple[str, str, Callable[[ProblemRecord], bool], bool]] = field(default_factory=list)
507
+
508
+ @classmethod
509
+ def build(cls, **criteria: Optional[str]) -> "Query":
510
+ query = cls()
511
+ for name, value in criteria.items():
512
+ if value is None:
513
+ continue
514
+ values = value if isinstance(value, (list, tuple)) else [value]
515
+ for item in values:
516
+ query.add(name, str(item))
517
+ return query
518
+
519
+ def add(self, name: str, value: str) -> "Query":
520
+ key = name.replace("-", "_")
521
+ if key not in CRITERIA:
522
+ raise ValueError(f"unknown search criterion {name!r}; known: {', '.join(CRITERIA)}")
523
+ negate = False
524
+ text = value.strip()
525
+ if text.lower().startswith("not:"):
526
+ negate, text = True, text[4:]
527
+ self.tests.append((key, value, CRITERIA[key][0](text), negate))
528
+ return self
529
+
530
+ def matches(self, record: ProblemRecord) -> bool:
531
+ return all(test(record) != negate for _, _, test, negate in self.tests)
532
+
533
+ def __bool__(self) -> bool:
534
+ return bool(self.tests)
535
+
536
+
537
+ def search(library: Union[str, os.PathLike, Library, None, list[ProblemRecord]] = None, *,
538
+ query: Optional[Query] = None, refresh: bool = False, **criteria: Optional[str]) -> list[ProblemRecord]:
539
+ """The problems of a local library that meet every criterion, sorted by name.
540
+
541
+ ``library`` is as for :func:`thousandproblems.open_library`, or a list of records from
542
+ :func:`build_index`. Criteria are keyword arguments (see :data:`CRITERIA`), or a prebuilt
543
+ :class:`Query`.
544
+ """
545
+ records = library if isinstance(library, list) else build_index(library, refresh=refresh)
546
+ q = query or Query()
547
+ if criteria:
548
+ q = Query(list(q.tests) + Query.build(**criteria).tests)
549
+ return [r for r in records if q.matches(r)]