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.
@@ -0,0 +1,392 @@
1
+ """Statistics about a TPTP problem: the ones its header declares, and ones computed from the AST.
2
+
3
+ Every problem in the TPTP library carries a ``% Syntax`` block in its header, written by the
4
+ TPTP tools, and an ``% SPC`` line giving its Specialist Problem Class::
5
+
6
+ % Syntax : Number of clauses : 9 ( 3 unt; 1 nHn; 8 RR)
7
+ % Number of literals : 17 ( 0 equ; 8 neg)
8
+ % Number of predicates : 3 ( 3 usr; 0 prp; 2-2 aty)
9
+ % Number of variables : 13 ( 0 sgn)
10
+ % SPC : CNF_UNS_RFO_NEQ_NHN
11
+
12
+ :func:`syntax_stats` reads the first into a dict of :class:`Stat`, and :class:`SPC` splits the
13
+ second. :func:`compute_stats` works the main figures out from a parsed file, which also works
14
+ for files that have no header.
15
+
16
+ >>> import thousandproblems as tptp
17
+ >>> from thousandproblems.stats import compute_stats
18
+ >>> stats = compute_stats(tptp.parse("fof(a, axiom, ! [X] : (p(X) => q(f(X))))."))
19
+ >>> stats.formulae, stats.atoms, stats.predicates, stats.functions
20
+ (1, 2, ('p/1', 'q/1'), ('f/1',))
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ import re
26
+ from collections import Counter
27
+ from dataclasses import asdict, dataclass, field
28
+ from typing import Optional, Union
29
+
30
+ from .nodes import (Binary, Function, Header, Let, ModalAtom, NAry, Node, Quantified, TPTPFile,
31
+ Tuple, TypedVariable, Typing, Unary, Variable, walk)
32
+
33
+ __all__ = ["SPC", "Stat", "ComputedStats", "syntax_stats", "compute_stats", "DOMAINS",
34
+ "STATUS_CODES", "FORMS"]
35
+
36
+ # ---------------------------------------------------------------------------------
37
+ # Header statistics
38
+ # ---------------------------------------------------------------------------------
39
+
40
+ Value = Union[int, float, tuple[int, int]]
41
+
42
+
43
+ @dataclass(frozen=True)
44
+ class Stat:
45
+ """One line of a ``% Syntax`` block: ``Number of predicates : 3 (3 usr; 0 prp; 2-2 aty)``
46
+ is ``Stat(3, {'usr': 3, 'prp': 0, 'aty': (2, 2)})``.
47
+
48
+ A detail written as a range (``2-2 aty``) is a ``(min, max)`` tuple. When a key appears
49
+ twice, as in the THF ``Number of connectives`` line, the first wins.
50
+ """
51
+
52
+ value: int
53
+ details: dict[str, Value] = field(default_factory=dict)
54
+
55
+ def get(self, key: str, default=None):
56
+ return self.details.get(key, default)
57
+
58
+
59
+ _STAT_RE = re.compile(r"((?:Number|Maximal)[A-Za-z ]*?)\s*:\s*(\d+)((?:\s*\([^()]*\))*)")
60
+ _DETAIL_RE = re.compile(r"(\d+(?:\.\d+)?)(?:-(\d+))?\s*(\S+)")
61
+
62
+
63
+ def _key(label: str) -> str:
64
+ """``'Number of type conns'`` -> ``'type_conns'``, ``'Maximal formula depth'`` ->
65
+ ``'max_formula_depth'``, ``'Number arithmetic'`` -> ``'arithmetic'``."""
66
+ label = label.strip().lower()
67
+ if label.startswith("maximal "):
68
+ return "max_" + label[8:].replace(" ", "_")
69
+ return re.sub(r"^number (of )?", "", label).replace(" ", "_")
70
+
71
+
72
+ def syntax_stats(header: Optional[Header]) -> dict[str, Stat]:
73
+ """The ``% Syntax`` block of a problem header, keyed by a short name.
74
+
75
+ Keys are the labels with ``Number of`` dropped and ``Maximal`` shortened to ``max_``,
76
+ e.g. ``formulae`` (``clauses`` in CNF), ``atoms`` (``literals`` in CNF), ``predicates``,
77
+ ``functors``, ``symbols`` (THF), ``variables``, ``types``, ``max_formula_depth``.
78
+ """
79
+ text = header.get("Syntax") if header is not None else None
80
+ if not text:
81
+ return {}
82
+ stats: dict[str, Stat] = {}
83
+ for label, value, groups in _STAT_RE.findall(text.replace("&amp;", "&").replace("&lt;", "<").replace("&gt;", ">")):
84
+ details: dict[str, Value] = {}
85
+ for group in re.findall(r"\(([^()]*)\)", groups):
86
+ for item in group.split(";"):
87
+ m = _DETAIL_RE.fullmatch(item.strip())
88
+ if not m:
89
+ continue
90
+ low, high, key = m.groups()
91
+ number: Value = (int(low), int(high)) if high is not None else (
92
+ float(low) if "." in low else int(low))
93
+ details.setdefault(key, number)
94
+ stats.setdefault(_key(label), Stat(int(value), details))
95
+ return stats
96
+
97
+
98
+ #: SZS status names and the three-letter codes used in SPCs and by TPTP2T.
99
+ STATUS_CODES = {
100
+ "Theorem": "THM", "ContradictoryAxioms": "CAX", "CounterSatisfiable": "CSA",
101
+ "Unknown": "UNK", "Unsatisfiable": "UNS", "Satisfiable": "SAT", "Open": "OPN",
102
+ }
103
+
104
+ #: Logical forms: the first component of an SPC.
105
+ FORMS = {
106
+ "CNF": "clause normal form", "FOF": "first-order form",
107
+ "TF0": "typed first-order, monomorphic", "TF1": "typed first-order, polymorphic",
108
+ "TX0": "typed extended first-order, monomorphic", "TX1": "typed extended first-order, polymorphic",
109
+ "TH0": "typed higher-order, monomorphic", "TH1": "typed higher-order, polymorphic",
110
+ "NX0": "non-classical typed extended first-order, monomorphic",
111
+ "NX1": "non-classical typed extended first-order, polymorphic",
112
+ "NH0": "non-classical typed higher-order, monomorphic",
113
+ "NH1": "non-classical typed higher-order, polymorphic",
114
+ "DH0": "dynamic higher-order, monomorphic", "DH1": "dynamic higher-order, polymorphic",
115
+ }
116
+
117
+ _FLAGS = {
118
+ "PRP": "propositional", "EPR": "effectively propositional", "FHU": "finite Herbrand universe",
119
+ "RFO": "real first-order", "NEQ": "no equality", "SEQ": "some equality", "PEQ": "pure equality",
120
+ "EQU": "equality", "UEQ": "unit equality", "HRN": "Horn", "NHN": "non-Horn",
121
+ "ARI": "arithmetic", "NAR": "no arithmetic", "NDT": "no datatypes", "DAT": "datatypes",
122
+ }
123
+
124
+ #: The TPTP domains, by their three-letter code.
125
+ DOMAINS = {
126
+ "AGT": "Agents", "ALG": "General Algebra", "ANA": "Analysis", "ARI": "Arithmetic",
127
+ "BIO": "Biology", "BOO": "Boolean Algebra", "CAT": "Category Theory",
128
+ "COL": "Combinatory Logic", "COM": "Computing Theory", "CSR": "Commonsense Reasoning",
129
+ "DAT": "Data Structures", "FLD": "Field Theory", "GEG": "Geography", "GEO": "Geometry",
130
+ "GRA": "Graph Theory", "GRP": "Group Theory", "HAL": "Homological Algebra",
131
+ "HEN": "Henkin Models", "HWC": "Hardware Creation", "HWV": "Hardware Verification",
132
+ "ITP": "Interactive Theorem Proving", "KLE": "Kleene Algebra", "KRS": "Knowledge Representation",
133
+ "LAT": "Lattice Theory", "LCL": "Logic Calculi", "LDA": "LD-Algebras", "LIN": "Linear Algebra",
134
+ "MED": "Medicine", "MGT": "Management", "MSC": "Miscellaneous", "MVA": "Multi-valued Algebra",
135
+ "NLP": "Natural Language Processing", "NUM": "Number Theory", "NUN": "Number Theory (no arithmetic)",
136
+ "PHI": "Philosophy", "PLA": "Planning", "PRD": "Products", "PRO": "Processes",
137
+ "PUZ": "Puzzles", "QUA": "Quantales", "RAL": "Relation Algebra", "REL": "Relation Algebra",
138
+ "RNG": "Ring Theory", "ROB": "Robbins Algebra", "SCT": "Social Choice Theory",
139
+ "SET": "Set Theory", "SEU": "Set Theory (Mizar)", "SEV": "Set Theory (Henkin)",
140
+ "SWB": "Semantic Web", "SWC": "Software Creation", "SWV": "Software Verification",
141
+ "SWW": "Software Verification (Why3)", "SYN": "Syntactic", "SYO": "Syntactic (Henkin)",
142
+ "TOP": "Topology",
143
+ }
144
+
145
+
146
+ @dataclass(frozen=True)
147
+ class SPC:
148
+ """A Specialist Problem Class such as ``FOF_THM_RFO_SEQ``: the logical form, the status,
149
+ and a set of flags (``RFO``, ``SEQ``, ``NHN``, ``ARI`` ...)."""
150
+
151
+ text: str
152
+
153
+ @property
154
+ def parts(self) -> tuple[str, ...]:
155
+ return tuple(self.text.split("_"))
156
+
157
+ @property
158
+ def form(self) -> str:
159
+ return self.parts[0]
160
+
161
+ @property
162
+ def status(self) -> Optional[str]:
163
+ return self.parts[1] if len(self.parts) > 1 else None
164
+
165
+ @property
166
+ def flags(self) -> frozenset[str]:
167
+ return frozenset(self.parts[2:])
168
+
169
+ def describe(self) -> str:
170
+ """``'FOF_THM_RFO_SEQ'`` -> ``'first-order form, Theorem, real first-order, some equality'``."""
171
+ status = {v: k for k, v in STATUS_CODES.items()}
172
+ words = [FORMS.get(self.form, self.form)]
173
+ if self.status:
174
+ words.append(status.get(self.status, self.status))
175
+ words += [_FLAGS.get(f, f) for f in self.parts[2:]]
176
+ return ", ".join(words)
177
+
178
+ def __str__(self) -> str:
179
+ return self.text
180
+
181
+
182
+ # ---------------------------------------------------------------------------------
183
+ # Computed statistics
184
+ # ---------------------------------------------------------------------------------
185
+
186
+
187
+ @dataclass
188
+ class ComputedStats:
189
+ """Figures worked out from the formulae themselves.
190
+
191
+ Symbols are written ``name/arity``. For THF, where the parser cannot tell a predicate
192
+ from a function, ``predicates`` and ``functions`` are empty and ``atoms`` and
193
+ ``unit_formulae`` are ``None``;
194
+ use ``symbols``. Interpreted symbols (``$less``, ``$true`` ...) are counted under
195
+ ``defined_symbols`` rather than as predicates or functions.
196
+ """
197
+
198
+ dialects: tuple[str, ...] = ()
199
+ formulae: int = 0
200
+ roles: dict[str, int] = field(default_factory=dict)
201
+ unit_formulae: Optional[int] = 0
202
+ type_declarations: int = 0
203
+ atoms: Optional[int] = 0
204
+ equality_atoms: int = 0
205
+ symbols: tuple[str, ...] = ()
206
+ predicates: tuple[str, ...] = ()
207
+ functions: tuple[str, ...] = ()
208
+ constants: tuple[str, ...] = ()
209
+ defined_symbols: tuple[str, ...] = ()
210
+ user_types: tuple[str, ...] = ()
211
+ variables: int = 0
212
+ singleton_variables: int = 0
213
+ bound_variables: dict[str, int] = field(default_factory=dict)
214
+ max_formula_depth: int = 0
215
+ max_term_depth: int = 0
216
+ includes: tuple[str, ...] = ()
217
+ polymorphic: bool = False
218
+
219
+ def as_dict(self) -> dict:
220
+ return asdict(self)
221
+
222
+
223
+ _FORMULA_BINARY = {"=>", "<=", "<=>", "<~>", "~|", "~&", "-->"}
224
+ _EQUALITY = {"=", "!="}
225
+
226
+
227
+ class _Collector:
228
+ def __init__(self) -> None:
229
+ self.atoms = 0
230
+ self.equality = 0
231
+ self.predicates: dict[str, None] = {}
232
+ self.functions: dict[str, None] = {}
233
+ self.defined: dict[str, None] = {}
234
+ self.bound: Counter = Counter()
235
+ self.term_depth = 0
236
+ self.polymorphic = False
237
+
238
+ # ``formula`` is whether ``node`` stands where a formula is expected; returns its depth.
239
+ def visit(self, node: Node, formula: bool) -> int:
240
+ if isinstance(node, Function):
241
+ if not formula:
242
+ return self.term(node)
243
+ if node.name == "$ite" and node.args: # a conditional formula
244
+ return 1 + max(self.visit(a, True) for a in node.args)
245
+ self.atoms += 1
246
+ self._symbol(node, self.predicates)
247
+ for arg in node.args:
248
+ self.term(arg)
249
+ return 1
250
+ if isinstance(node, Variable):
251
+ if formula:
252
+ self.atoms += 1
253
+ return 1
254
+ if isinstance(node, Binary):
255
+ if node.op in _EQUALITY:
256
+ self.atoms += 1
257
+ self.equality += 1
258
+ self.term(node.left)
259
+ self.term(node.right)
260
+ return 1
261
+ if node.op in _FORMULA_BINARY:
262
+ return 1 + max(self.visit(node.left, True), self.visit(node.right, True))
263
+ return 1 + max(self.visit(node.left, formula), self.visit(node.right, formula))
264
+ if isinstance(node, NAry):
265
+ if node.op in ("|", "&"):
266
+ return 1 + max(self.visit(a, True) for a in node.args)
267
+ return 1 + max((self.visit(a, False) for a in node.args), default=0)
268
+ if isinstance(node, Unary):
269
+ return 1 + self.visit(node.arg, formula)
270
+ if isinstance(node, Quantified):
271
+ self.bound[node.quantifier] += len(node.variables)
272
+ if node.quantifier in ("!>", "?*"):
273
+ self.polymorphic = True
274
+ return 1 + self.visit(node.body, formula)
275
+ if isinstance(node, ModalAtom):
276
+ return 1 + max((self.visit(a, True) for a in node.args), default=0)
277
+ if isinstance(node, Let):
278
+ for definition in node.definitions:
279
+ self.visit(definition.right, formula)
280
+ return 1 + self.visit(node.body, formula)
281
+ if isinstance(node, Tuple):
282
+ return 1 + max((self.visit(a, formula) for a in node.items), default=0)
283
+ return 1 # FormulaData, ConnectiveTerm, numbers, distinct objects ...
284
+
285
+ def term(self, node: Node) -> int:
286
+ if isinstance(node, Function):
287
+ self._symbol(node, self.functions)
288
+ depth = 1 + max((self.term(a) for a in node.args), default=0)
289
+ elif isinstance(node, Binary) and node.op in _EQUALITY: # e.g. inside $ite
290
+ self.equality += 1
291
+ depth = 1 + max(self.term(node.left), self.term(node.right))
292
+ elif isinstance(node, (Quantified, Unary, NAry, Binary, Let)):
293
+ depth = self.visit(node, True)
294
+ else:
295
+ depth = 1
296
+ self.term_depth = max(self.term_depth, depth)
297
+ return depth
298
+
299
+ def _symbol(self, node: Function, table: dict[str, None]) -> None:
300
+ key = f"{node.name}/{len(node.args)}"
301
+ if node.name.startswith("$"):
302
+ self.defined[key] = None
303
+ elif not node.name.startswith('"'):
304
+ table[key] = None
305
+
306
+
307
+ def compute_stats(problem: TPTPFile) -> ComputedStats:
308
+ """Work out statistics for ``problem`` from its formulae.
309
+
310
+ Only the formulae actually in ``problem`` count, so parse with ``expand_includes=True``
311
+ to include the axioms; ``includes`` lists the include directives still unexpanded.
312
+ """
313
+ formulae = problem.formulae
314
+ result = ComputedStats(
315
+ dialects=tuple(dict.fromkeys(f.language for f in formulae)),
316
+ formulae=len(formulae),
317
+ roles=dict(Counter(f.role for f in formulae)),
318
+ includes=tuple(i.path for i in problem.includes),
319
+ symbols=tuple(str(s) for s in problem.symbols),
320
+ )
321
+ collector = _Collector()
322
+ higher_order = False
323
+ singletons = distinct = 0
324
+ user_types: dict[str, None] = {}
325
+ for f in formulae:
326
+ if f.role == "type" or isinstance(f.formula, Typing):
327
+ result.type_declarations += 1
328
+ if isinstance(f.formula, Typing):
329
+ text = str(f.formula.type)
330
+ if text.endswith("$tType"):
331
+ user_types[f.formula.atom] = None
332
+ if "!>" in text or text.count("$tType") > 1:
333
+ collector.polymorphic = True
334
+ continue
335
+ occurrences: Counter = Counter()
336
+ for node in walk(f.formula):
337
+ if isinstance(node, Variable) and node.index:
338
+ occurrences[node.index] += 1
339
+ elif isinstance(node, TypedVariable) and node.index:
340
+ occurrences[node.index] += 0
341
+ distinct += len(occurrences)
342
+ if f.language == "cnf":
343
+ singletons += sum(1 for n in occurrences.values() if n == 1)
344
+ if occurrences:
345
+ collector.bound["!"] += len(occurrences)
346
+ if f.language == "thf":
347
+ higher_order = True
348
+ before = collector.atoms
349
+ depth = _thf_depth(f.formula, collector)
350
+ collector.atoms = before
351
+ else:
352
+ atoms_before = collector.atoms
353
+ depth = collector.visit(f.formula, True)
354
+ if collector.atoms - atoms_before == 1:
355
+ result.unit_formulae += 1
356
+ result.max_formula_depth = max(result.max_formula_depth, depth)
357
+ result.variables = distinct
358
+ result.singleton_variables = singletons
359
+ result.bound_variables = dict(collector.bound)
360
+ result.max_term_depth = collector.term_depth
361
+ result.user_types = tuple(user_types)
362
+ result.polymorphic = collector.polymorphic
363
+ result.defined_symbols = tuple(collector.defined)
364
+ result.equality_atoms = collector.equality
365
+ if higher_order:
366
+ result.atoms = result.unit_formulae = None
367
+ else:
368
+ result.atoms = collector.atoms
369
+ result.predicates = tuple(collector.predicates)
370
+ result.functions = tuple(s for s in collector.functions if not s.endswith("/0"))
371
+ result.constants = tuple(s for s in collector.functions if s.endswith("/0"))
372
+ return result
373
+
374
+
375
+ def _thf_depth(node: Node, collector: _Collector) -> int:
376
+ """Formula depth of a THF formula, also counting its binders."""
377
+ if isinstance(node, Quantified):
378
+ collector.bound[node.quantifier] += len(node.variables)
379
+ if node.quantifier in ("!>", "?*"):
380
+ collector.polymorphic = True
381
+ return 1 + _thf_depth(node.body, collector)
382
+ if isinstance(node, Binary):
383
+ if node.op in _EQUALITY:
384
+ collector.equality += 1
385
+ return 1 + max(_thf_depth(node.left, collector), _thf_depth(node.right, collector))
386
+ if isinstance(node, NAry):
387
+ return 1 + max((_thf_depth(a, collector) for a in node.args), default=0)
388
+ if isinstance(node, Unary):
389
+ return 1 + _thf_depth(node.arg, collector)
390
+ if isinstance(node, Function) and node.name.startswith("$"):
391
+ collector.defined[f"{node.name}/{len(node.args)}"] = None
392
+ return 1
@@ -0,0 +1,231 @@
1
+ """Checking for new TPTP releases, and keeping the online cache in step with them.
2
+
3
+ The TPTP website serves only the current release, so files cached by
4
+ :class:`~thousandproblems.library.OnlineLibrary` go out of date when a new release comes
5
+ out. :func:`check_for_updates` asks tptp.org for the latest version, clears the online cache
6
+ if it holds an older one, and says whether a local library is behind.
7
+
8
+ The time of the last check is kept in ``state.json`` in the cache directory, and the
9
+ command line reminds you when it is more than :data:`CHECK_INTERVAL` old. Set
10
+ ``THOUSANDPROBLEMS_NO_UPDATE_CHECK=1`` to turn the reminder off.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import json
16
+ import os
17
+ import re
18
+ import shutil
19
+ import time
20
+ from dataclasses import dataclass, field
21
+ from pathlib import Path
22
+ from typing import Optional, Union
23
+
24
+ from .library import DEFAULT_URL, default_cache_dir
25
+
26
+ __all__ = ["CHECK_INTERVAL", "UpdateReport", "check_for_updates", "check_due", "snooze",
27
+ "postpone", "detect_version", "online_cache_version"]
28
+
29
+ #: How long after a check the command line starts reminding you, in seconds.
30
+ CHECK_INTERVAL = 30 * 24 * 3600
31
+ #: How long answering "no" to the reminder keeps it quiet, in seconds.
32
+ POSTPONE = 24 * 3600
33
+
34
+ _VERSION_RE = re.compile(r"v(\d+\.\d+\.\d+)")
35
+ _FILE_LINE_RE = re.compile(r"^% File\s*:.*?TPTP v(\d+\.\d+\.\d+)", re.MULTILINE)
36
+
37
+
38
+ def _key(version: str) -> tuple[int, ...]:
39
+ return tuple(int(x) for x in version.lstrip("v").split("."))
40
+
41
+
42
+ # ---------------------------------------------------------------------------------
43
+ # State
44
+ # ---------------------------------------------------------------------------------
45
+
46
+
47
+ def _state_file(cache: Optional[Path] = None) -> Path:
48
+ return (cache or default_cache_dir()) / "state.json"
49
+
50
+
51
+ def load_state(cache: Optional[Path] = None) -> dict:
52
+ try:
53
+ data = json.loads(_state_file(cache).read_text(encoding="utf-8"))
54
+ return data if isinstance(data, dict) else {}
55
+ except (OSError, ValueError):
56
+ return {}
57
+
58
+
59
+ def save_state(state: dict, cache: Optional[Path] = None) -> None:
60
+ path = _state_file(cache)
61
+ try:
62
+ path.parent.mkdir(parents=True, exist_ok=True)
63
+ temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
64
+ temporary.write_text(json.dumps(state, indent=2), encoding="utf-8")
65
+ os.replace(temporary, path)
66
+ except OSError:
67
+ pass # an unwritable cache only means being reminded again
68
+
69
+
70
+ def check_due(now: Optional[float] = None, cache: Optional[Path] = None) -> Optional[int]:
71
+ """Days since the last check if a reminder is due, else ``None``.
72
+
73
+ The clock starts the first time this is called, so a new installation is not
74
+ reminded straight away.
75
+ """
76
+ if os.environ.get("THOUSANDPROBLEMS_NO_UPDATE_CHECK"):
77
+ return None
78
+ now = time.time() if now is None else now
79
+ state = load_state(cache)
80
+ if "last_check" not in state:
81
+ state["last_check"] = now
82
+ save_state(state, cache)
83
+ return None
84
+ if now < state.get("quiet_until", 0):
85
+ return None
86
+ age = now - state["last_check"]
87
+ return int(age // 86400) if age >= CHECK_INTERVAL else None
88
+
89
+
90
+ def snooze(now: Optional[float] = None, cache: Optional[Path] = None, seconds: float = CHECK_INTERVAL) -> None:
91
+ """Don't remind again for ``seconds`` (default: 30 days)."""
92
+ now = time.time() if now is None else now
93
+ state = load_state(cache)
94
+ state["quiet_until"] = now + seconds
95
+ save_state(state, cache)
96
+
97
+
98
+ def postpone(now: Optional[float] = None, cache: Optional[Path] = None) -> None:
99
+ """Don't remind again for a day (the answer "no")."""
100
+ snooze(now, cache, POSTPONE)
101
+
102
+
103
+ # ---------------------------------------------------------------------------------
104
+ # Versions
105
+ # ---------------------------------------------------------------------------------
106
+
107
+
108
+ def detect_version(source: Union[str, os.PathLike]) -> Optional[str]:
109
+ """The TPTP version of a local library, e.g. ``'10.0.0'``, from its folder or tarball
110
+ name (``TPTP-v10.0.0``) or else from the ``% File`` line of one of its problems."""
111
+ path = Path(source)
112
+ match = _VERSION_RE.search(path.name)
113
+ if match:
114
+ return match[1]
115
+ if path.is_dir():
116
+ for problem in sorted((path / "Problems").glob("*/*.p"))[:5]:
117
+ try:
118
+ with open(problem, encoding="utf-8", errors="replace") as handle:
119
+ found = _FILE_LINE_RE.search(handle.read(4096))
120
+ except OSError:
121
+ continue
122
+ if found:
123
+ return found[1]
124
+ return None
125
+
126
+
127
+ def _host_dir(cache: Path, base_url: str = DEFAULT_URL) -> Path:
128
+ import urllib.parse
129
+ host = re.sub(r"[^A-Za-z0-9._-]+", "_", urllib.parse.urlsplit(base_url).netloc or "server")
130
+ return cache / host
131
+
132
+
133
+ def online_cache_version(cache: Optional[Path] = None, base_url: str = DEFAULT_URL) -> Optional[str]:
134
+ """The TPTP version the online cache was filled from, or ``None`` if it is empty or unknown.
135
+
136
+ It is recorded in a ``VERSION`` file; a cache without one (from before versions were
137
+ recorded) is judged by the ``% File`` line of a cached problem.
138
+ """
139
+ folder = _host_dir(cache or default_cache_dir(), base_url)
140
+ try:
141
+ recorded = (folder / "VERSION").read_text(encoding="utf-8").strip()
142
+ if recorded:
143
+ return recorded
144
+ except OSError:
145
+ pass
146
+ for problem in sorted((folder / "Problems").glob("*/*.p"))[:5]:
147
+ try:
148
+ found = _FILE_LINE_RE.search(problem.read_text(encoding="utf-8", errors="replace")[:4096])
149
+ except OSError:
150
+ continue
151
+ if found:
152
+ return found[1]
153
+ return None
154
+
155
+
156
+ @dataclass
157
+ class UpdateReport:
158
+ """What :func:`check_for_updates` found."""
159
+
160
+ latest: str
161
+ cache_version: Optional[str] = None
162
+ cache_cleared: int = 0 # files removed from the online cache
163
+ local_path: Optional[str] = None
164
+ local_version: Optional[str] = None
165
+ notes: list[str] = field(default_factory=list)
166
+
167
+ @property
168
+ def local_outdated(self) -> bool:
169
+ return bool(self.local_version) and _key(self.local_version) < _key(self.latest)
170
+
171
+ def summary(self) -> str:
172
+ lines = [f"latest TPTP release : v{self.latest}"]
173
+ if self.cache_cleared:
174
+ lines.append(f"online cache : held v{self.cache_version or '?'}; cleared "
175
+ f"{self.cache_cleared} files, so problems are fetched again from v{self.latest}")
176
+ else:
177
+ lines.append(f"online cache : {'v' + self.cache_version if self.cache_version else 'empty'}"
178
+ + (" (up to date)" if self.cache_version == self.latest else ""))
179
+ if self.local_path:
180
+ if self.local_version is None:
181
+ lines.append(f"local library : {self.local_path} (version unknown)")
182
+ elif self.local_outdated:
183
+ lines.append(f"local library : {self.local_path} is v{self.local_version}; "
184
+ f"get v{self.latest} with 'thousandproblems download'")
185
+ else:
186
+ lines.append(f"local library : {self.local_path} is v{self.local_version} (up to date)")
187
+ lines += self.notes
188
+ return "\n".join(lines)
189
+
190
+
191
+ def check_for_updates(local: Union[None, str, os.PathLike] = None, *, cache: Optional[Path] = None,
192
+ base_url: str = DEFAULT_URL, distribution_url: Optional[str] = None,
193
+ now: Optional[float] = None) -> UpdateReport:
194
+ """Look up the latest TPTP release and bring the online cache in line with it.
195
+
196
+ Cached downloads from an older release (or of unknown release) are deleted, since the
197
+ website now serves the new one. ``local`` is a local library to compare. The check is
198
+ recorded, which resets the reminder. Raises
199
+ :class:`~thousandproblems.library.LibraryError` if tptp.org cannot be reached.
200
+ """
201
+ from .download import DISTRIBUTION_URL, latest_version
202
+
203
+ cache = cache or default_cache_dir()
204
+ latest = latest_version(distribution_url or DISTRIBUTION_URL)
205
+ report = UpdateReport(latest)
206
+
207
+ folder = _host_dir(cache, base_url)
208
+ report.cache_version = online_cache_version(cache, base_url)
209
+ cached = [p for p in folder.rglob("*") if p.is_file() and p.name != "VERSION"] if folder.is_dir() else []
210
+ if cached and report.cache_version != latest:
211
+ for sub in ("Problems", "Axioms"):
212
+ shutil.rmtree(folder / sub, ignore_errors=True)
213
+ report.cache_cleared = sum(1 for p in cached if not p.exists())
214
+ leftover = [p for p in cached if p.exists()]
215
+ if leftover:
216
+ report.notes.append(f"note: {len(leftover)} other files in {folder} were left alone")
217
+ try:
218
+ folder.mkdir(parents=True, exist_ok=True)
219
+ (folder / "VERSION").write_text(latest + "\n", encoding="utf-8")
220
+ except OSError:
221
+ pass
222
+
223
+ if local is not None:
224
+ report.local_path = str(local)
225
+ report.local_version = detect_version(local)
226
+
227
+ state = load_state(cache)
228
+ state.update(last_check=time.time() if now is None else now, latest_version=latest)
229
+ state.pop("quiet_until", None)
230
+ save_state(state, cache)
231
+ return report