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,498 @@
1
+ """Fetch problems from a TPTP library: an unpacked folder, a tarball, or the TPTP website.
2
+
3
+ >>> import thousandproblems as tptp
4
+ >>> problem = tptp.fetch_problem("SET001-1", "/data/TPTP-v9.0.0") # doctest: +SKIP
5
+ >>> problem = tptp.fetch_problem("SET001-1", "/data/TPTP-v9.0.0.tgz") # doctest: +SKIP
6
+ >>> problem = tptp.fetch_problem("SET001-1") # doctest: +SKIP
7
+
8
+ All three understand the standard layout, in which problem ``SET001-1`` lives at
9
+ ``Problems/SET/SET001-1.p`` and includes such as ``include('Axioms/SET001-0.ax')`` are
10
+ relative to the library root::
11
+
12
+ TPTP-v9.0.0/
13
+ Problems/SET/SET001-1.p
14
+ Axioms/SET001-0.ax
15
+
16
+ Use :func:`open_library` to get a :class:`Library` when you want to read several
17
+ problems, and :func:`fetch_problem` for a single one. With no source given, the folder
18
+ named by the ``TPTP`` environment variable is used if there is one, and the website
19
+ otherwise.
20
+
21
+ Online access
22
+ -------------
23
+ The website allows only a few requests per minute (at the time of writing, 6), so
24
+ the online library fetches a problem *together with the axiom files it includes* in
25
+ one request, and keeps everything it downloads in a cache directory
26
+ (``$THOUSANDPROBLEMS_CACHE``, or the platform's usual cache location). Reading a problem
27
+ twice, or an axiom file shared by several problems, costs one request. If the server
28
+ refuses a request for going too fast, :class:`RateLimited` is raised, with the time
29
+ to wait; nothing is retried automatically. Only the current release is available
30
+ online; for a particular version, download its tarball and open that.
31
+
32
+ Only the standard library is used, and nothing in this module is imported until you
33
+ ask for it.
34
+ """
35
+
36
+ from __future__ import annotations
37
+
38
+ import io
39
+ import os
40
+ import posixpath
41
+ import re
42
+ import sys
43
+ import tarfile
44
+ import urllib.error
45
+ import urllib.parse
46
+ import urllib.request
47
+ from pathlib import Path
48
+ from typing import Optional, Union
49
+
50
+ from .nodes import AnnotatedFormula, ParseError, TPTPFile, _error_at, _symbol_table
51
+
52
+ __all__ = [
53
+ "DirectoryLibrary", "Library", "LibraryError", "OnlineLibrary", "ProblemNotFound",
54
+ "RateLimited", "TarballLibrary", "fetch_problem", "open_library",
55
+ ]
56
+
57
+ DEFAULT_URL = "https://seetptp.tptp.org"
58
+
59
+ #: ``SET001-1``, ``SEU140+3``, ``SYN000_1``, ``SYO000^1``, ``SYN000-1.002``: three
60
+ #: capitals for the domain, three digits, then whatever the naming scheme allows.
61
+ _NAME_RE = re.compile(r"[A-Z]{3}[0-9]{3}[A-Za-z0-9_+\-^=#.]*")
62
+
63
+
64
+ class LibraryError(Exception):
65
+ """A problem with reaching or reading a TPTP library."""
66
+
67
+
68
+ class ProblemNotFound(LibraryError, FileNotFoundError):
69
+ """The library has no such problem or file."""
70
+
71
+
72
+ class RateLimited(LibraryError):
73
+ """The TPTP server refused a request for coming too fast.
74
+
75
+ ``retry_after`` is the number of seconds the server asked us to wait, if it said.
76
+ """
77
+
78
+ def __init__(self, message: str, retry_after: Optional[float] = None):
79
+ super().__init__(message)
80
+ self.retry_after = retry_after
81
+
82
+
83
+ # ---------------------------------------------------------------------------------
84
+ # Names and paths
85
+ # ---------------------------------------------------------------------------------
86
+
87
+
88
+ def problem_path(name: str) -> str:
89
+ """The library path of a problem: ``'SET001-1'`` -> ``'Problems/SET/SET001-1.p'``."""
90
+ stem = name[:-2] if name.endswith(".p") else name
91
+ if not _NAME_RE.fullmatch(stem) or ".." in stem:
92
+ raise ValueError(
93
+ f"{name!r} is not a TPTP problem name (expected something like 'SET001-1' or 'SEU140+3')")
94
+ return f"Problems/{stem[:3]}/{stem}.p"
95
+
96
+
97
+ def _clean(path: str) -> Optional[str]:
98
+ """A library-relative path in normal form, or None if it points outside the library."""
99
+ path = path.replace("\\", "/")
100
+ if "\x00" in path or path.startswith("/") or re.match(r"[A-Za-z]:", path):
101
+ return None
102
+ norm = posixpath.normpath(path)
103
+ if norm == "." or norm == ".." or norm.startswith("../"):
104
+ return None
105
+ return norm
106
+
107
+
108
+ def _decode(data: bytes) -> str:
109
+ return data.decode("utf-8", errors="replace")
110
+
111
+
112
+ # ---------------------------------------------------------------------------------
113
+ # Libraries
114
+ # ---------------------------------------------------------------------------------
115
+
116
+
117
+ class Library:
118
+ """A TPTP library. Paths are relative to its root, with forward slashes."""
119
+
120
+ #: Shown in error messages and set as the ``filename`` of what is parsed.
121
+ label = "TPTP"
122
+
123
+ def read_optional(self, path: str) -> Optional[str]:
124
+ """The text of the file at ``path``, or ``None`` if the library has no such file."""
125
+ raise NotImplementedError
126
+
127
+ def read(self, path: str) -> str:
128
+ """The text of the file at ``path``; raises :class:`ProblemNotFound` if absent."""
129
+ clean = _clean(path)
130
+ text = None if clean is None else self.read_optional(clean)
131
+ if text is None:
132
+ raise ProblemNotFound(f"{path!r} is not in {self.label}")
133
+ return text
134
+
135
+ def problem_text(self, name: str) -> str:
136
+ """The source of problem ``name``, e.g. ``'SET001-1'``."""
137
+ try:
138
+ return self.read(problem_path(name))
139
+ except ProblemNotFound:
140
+ raise ProblemNotFound(f"problem {name!r} is not in {self.label}") from None
141
+
142
+ def problem(self, name: str, *, expand_includes: bool = False) -> TPTPFile:
143
+ """Parse problem ``name``.
144
+
145
+ With ``expand_includes``, each ``include`` is replaced by the formulae it selects,
146
+ as in :func:`thousandproblems.parse_file`. Include paths are read relative to the
147
+ library root, then relative to the including file.
148
+ """
149
+ from . import parse
150
+
151
+ path = problem_path(name)
152
+ try:
153
+ text = self.read(path)
154
+ except ProblemNotFound:
155
+ raise ProblemNotFound(f"problem {name!r} is not in {self.label}") from None
156
+ parsed = parse(text, path)
157
+ return self._expand(path, text, parsed, ()) if expand_includes else parsed
158
+
159
+ def problem_names(self, domain: Optional[str] = None) -> list[str]:
160
+ """The names of the problems in the library, sorted; optionally only one domain."""
161
+ raise NotImplementedError(f"{type(self).__name__} cannot list its problems")
162
+
163
+ def problem_files(self, name: str) -> dict[str, str]:
164
+ """Problem ``name`` and every file it includes, directly or not, as
165
+ ``{library path: text}`` with the problem first, e.g.
166
+ ``{'Problems/SET/SET001-1.p': ..., 'Axioms/SET001-0.ax': ...}``.
167
+
168
+ Includes are found the same way as by :meth:`problem`; one that cannot be found
169
+ raises :class:`ProblemNotFound`.
170
+ """
171
+ from . import parse
172
+
173
+ path = problem_path(name)
174
+ try:
175
+ files = {path: self.read(path)}
176
+ except ProblemNotFound:
177
+ raise ProblemNotFound(f"problem {name!r} is not in {self.label}") from None
178
+ todo = [path]
179
+ while todo:
180
+ current = todo.pop()
181
+ for item in parse(files[current], current).includes:
182
+ for candidate in (item.path, posixpath.join(posixpath.dirname(current), item.path)):
183
+ clean = _clean(candidate)
184
+ if clean is None:
185
+ continue
186
+ if clean in files:
187
+ break
188
+ text = self.read_optional(clean)
189
+ if text is not None:
190
+ files[clean] = text
191
+ todo.append(clean)
192
+ break
193
+ else:
194
+ raise ProblemNotFound(f"{current} includes {item.path!r}, which is not in {self.label}")
195
+ return files
196
+
197
+ def close(self) -> None:
198
+ """Release any open files."""
199
+
200
+ def __enter__(self) -> "Library":
201
+ return self
202
+
203
+ def __exit__(self, *exc) -> None:
204
+ self.close()
205
+
206
+ def __repr__(self) -> str:
207
+ return f"<{type(self).__name__} {self.label}>"
208
+
209
+ def _expand(self, path: str, text: str, parsed: TPTPFile, stack: tuple[str, ...]) -> TPTPFile:
210
+ from . import parse
211
+
212
+ inputs = []
213
+ for item in parsed.inputs:
214
+ if isinstance(item, AnnotatedFormula):
215
+ inputs.append(item)
216
+ continue
217
+
218
+ def fail(message: str, item=item) -> ParseError:
219
+ return _error_at(message, text, item.line, 1, path)
220
+
221
+ candidates = []
222
+ for candidate in (item.path, posixpath.join(posixpath.dirname(path), item.path)):
223
+ clean = _clean(candidate)
224
+ if clean is not None and clean not in candidates:
225
+ candidates.append(clean)
226
+ target = body = None
227
+ for candidate in candidates:
228
+ body = self.read_optional(candidate)
229
+ if body is not None:
230
+ target = candidate
231
+ break
232
+ if target is None:
233
+ tried = ", ".join(candidates) or item.path
234
+ raise fail(f"included file {item.path!r} not found (tried {tried})")
235
+ if target == path or target in stack:
236
+ raise fail(f"circular include of {item.path!r}")
237
+ child = parse(body, target)
238
+ formulae = self._expand(target, body, child, (*stack, path)).formulae
239
+ if isinstance(item.selection, tuple):
240
+ selected = [f for f in formulae if f.name in item.selection]
241
+ missing = set(item.selection) - {f.name for f in selected}
242
+ if missing:
243
+ raise fail(f"{item.path!r} has no formulae named {sorted(missing)}")
244
+ formulae = tuple(selected)
245
+ inputs.extend(formulae)
246
+ return TPTPFile(tuple(inputs), parsed.comments, parsed.filename,
247
+ _symbol_table(i for i in inputs if isinstance(i, AnnotatedFormula)))
248
+
249
+
250
+ class DirectoryLibrary(Library):
251
+ """An unpacked TPTP distribution, e.g. ``TPTP-v9.0.0/`` (the folder that holds ``Problems``)."""
252
+
253
+ def __init__(self, root: Union[str, os.PathLike]):
254
+ self.root = Path(root)
255
+ if not (self.root / "Problems").is_dir():
256
+ raise LibraryError(
257
+ f"{str(self.root)!r} does not look like a TPTP library: it has no 'Problems' folder. "
258
+ "Point at the folder that contains Problems/ and Axioms/.")
259
+ self.label = str(self.root)
260
+
261
+ def read_optional(self, path: str) -> Optional[str]:
262
+ clean = _clean(path)
263
+ if clean is None:
264
+ return None
265
+ file = self.root / clean
266
+ try:
267
+ return file.read_text(encoding="utf-8", errors="replace") if file.is_file() else None
268
+ except OSError:
269
+ return None
270
+
271
+ def problem(self, name: str, *, expand_includes: bool = False) -> TPTPFile:
272
+ from . import parse_file
273
+
274
+ file = self.root / problem_path(name)
275
+ if not file.is_file():
276
+ raise ProblemNotFound(f"problem {name!r} is not in {self.label}")
277
+ return parse_file(file, expand_includes=expand_includes, tptp_root=self.root)
278
+
279
+ def problem_names(self, domain: Optional[str] = None) -> list[str]:
280
+ pattern = f"{domain}/*.p" if domain else "*/*.p"
281
+ return sorted(p.stem for p in (self.root / "Problems").glob(pattern))
282
+
283
+
284
+ class TarballLibrary(Library):
285
+ """A TPTP distribution tarball (``.tar``, ``.tgz``, ``.tar.gz``, ``.tar.bz2``, ``.tar.xz``).
286
+
287
+ The archive may have a top-level folder such as ``TPTP-v9.0.0/``, or none.
288
+
289
+ The first lookup reads the whole archive to index it, which takes a while for the
290
+ full distribution when it is compressed; after that each lookup seeks to its file,
291
+ which in a compressed archive means decompressing up to that point again. For
292
+ heavy use, unpack the tarball and use :class:`DirectoryLibrary`.
293
+ """
294
+
295
+ def __init__(self, path: Union[str, os.PathLike]):
296
+ self.path = Path(path)
297
+ if not self.path.is_file():
298
+ raise FileNotFoundError(f"no such tarball: {str(self.path)!r}")
299
+ self.label = str(self.path)
300
+ self._tar: Optional[tarfile.TarFile] = None
301
+ self._index: Optional[dict[str, tarfile.TarInfo]] = None
302
+
303
+ def _members(self) -> dict[str, tarfile.TarInfo]:
304
+ if self._index is not None:
305
+ return self._index
306
+ try:
307
+ self._tar = tarfile.open(self.path, "r:*")
308
+ files = {}
309
+ for member in self._tar:
310
+ if member.isfile():
311
+ files[member.name[2:] if member.name.startswith("./") else member.name] = member
312
+ except (tarfile.TarError, OSError, EOFError) as e:
313
+ raise LibraryError(f"cannot read {self.label}: {e}") from e
314
+ prefix = None
315
+ for name in files:
316
+ parts = name.split("/")
317
+ if "Problems" in parts[:-1]:
318
+ prefix = "/".join(parts[:parts.index("Problems")])
319
+ break
320
+ if prefix is None:
321
+ raise LibraryError(f"{self.label} has no 'Problems' folder; is it a TPTP distribution?")
322
+ cut = len(prefix) + 1 if prefix else 0
323
+ self._index = {name[cut:]: m for name, m in files.items() if name.startswith(prefix + "/" if prefix else "")}
324
+ return self._index
325
+
326
+ def read_optional(self, path: str) -> Optional[str]:
327
+ member = self._members().get(path)
328
+ if member is None:
329
+ return None
330
+ handle = self._tar.extractfile(member)
331
+ if handle is None:
332
+ return None
333
+ with handle:
334
+ return _decode(handle.read())
335
+
336
+ def problem_names(self, domain: Optional[str] = None) -> list[str]:
337
+ names = []
338
+ for path in self._members():
339
+ parts = path.split("/")
340
+ if len(parts) == 3 and parts[0] == "Problems" and parts[2].endswith(".p"):
341
+ if domain is None or parts[1] == domain:
342
+ names.append(parts[2][:-2])
343
+ return sorted(names)
344
+
345
+ def close(self) -> None:
346
+ if self._tar is not None:
347
+ self._tar.close()
348
+ self._tar = self._index = None
349
+
350
+
351
+ def default_cache_dir() -> Path:
352
+ """Where downloads are kept unless told otherwise."""
353
+ if os.environ.get("THOUSANDPROBLEMS_CACHE"):
354
+ return Path(os.environ["THOUSANDPROBLEMS_CACHE"])
355
+ if sys.platform == "darwin":
356
+ return Path.home() / "Library" / "Caches" / "thousandproblems"
357
+ if sys.platform == "win32":
358
+ return Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local")) / "thousandproblems" / "Cache"
359
+ return Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") / "thousandproblems"
360
+
361
+
362
+ class OnlineLibrary(Library):
363
+ """The current TPTP release, fetched over HTTP from the TPTP website.
364
+
365
+ :param base_url: the server; the default is the TPTP project's own.
366
+ :param cache: ``True`` (default) to keep downloads in :func:`default_cache_dir`,
367
+ ``False`` to keep them in memory only, or a directory to use as the cache.
368
+ :param timeout: seconds to wait for the server.
369
+ """
370
+
371
+ def __init__(self, base_url: str = DEFAULT_URL, *, cache: Union[bool, str, os.PathLike] = True,
372
+ timeout: float = 30.0):
373
+ self.base_url = base_url.rstrip("/")
374
+ self.timeout = timeout
375
+ self.label = self.base_url
376
+ if cache is True:
377
+ cache = default_cache_dir()
378
+ host = re.sub(r"[^A-Za-z0-9._-]+", "_", urllib.parse.urlsplit(self.base_url).netloc or "server")
379
+ self.cache_dir: Optional[Path] = Path(cache) / host if cache else None
380
+ self._memory: dict[str, str] = {}
381
+
382
+ # The server hands out a .tgz holding the requested file and, for a problem, every
383
+ # axiom file it includes, laid out from the library root.
384
+ def _download_url(self, path: str) -> str:
385
+ return f"{self.base_url}/download/TPTPWorld/TPTP/{urllib.parse.quote(path, safe='/+')}"
386
+
387
+ def _fetch(self, path: str) -> Optional[dict[str, str]]:
388
+ from . import __version__
389
+
390
+ request = urllib.request.Request(
391
+ self._download_url(path), headers={"User-Agent": f"thousandproblems/{__version__}"})
392
+ try:
393
+ with urllib.request.urlopen(request, timeout=self.timeout) as response:
394
+ data = response.read()
395
+ except urllib.error.HTTPError as e:
396
+ e.close()
397
+ if e.code == 429:
398
+ retry = e.headers.get("Retry-After")
399
+ wait = float(retry) if retry and retry.replace(".", "", 1).isdigit() else None
400
+ hint = f"; wait {wait:g} s" if wait else "; the TPTP server allows only a few requests a minute"
401
+ raise RateLimited(f"the TPTP server is rate limiting requests{hint}", wait) from None
402
+ if e.code == 404:
403
+ return None
404
+ raise LibraryError(f"{self._download_url(path)}: HTTP {e.code} {e.reason}") from e
405
+ except (urllib.error.URLError, OSError) as e:
406
+ raise LibraryError(f"cannot reach {self.base_url}: {getattr(e, 'reason', e)}") from e
407
+ if data[:2] != b"\x1f\x8b": # a missing file comes back as an HTML page, status 200
408
+ return None
409
+ files = {}
410
+ try:
411
+ with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as tar:
412
+ for member in tar:
413
+ if not member.isfile():
414
+ continue
415
+ name = member.name[2:] if member.name.startswith("./") else member.name
416
+ # the requested file is stored under its bare name
417
+ key = path if "/" not in name and name == posixpath.basename(path) else name
418
+ clean = _clean(key)
419
+ if clean is not None:
420
+ files[clean] = _decode(tar.extractfile(member).read())
421
+ except (tarfile.TarError, EOFError) as e:
422
+ raise LibraryError(f"unreadable download for {path!r}: {e}") from e
423
+ return files if path in files else None
424
+
425
+ def _cache_file(self, path: str) -> Optional[Path]:
426
+ return self.cache_dir / path if self.cache_dir else None
427
+
428
+ def read_optional(self, path: str) -> Optional[str]:
429
+ if path in self._memory:
430
+ return self._memory[path]
431
+ cached = self._cache_file(path)
432
+ if cached is not None:
433
+ try:
434
+ text = _decode(cached.read_bytes())
435
+ self._memory[path] = text
436
+ return text
437
+ except OSError:
438
+ pass
439
+ files = self._fetch(path)
440
+ if files is None:
441
+ return None
442
+ for name, text in files.items():
443
+ self._memory[name] = text
444
+ target = self._cache_file(name)
445
+ if target is not None:
446
+ try:
447
+ target.parent.mkdir(parents=True, exist_ok=True)
448
+ temporary = target.with_name(f".{target.name}.{os.getpid()}.tmp")
449
+ temporary.write_bytes(text.encode("utf-8")) # bytes: no newline translation on Windows
450
+ os.replace(temporary, target)
451
+ except OSError:
452
+ pass # a cache that can't be written is not an error
453
+ return files[path]
454
+
455
+ def problem_names(self, domain: Optional[str] = None) -> list[str]:
456
+ raise NotImplementedError("the TPTP website cannot be listed; use a local copy of the library")
457
+
458
+
459
+ # ---------------------------------------------------------------------------------
460
+ # Entry points
461
+ # ---------------------------------------------------------------------------------
462
+
463
+
464
+ def open_library(source: Union[None, str, os.PathLike, Library] = None) -> Library:
465
+ """A :class:`Library` for ``source``.
466
+
467
+ ``source`` can be a folder, a tarball, an ``http(s)://`` URL of a TPTP server, an
468
+ existing :class:`Library` (returned as is), or ``None`` for the folder named by the
469
+ ``TPTP`` environment variable if that is set, else the TPTP website.
470
+ """
471
+ if isinstance(source, Library):
472
+ return source
473
+ if source is None:
474
+ root = os.environ.get("TPTP")
475
+ return DirectoryLibrary(root) if root and Path(root).is_dir() else OnlineLibrary()
476
+ text = os.fspath(source)
477
+ if re.match(r"https?://", text):
478
+ return OnlineLibrary(text)
479
+ path = Path(text)
480
+ if path.is_dir():
481
+ return DirectoryLibrary(path)
482
+ if path.is_file():
483
+ return TarballLibrary(path)
484
+ raise FileNotFoundError(f"no such TPTP library (folder or tarball): {text!r}")
485
+
486
+
487
+ def fetch_problem(name: str, source: Union[None, str, os.PathLike, Library] = None, *,
488
+ expand_includes: bool = False) -> TPTPFile:
489
+ """Parse problem ``name`` (e.g. ``'SET001-1'``) from a TPTP library; see :func:`open_library`.
490
+
491
+ A library opened here is closed again before returning.
492
+ """
493
+ library = open_library(source)
494
+ try:
495
+ return library.problem(name, expand_includes=expand_includes)
496
+ finally:
497
+ if library is not source:
498
+ library.close()