docattest 0.1.0__py3-none-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.
Files changed (66) hide show
  1. docattest/__init__.py +10 -0
  2. docattest/__main__.py +6 -0
  3. docattest/bin/docattest.exe +0 -0
  4. docattest/launcher.py +351 -0
  5. docattest-0.1.0.dist-info/METADATA +440 -0
  6. docattest-0.1.0.dist-info/RECORD +66 -0
  7. docattest-0.1.0.dist-info/WHEEL +4 -0
  8. docattest-0.1.0.dist-info/entry_points.txt +3 -0
  9. docattest-0.1.0.dist-info/licenses/LICENSE +21 -0
  10. docattest-0.1.0.dist-info/top_level.txt +2 -0
  11. docattest_python/__init__.py +3 -0
  12. docattest_python/__main__.py +16 -0
  13. docattest_python/analysis/__init__.py +8 -0
  14. docattest_python/analysis/impact.py +240 -0
  15. docattest_python/analysis/modules.py +263 -0
  16. docattest_python/analysis/names.py +221 -0
  17. docattest_python/analysis/project.py +189 -0
  18. docattest_python/analysis/surfaces.py +272 -0
  19. docattest_python/attestations.py +83 -0
  20. docattest_python/errors.py +13 -0
  21. docattest_python/language.py +348 -0
  22. docattest_python/protocol/agents/claude.json +30 -0
  23. docattest_python/protocol/agents/cursor.json +19 -0
  24. docattest_python/protocol/agents/gemini.json +27 -0
  25. docattest_python/protocol/agents/index.json +3 -0
  26. docattest_python/protocol/core.json +4 -0
  27. docattest_python/protocol/platforms.json +40 -0
  28. docattest_python/protocol/schema/agent.json +162 -0
  29. docattest_python/protocol/schema/attestations.json +307 -0
  30. docattest_python/protocol/schema/kit.json +190 -0
  31. docattest_python/protocol/schema/language.json +162 -0
  32. docattest_python/protocol/schema/messages.json +68 -0
  33. docattest_python/protocol/schema/methods.json +412 -0
  34. docattest_python/protocol/schema/project.json +113 -0
  35. docattest_python/protocol/schema/results.json +249 -0
  36. docattest_python/server/__init__.py +2 -0
  37. docattest_python/server/params.py +134 -0
  38. docattest_python/server/server.py +297 -0
  39. docattest_python/session/__init__.py +2 -0
  40. docattest_python/session/continued.py +64 -0
  41. docattest_python/session/problems.py +225 -0
  42. docattest_python/session/running.py +348 -0
  43. docattest_python/session/session.py +119 -0
  44. docattest_python/session/settings.py +29 -0
  45. docattest_python/session/symbols.py +319 -0
  46. docattest_python/session/workspace.py +107 -0
  47. docattest_python/workers/__init__.py +2 -0
  48. docattest_python/workers/docattest_worker/__init__.py +5 -0
  49. docattest_python/workers/docattest_worker/asserts.py +111 -0
  50. docattest_python/workers/docattest_worker/cases.py +86 -0
  51. docattest_python/workers/docattest_worker/channel.py +42 -0
  52. docattest_python/workers/docattest_worker/environment.py +175 -0
  53. docattest_python/workers/docattest_worker/examples.py +62 -0
  54. docattest_python/workers/docattest_worker/facts.py +155 -0
  55. docattest_python/workers/docattest_worker/failures.py +83 -0
  56. docattest_python/workers/docattest_worker/fields.py +91 -0
  57. docattest_python/workers/docattest_worker/jobs.py +201 -0
  58. docattest_python/workers/docattest_worker/messages.py +179 -0
  59. docattest_python/workers/docattest_worker/named_facts.py +52 -0
  60. docattest_python/workers/docattest_worker/observables.py +365 -0
  61. docattest_python/workers/docattest_worker/sessions.py +169 -0
  62. docattest_python/workers/docattest_worker/values.py +63 -0
  63. docattest_python/workers/interpreter.py +137 -0
  64. docattest_python/workers/pool.py +272 -0
  65. docattest_python/workers/worker.py +126 -0
  66. docattest_python/workers/worker_process.py +160 -0
docattest/__init__.py ADDED
@@ -0,0 +1,10 @@
1
+ """docattest for Python projects: the ``docattest`` command.
2
+
3
+ This package is the launcher. It finds the docattest core it was installed with, tells it
4
+ how to start the Python adapter (``docattest_python``) and what command runs docattest in
5
+ this project, and replaces itself with the core (PROTOCOL.md, section 1, "Launchers").
6
+ """
7
+
8
+ from docattest_python import __version__
9
+
10
+ __all__ = ["__version__"]
docattest/__main__.py ADDED
@@ -0,0 +1,6 @@
1
+ """``python -m docattest``."""
2
+
3
+ from .launcher import main
4
+
5
+ if __name__ == "__main__":
6
+ main()
Binary file
docattest/launcher.py ADDED
@@ -0,0 +1,351 @@
1
+ """The ``docattest`` command of the Python package: a launcher for the docattest core.
2
+
3
+ The core is one binary for every language and knows nothing of how it was installed. This
4
+ launcher belongs to the language package. It hands the core two things in the environment
5
+ (PROTOCOL.md, section 1, "Launchers") and then becomes it (``exec``; on Windows, which has
6
+ no exec, it runs the core and exits with its code), so arguments, standard streams, signals
7
+ and the exit code are the core's own:
8
+
9
+ ``DOCATTEST_ADAPTER_PYTHON``
10
+ How to start this package's adapter: a JSON array, the program and its arguments.
11
+ ``DOCATTEST_COMMAND``
12
+ A shell command that runs docattest in this project; ``hooks install`` and ``agents
13
+ install`` write it down. ``{root}`` in it stands for the project root, which the core
14
+ spells as whoever will run the command spells it.
15
+
16
+ A variable that is already set is left alone. Only the standard library is imported, and
17
+ as little of it as will do: this runs before every docattest command.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ import os
23
+ import sys
24
+ from collections.abc import Callable, Mapping
25
+ from typing import TypedDict, cast
26
+
27
+ CORE_VARIABLE = "DOCATTEST_CORE"
28
+ ADAPTER_VARIABLE = "DOCATTEST_ADAPTER_PYTHON"
29
+ COMMAND_VARIABLE = "DOCATTEST_COMMAND"
30
+ # The core's own trace, which this launcher answers too: set to anything but nothing.
31
+ TRACE_VARIABLE = "DOCATTEST_TRACE"
32
+ # In the command, the project root: the core says how it is spelt where the command is written.
33
+ ROOT = "{root}"
34
+ # The commands that write the command down; only for them is it worked out.
35
+ WRITERS = ("hooks", "agents")
36
+
37
+ _HERE = os.path.dirname(os.path.abspath(__file__))
38
+
39
+
40
+ class Pin(TypedDict):
41
+ """``protocol/core.json``: the core this package was built for."""
42
+
43
+ version: str
44
+ protocol: int
45
+
46
+
47
+ class Platform(TypedDict):
48
+ """One platform a core is built for, in ``protocol/platforms.json``."""
49
+
50
+ os: str
51
+ cpu: str
52
+ rust: str
53
+ wheel: list[str]
54
+ binary: str
55
+
56
+
57
+ class Platforms(TypedDict):
58
+ """``protocol/platforms.json``: the platforms a core is built for, by ``<os>-<cpu>``."""
59
+
60
+ npmPackage: str
61
+ platforms: dict[str, Platform]
62
+
63
+
64
+ #: The environment, as finding the core reads it.
65
+ Environment = Mapping[str, str]
66
+ #: Asks a program for ``--version --json``; None when it does not answer.
67
+ AskCore = Callable[[str], str | None]
68
+ #: What a user with no core is told to do, given the platform's name.
69
+ Advice = Callable[[str], str]
70
+
71
+
72
+ def _protocol_file(name: str) -> object:
73
+ """A file of the package's copy of ``protocol/`` (written by ``sync_protocol.py``)."""
74
+ import json
75
+
76
+ with open(
77
+ os.path.join(os.path.dirname(_HERE), "docattest_python", "protocol", name), encoding="utf-8"
78
+ ) as f:
79
+ return json.load(f)
80
+
81
+
82
+ def pinned() -> Pin:
83
+ """The core this package was built for: its exact version and the protocol it speaks.
84
+ Copied from ``protocol/core.json`` when the package was built."""
85
+ return cast(Pin, _protocol_file("core.json"))
86
+
87
+
88
+ def remedy(version: str, platform: str, listed: list[str]) -> str:
89
+ """What a user with no core is told: why this installation has none, and the ways to get
90
+ one. ``listed`` are the platforms a wheel with a core exists for (``protocol/platforms.json``)."""
91
+ if platform not in listed:
92
+ return (
93
+ f"docattest brings a core for {', '.join(listed)}; there is none for {platform}. "
94
+ f"Build one from docattest's source (cargo build --release in its core/ directory) and "
95
+ f"set {CORE_VARIABLE} to it."
96
+ )
97
+ return (
98
+ f"A docattest wheel for {platform} carries the core as docattest/bin/docattest, and this "
99
+ f"installation has none: it was installed from source (a checkout, or a wheel built "
100
+ f"without the core). To fix it, install the wheel "
101
+ f"(pip install --force-reinstall --only-binary :all: docattest=={version}), "
102
+ f"or set {CORE_VARIABLE} to a docattest core {version}."
103
+ )
104
+
105
+
106
+ def platform_name(platform: str, arch: str) -> str:
107
+ """``<os>-<arch>`` in the names every package uses: ``darwin-arm64``, ``linux-x64``."""
108
+ system = "windows" if platform == "win32" else platform
109
+ cpu = arch.lower()
110
+ return f"{system}-{ {'x86_64': 'x64', 'amd64': 'x64', 'aarch64': 'arm64'}.get(cpu, cpu) }"
111
+
112
+
113
+ def _arch() -> str:
114
+ if hasattr(os, "uname"):
115
+ return os.uname().machine
116
+ return os.environ.get("PROCESSOR_ARCHITECTURE", "unknown")
117
+
118
+
119
+ def cache_directory(env: Environment, platform: str, home: str) -> str:
120
+ """docattest's own cache directory: ``DOCATTEST_CACHE``, else ``docattest`` in the
121
+ user's cache directory (``~/Library/Caches`` on macOS, ``%LOCALAPPDATA%`` on Windows,
122
+ ``$XDG_CACHE_HOME`` or ``~/.cache`` elsewhere)."""
123
+ if env.get("DOCATTEST_CACHE"):
124
+ return env["DOCATTEST_CACHE"]
125
+ if platform == "win32":
126
+ import ntpath
127
+
128
+ return ntpath.join(env.get("LOCALAPPDATA") or ntpath.join(home, "AppData", "Local"), "docattest")
129
+ import posixpath
130
+
131
+ if platform == "darwin":
132
+ return posixpath.join(home, "Library", "Caches", "docattest")
133
+ xdg = env.get("XDG_CACHE_HOME")
134
+ return posixpath.join(
135
+ xdg if xdg and posixpath.isabs(xdg) else posixpath.join(home, ".cache"), "docattest"
136
+ )
137
+
138
+
139
+ def cached_core(pin: Pin, env: Environment, platform: str, arch: str, home: str) -> str:
140
+ """Where a core of the pinned version lies in the shared cache."""
141
+ sep = "\\" if platform == "win32" else "/"
142
+ name = "docattest.exe" if platform == "win32" else "docattest"
143
+ parts = [
144
+ cache_directory(env, platform, home),
145
+ "core",
146
+ pin["version"],
147
+ platform_name(platform, arch),
148
+ name,
149
+ ]
150
+ return sep.join(parts)
151
+
152
+
153
+ def ask_core(core: str) -> str | None:
154
+ """``core --version --json``, or None when the program does not answer it."""
155
+ import subprocess
156
+
157
+ try:
158
+ done = subprocess.run([core, "--version", "--json"], capture_output=True, text=True, timeout=10)
159
+ except (OSError, subprocess.SubprocessError):
160
+ return None
161
+ return done.stdout if done.returncode == 0 else None
162
+
163
+
164
+ def _checked(core: str, pin: Pin, ask: AskCore) -> tuple[str | None, str | None]:
165
+ import json
166
+
167
+ not_a_core = (
168
+ None,
169
+ f"docattest: {CORE_VARIABLE} ({core}) is not a docattest core: it does not answer --version --json",
170
+ )
171
+ try:
172
+ told: object = json.loads(ask(core) or "")
173
+ except ValueError:
174
+ return not_a_core
175
+ if not isinstance(told, dict):
176
+ return not_a_core
177
+ answer = cast("dict[str, object]", told)
178
+ version, protocol = answer.get("version"), answer.get("protocol")
179
+ if not isinstance(version, str) or isinstance(protocol, bool) or not isinstance(protocol, (int, float)):
180
+ return not_a_core
181
+ if protocol != pin["protocol"]:
182
+ return None, (
183
+ f"docattest: {CORE_VARIABLE} ({core}) is core {version}, which speaks adapter protocol "
184
+ f"{protocol}; this package speaks protocol {pin['protocol']} (it was built for core {pin['version']})"
185
+ )
186
+ return core, None
187
+
188
+
189
+ class Machine:
190
+ """What finding the core reads of the machine it runs on: its environment, its operating
191
+ system as ``sys.platform`` names it, its CPU and its home directory. Each is this
192
+ machine's own unless given; the tests describe other machines."""
193
+
194
+ def __init__(
195
+ self,
196
+ env: Environment | None = None,
197
+ platform: str | None = None,
198
+ arch: str | None = None,
199
+ home: str | None = None,
200
+ ) -> None:
201
+ self.env = os.environ if env is None else env
202
+ self.platform = sys.platform if platform is None else platform
203
+ self.arch = _arch() if arch is None else arch
204
+ self.home = os.path.expanduser("~") if home is None else home
205
+
206
+
207
+ def find_core(
208
+ pin: Pin,
209
+ machine: Machine | None = None,
210
+ bundled: str | None = None,
211
+ ask: AskCore = ask_core,
212
+ advice: Advice | None = None,
213
+ ) -> tuple[str | None, str | None]:
214
+ """The core, in order of preference: ``DOCATTEST_CORE``; the binary the package brought
215
+ (a platform wheel ships it as ``docattest/bin/docattest``); the shared cache. The last
216
+ two are trusted without being run: the package brought the first itself, and the cache
217
+ path names the exact version. A core someone else points at is asked what protocol it
218
+ speaks, and refused when it is not this package's. Returns ``(core, error)``; when there
219
+ is no core at all, ``advice(platform name)`` is added to the error on a line of its own.
220
+
221
+ The npm launcher (``adapters/typescript/src/core-binary/locate.ts``) follows the same rules, so
222
+ that an npm install and a pip install on one machine can share one binary."""
223
+ machine = Machine() if machine is None else machine
224
+ given = machine.env.get(CORE_VARIABLE)
225
+ if given:
226
+ return _checked(given, pin, ask)
227
+ if bundled is None:
228
+ bundled = os.path.join(_HERE, "bin", "docattest.exe" if machine.platform == "win32" else "docattest")
229
+ if bundled and os.path.isfile(bundled):
230
+ return bundled, None
231
+ cached = cached_core(pin, machine.env, machine.platform, machine.arch, machine.home)
232
+ if os.path.isfile(cached):
233
+ return cached, None
234
+ return None, _no_core(pin, platform_name(machine.platform, machine.arch), bundled, cached, advice)
235
+
236
+
237
+ def _no_core(pin: Pin, name: str, bundled: str, cached: str, advice: Advice | None) -> str:
238
+ """The error when there is no core anywhere: every place it was looked for."""
239
+ brought = bundled or "it brought no binary for this platform"
240
+ told = "" if advice is None else "\n" + advice(name)
241
+ return (
242
+ f"docattest: no docattest core {pin['version']} for {name}. Looked in: "
243
+ f"{CORE_VARIABLE} (not set); this package ({brought}); the shared cache ({cached}){told}"
244
+ )
245
+
246
+
247
+ def _platform_names() -> list[str]:
248
+ """The platforms a wheel with a core exists for."""
249
+ return list(cast(Platforms, _protocol_file("platforms.json"))["platforms"])
250
+
251
+
252
+ def adapter_command() -> list[str]:
253
+ """This interpreter, running the adapter that was installed next to this launcher. The
254
+ adapter is named by its file, so nothing in the working directory can stand in for it."""
255
+ adapter = os.path.join(os.path.dirname(_HERE), "docattest_python", "__main__.py")
256
+ return [sys.executable, adapter]
257
+
258
+
259
+ CONFIG_FILE = "docattest.config.json"
260
+
261
+
262
+ def _root(argv: list[str]) -> str:
263
+ """The project root the core will use: ``--root``, else the nearest directory at or
264
+ above the working directory that holds a ``docattest.config.json``, else the working
265
+ directory."""
266
+ root = None
267
+ for k, arg in enumerate(argv):
268
+ if arg == "--root" and k + 1 < len(argv):
269
+ root = argv[k + 1]
270
+ elif arg.startswith("--root="):
271
+ root = arg[len("--root=") :]
272
+ if root is not None:
273
+ return os.path.realpath(root)
274
+ here = directory = os.path.realpath(".")
275
+ while not os.path.isfile(os.path.join(directory, CONFIG_FILE)):
276
+ above = os.path.dirname(directory)
277
+ if above == directory:
278
+ return here
279
+ directory = above
280
+ return directory
281
+
282
+
283
+ def docattest_command(root: str) -> str:
284
+ """A shell command that runs docattest in the project at ``root``, for a hook that is
285
+ started with no virtualenv active.
286
+
287
+ In a virtualenv inside the project (the usual ``.venv``) it is the environment's own
288
+ script, relative to the project: ``{root}/.venv/bin/docattest``, which a file can share
289
+ between machines. What ``{root}`` becomes is not this launcher's to know: the core
290
+ writes there how the reader of the command names the project root (a coding agent's own
291
+ variable in that agent's hook, ``.`` in ``AGENTS.md`` and in a git hook). Otherwise the
292
+ command is ``docattest`` when that is what the shell finds on the ``PATH``, and else
293
+ this interpreter by its full path.
294
+ """
295
+ import shlex
296
+
297
+ prefix = os.path.realpath(sys.prefix)
298
+ script = os.path.join(prefix, "Scripts" if os.name == "nt" else "bin", "docattest")
299
+ in_virtualenv = sys.prefix != getattr(sys, "base_prefix", sys.prefix)
300
+ inside = os.path.commonpath([prefix, root]) == root and prefix != root
301
+ if in_virtualenv and inside and os.path.isfile(script):
302
+ relative = os.path.relpath(script, root).replace(os.sep, "/")
303
+ return ROOT + "/" + shlex.quote(relative)
304
+ import shutil
305
+
306
+ found = shutil.which("docattest")
307
+ if found and os.path.isfile(script) and os.path.samefile(found, script):
308
+ return "docattest"
309
+ if os.path.isfile(script):
310
+ return shlex.quote(script)
311
+ return f"{shlex.quote(sys.executable)} -m docattest"
312
+
313
+
314
+ def environment(argv: list[str]) -> dict[str, str]:
315
+ """The core's environment: this process's, with the hand-off added where unset."""
316
+ import json
317
+
318
+ env = dict(os.environ)
319
+ if not env.get(ADAPTER_VARIABLE):
320
+ env[ADAPTER_VARIABLE] = json.dumps(adapter_command())
321
+ # Only these commands read it, and working it out looks at the file system.
322
+ if not env.get(COMMAND_VARIABLE) and any(writer in argv for writer in WRITERS):
323
+ env[COMMAND_VARIABLE] = docattest_command(_root(argv))
324
+ return env
325
+
326
+
327
+ def main() -> None:
328
+ argv = sys.argv[1:]
329
+ pin = pinned()
330
+ core, error = find_core(pin, advice=lambda name: remedy(pin["version"], name, _platform_names()))
331
+ if core is None:
332
+ sys.stderr.write(f"{error}\n")
333
+ sys.exit(1)
334
+ # With a trace asked for, say which core runs.
335
+ if os.environ.get(TRACE_VARIABLE):
336
+ sys.stderr.write(f"[trace launcher] core {core}\n")
337
+ try:
338
+ if sys.platform == "win32":
339
+ # Windows has no exec: os.execve starts the core and ends this process at once,
340
+ # so whoever ran docattest would see neither the core's exit code nor wait for it.
341
+ import subprocess
342
+
343
+ sys.exit(subprocess.call([core, *argv], env=environment(argv)))
344
+ os.execve(core, [core, *argv], environment(argv))
345
+ except OSError as err:
346
+ sys.stderr.write(f"docattest: cannot run the core ({core}): {err}\n")
347
+ sys.exit(1)
348
+
349
+
350
+ if __name__ == "__main__":
351
+ main()