onetrace-auto 0.7.0__tar.gz

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,2 @@
1
+ include _reproducible_sdist.py
2
+ include onetrace-auto.pth
@@ -0,0 +1,104 @@
1
+ Metadata-Version: 2.4
2
+ Name: onetrace-auto
3
+ Version: 0.7.0
4
+ Summary: Zero-configuration recording for onetrace: a run folder from a library's calls, with nothing added to the app
5
+ Author-email: Shamik Saha <shamik.saha.rcciit@gmail.com>
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Issues, https://github.com/shamiksaharcciit-oss/onetrace-issues
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.10
12
+ Classifier: Programming Language :: Python :: 3.11
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Requires-Python: >=3.10
15
+ Description-Content-Type: text/markdown
16
+ Requires-Dist: onetrace==0.7.0
17
+
18
+ # onetrace-auto
19
+
20
+ Zero-configuration recording for [onetrace](https://pypi.org/project/onetrace/): run an app as
21
+ you run it today, with one thing added at the edge, and get a run folder with a receipt per hooked
22
+ library call. Released with onetrace, at the same version, and pinned to it.
23
+
24
+ ## Install
25
+
26
+ ```
27
+ pip install onetrace-auto
28
+ ```
29
+
30
+ This installs one `.pth` line into the environment. It runs at every interpreter start there, and
31
+ with `ONETRACE_AUTO` unset it reads two environment variables and imports nothing. The `onetrace`
32
+ package alone installs no `.pth` line.
33
+
34
+ ## Use
35
+
36
+ ```
37
+ onetrace-run python app.py
38
+ ```
39
+
40
+ or set the variable yourself:
41
+
42
+ ```
43
+ ONETRACE_AUTO=1 python app.py
44
+ ```
45
+
46
+ Only the value `1` turns recording on, and `ONETRACE_DISABLE=1` turns it off whatever else is set.
47
+ Each Python process records its own run, under `ONETRACE_RUNS` (default `./runs`), opened at its
48
+ first hooked call: a process that makes none leaves no folder.
49
+
50
+ An auto-recorded run is complete only with respect to the libraries hooked, at the versions its
51
+ manifest lists in `auto.hooks`. A step in your own code is recorded only where a decorator names
52
+ it. A run folder may contain sensitive data: by default it holds digests only.
53
+
54
+ ## Hooked libraries
55
+
56
+ | library | versions | stage | what a step records |
57
+ |---|---|---|---|
58
+ | openai | `>=1.40,<4` | `openai.chat.completions.create`, `openai.responses.create`, `openai.embeddings.create`, `openai.completions.create` | `create` on each, on `OpenAI` and `AsyncOpenAI`; a stage is declared only where the installed version has its resource (1.40 has no `responses`) |
59
+ | requests | `>=2.28,<3` | `requests.send` | `Session.send`, so `requests.get(...)`, every session method and a prepared request sent by hand |
60
+ | httpx | `>=0.24,<1` | `httpx.send` | `Client.send` and `AsyncClient.send`, so every request method |
61
+
62
+ An HTTP step records the request body as its input `request`, and two outputs: `status`, the JSON
63
+ object `{"status": "<code>"}`, and `response`, the body's bytes. A requests call that followed
64
+ redirects is one step: its `status` is the final response's, with the number of hops,
65
+ `{"redirects": "<n>", "status": "<code>"}`, and its `response` is the final body. A requests text body is
66
+ digested as the installed urllib3 sends it: ISO-8859-1 below urllib3 2, UTF-8 from 2. Where
67
+ ISO-8859-1 cannot encode it, the step records no `request` input and says why. A streamed response's body is not
68
+ read, so the step records `status` alone and says so in the constant `onetrace.http.body`. A
69
+ streamed request body is not read either: the step has no `request` input and says so in
70
+ `onetrace.http.request`. The target is the host, the method, the path's sha256 and the query's
71
+ parameter names; no query value and no user info is recorded. An error records its class, never its
72
+ message, since an HTTP library's message can hold the URL.
73
+
74
+ A model call records its request body as `request`, the response's `model_dump()` as `response`,
75
+ and a model-call record, `model_call.json`, by the hosted adapter's rules. The record's
76
+ `credential` (only whether a key is set, never the key) and the step's host come from the client's
77
+ own `post` method, read while the call runs. A streamed call returns the library's stream, wrapped:
78
+ the step ends when the stream does, and a stream left before its end is an error. Usage is in
79
+ `response`, not in the record. An error records its class and its message, with every URL's user
80
+ info and query values removed.
81
+
82
+ What a model call does **not** record:
83
+ - **where openai was imported before onetrace-auto's boot,** a call on a client made then records
84
+ no credential, no host and no model-call record. The step is recorded, and the constant
85
+ `onetrace.model_call` says `not written: the hook did not see the client's request`. With
86
+ `onetrace-run`, or `ONETRACE_AUTO=1` set before the interpreter starts, boot comes first;
87
+ - **an embeddings call** has no record format in this release: it records `request` and
88
+ `response`, and the constant says so;
89
+ - **under openai 3.x, the client's HTTP layer** (`httpx2`) is not recorded by the httpx hook. The
90
+ model step itself is recorded.
91
+
92
+ ## Settings
93
+
94
+ - `ONETRACE_AUTO_KEEP=outputs` keeps the output files; `inputs` keeps each request body of up to
95
+ 4096 bytes (a larger one is named, not kept). Both: `outputs,inputs`.
96
+ - `ONETRACE_AUTO_MAX_RUN_BYTES=<bytes>` gives the process's run a store bound, in decimal digits: the
97
+ receipts and kept outputs count toward it, the manifest does not. The step that reaches it is
98
+ recorded as a gap, the run declares the boundary `store bound reached` naming that step and
99
+ closes, and every later hooked call goes ahead unrecorded. Unset or empty: no bound. A value that
100
+ is not a whole decimal number, or is below the smallest the run's receipts allow, opens no run,
101
+ and the process says why once on stderr. It is read once, when the run opens; a decorated
102
+ `@ot.run` does not read it.
103
+ - `ONETRACE_AUTO_HTTP_PATH=plain` records the path itself in place of its digest.
104
+ - `ONETRACE_AUTO_KEEP_QUERY=name,...` records the named query parameters' values as configuration.
@@ -0,0 +1,87 @@
1
+ # onetrace-auto
2
+
3
+ Zero-configuration recording for [onetrace](https://pypi.org/project/onetrace/): run an app as
4
+ you run it today, with one thing added at the edge, and get a run folder with a receipt per hooked
5
+ library call. Released with onetrace, at the same version, and pinned to it.
6
+
7
+ ## Install
8
+
9
+ ```
10
+ pip install onetrace-auto
11
+ ```
12
+
13
+ This installs one `.pth` line into the environment. It runs at every interpreter start there, and
14
+ with `ONETRACE_AUTO` unset it reads two environment variables and imports nothing. The `onetrace`
15
+ package alone installs no `.pth` line.
16
+
17
+ ## Use
18
+
19
+ ```
20
+ onetrace-run python app.py
21
+ ```
22
+
23
+ or set the variable yourself:
24
+
25
+ ```
26
+ ONETRACE_AUTO=1 python app.py
27
+ ```
28
+
29
+ Only the value `1` turns recording on, and `ONETRACE_DISABLE=1` turns it off whatever else is set.
30
+ Each Python process records its own run, under `ONETRACE_RUNS` (default `./runs`), opened at its
31
+ first hooked call: a process that makes none leaves no folder.
32
+
33
+ An auto-recorded run is complete only with respect to the libraries hooked, at the versions its
34
+ manifest lists in `auto.hooks`. A step in your own code is recorded only where a decorator names
35
+ it. A run folder may contain sensitive data: by default it holds digests only.
36
+
37
+ ## Hooked libraries
38
+
39
+ | library | versions | stage | what a step records |
40
+ |---|---|---|---|
41
+ | openai | `>=1.40,<4` | `openai.chat.completions.create`, `openai.responses.create`, `openai.embeddings.create`, `openai.completions.create` | `create` on each, on `OpenAI` and `AsyncOpenAI`; a stage is declared only where the installed version has its resource (1.40 has no `responses`) |
42
+ | requests | `>=2.28,<3` | `requests.send` | `Session.send`, so `requests.get(...)`, every session method and a prepared request sent by hand |
43
+ | httpx | `>=0.24,<1` | `httpx.send` | `Client.send` and `AsyncClient.send`, so every request method |
44
+
45
+ An HTTP step records the request body as its input `request`, and two outputs: `status`, the JSON
46
+ object `{"status": "<code>"}`, and `response`, the body's bytes. A requests call that followed
47
+ redirects is one step: its `status` is the final response's, with the number of hops,
48
+ `{"redirects": "<n>", "status": "<code>"}`, and its `response` is the final body. A requests text body is
49
+ digested as the installed urllib3 sends it: ISO-8859-1 below urllib3 2, UTF-8 from 2. Where
50
+ ISO-8859-1 cannot encode it, the step records no `request` input and says why. A streamed response's body is not
51
+ read, so the step records `status` alone and says so in the constant `onetrace.http.body`. A
52
+ streamed request body is not read either: the step has no `request` input and says so in
53
+ `onetrace.http.request`. The target is the host, the method, the path's sha256 and the query's
54
+ parameter names; no query value and no user info is recorded. An error records its class, never its
55
+ message, since an HTTP library's message can hold the URL.
56
+
57
+ A model call records its request body as `request`, the response's `model_dump()` as `response`,
58
+ and a model-call record, `model_call.json`, by the hosted adapter's rules. The record's
59
+ `credential` (only whether a key is set, never the key) and the step's host come from the client's
60
+ own `post` method, read while the call runs. A streamed call returns the library's stream, wrapped:
61
+ the step ends when the stream does, and a stream left before its end is an error. Usage is in
62
+ `response`, not in the record. An error records its class and its message, with every URL's user
63
+ info and query values removed.
64
+
65
+ What a model call does **not** record:
66
+ - **where openai was imported before onetrace-auto's boot,** a call on a client made then records
67
+ no credential, no host and no model-call record. The step is recorded, and the constant
68
+ `onetrace.model_call` says `not written: the hook did not see the client's request`. With
69
+ `onetrace-run`, or `ONETRACE_AUTO=1` set before the interpreter starts, boot comes first;
70
+ - **an embeddings call** has no record format in this release: it records `request` and
71
+ `response`, and the constant says so;
72
+ - **under openai 3.x, the client's HTTP layer** (`httpx2`) is not recorded by the httpx hook. The
73
+ model step itself is recorded.
74
+
75
+ ## Settings
76
+
77
+ - `ONETRACE_AUTO_KEEP=outputs` keeps the output files; `inputs` keeps each request body of up to
78
+ 4096 bytes (a larger one is named, not kept). Both: `outputs,inputs`.
79
+ - `ONETRACE_AUTO_MAX_RUN_BYTES=<bytes>` gives the process's run a store bound, in decimal digits: the
80
+ receipts and kept outputs count toward it, the manifest does not. The step that reaches it is
81
+ recorded as a gap, the run declares the boundary `store bound reached` naming that step and
82
+ closes, and every later hooked call goes ahead unrecorded. Unset or empty: no bound. A value that
83
+ is not a whole decimal number, or is below the smallest the run's receipts allow, opens no run,
84
+ and the process says why once on stderr. It is read once, when the run opens; a decorated
85
+ `@ot.run` does not read it.
86
+ - `ONETRACE_AUTO_HTTP_PATH=plain` records the path itself in place of its digest.
87
+ - `ONETRACE_AUTO_KEEP_QUERY=name,...` records the named query parameters' values as configuration.
@@ -0,0 +1,61 @@
1
+ """The build backend: setuptools' own (setuptools.build_meta), with its sdist archived so that two
2
+ builds of the same tree are the same bytes. Wheels are built exactly as setuptools builds them.
3
+
4
+ setuptools writes each sdist member with the file's mtime and owner, and the gzip header with the
5
+ build clock, so two builds of one tree differ in those bytes alone. Here the release tree setuptools
6
+ has already made is archived in sorted order, every member's time set to SOURCE_DATE_EPOCH (0 when it
7
+ is unset), owner and group 0 with no names, modes normalised (0644 for files, 0755 for directories
8
+ and executables), and the gzip header's time set the same way. The members and their contents are
9
+ setuptools' own. It runs inside the build, before the archive exists; nothing is repacked afterwards.
10
+ """
11
+ import gzip
12
+ import os
13
+ import tarfile
14
+
15
+ from setuptools.command import sdist as _sdist_module
16
+
17
+
18
+ def _epoch() -> int:
19
+ v = os.environ.get("SOURCE_DATE_EPOCH", "")
20
+ return int(v) if v.isdigit() else 0
21
+
22
+
23
+ _setuptools_make_archive = _sdist_module.sdist.make_archive
24
+
25
+
26
+ def _make_archive(self, base_name, format, root_dir=None, base_dir=None, owner=None, group=None):
27
+ if format != "gztar":
28
+ return _setuptools_make_archive(self, base_name, format, root_dir, base_dir, owner, group)
29
+ when = _epoch()
30
+ root = os.path.abspath(root_dir or os.curdir)
31
+ top = base_dir or os.curdir
32
+ paths = []
33
+ for d, dirs, files in os.walk(os.path.join(root, top)):
34
+ dirs.sort()
35
+ rel_d = os.path.relpath(d, root)
36
+ paths.append(rel_d)
37
+ paths.extend(os.path.join(rel_d, f) for f in sorted(files))
38
+ target = os.path.abspath(base_name + ".tar.gz")
39
+
40
+ def norm(ti):
41
+ ti.mtime = when
42
+ ti.uid = ti.gid = 0
43
+ ti.uname = ti.gname = ""
44
+ if ti.isdir():
45
+ ti.mode = 0o755
46
+ elif ti.isfile():
47
+ ti.mode = 0o755 if ti.mode & 0o111 else 0o644
48
+ return ti
49
+
50
+ with open(target, "wb") as raw, \
51
+ gzip.GzipFile(filename="", mode="wb", fileobj=raw, mtime=when, compresslevel=9) as gz, \
52
+ tarfile.open(fileobj=gz, mode="w", format=tarfile.PAX_FORMAT) as tar:
53
+ for rel in paths:
54
+ tar.add(os.path.join(root, rel), arcname=os.path.normpath(rel), recursive=False, filter=norm)
55
+ return target
56
+
57
+
58
+ _sdist_module.sdist.make_archive = _make_archive
59
+
60
+ from setuptools.build_meta import * # noqa: E402,F401,F403 -- the hooks, unchanged
61
+ from setuptools.build_meta import __all__ # noqa: E402,F401
@@ -0,0 +1 @@
1
+ import os; os.environ.get("ONETRACE_AUTO") == "1" and os.environ.get("ONETRACE_DISABLE") != "1" and __import__("onetrace.auto._boot")
@@ -0,0 +1,42 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ # setuptools' own backend, with its sdist archived reproducibly (_reproducible_sdist.py says how).
4
+ # setup.py beside this file adds one thing setuptools has no setting for: the .pth line, at the top
5
+ # of the wheel.
6
+ build-backend = "_reproducible_sdist"
7
+ backend-path = ["."]
8
+
9
+ [project]
10
+ name = "onetrace-auto"
11
+ # Released in lockstep with onetrace, as onetrace-verify is: the same version, and onetrace pinned
12
+ # to it exactly, since onetrace.auto writes through onetrace's own recorder.
13
+ version = "0.7.0"
14
+ description = "Zero-configuration recording for onetrace: a run folder from a library's calls, with nothing added to the app"
15
+ readme = "README.md"
16
+ requires-python = ">=3.10"
17
+ dependencies = ["onetrace==0.7.0"]
18
+ license = "Apache-2.0"
19
+ authors = [
20
+ {name = "Shamik Saha", email = "shamik.saha.rcciit@gmail.com"},
21
+ ]
22
+ classifiers = [
23
+ "Development Status :: 3 - Alpha",
24
+ "Intended Audience :: Developers",
25
+ "Programming Language :: Python :: 3",
26
+ "Programming Language :: Python :: 3.10",
27
+ "Programming Language :: Python :: 3.11",
28
+ "Programming Language :: Python :: 3.12",
29
+ ]
30
+
31
+ [project.urls]
32
+ Issues = "https://github.com/shamiksaharcciit-oss/onetrace-issues"
33
+
34
+ [project.scripts]
35
+ onetrace-run = "onetrace.auto.launcher:main"
36
+
37
+ # onetrace.auto is a subpackage of onetrace, shipped by this distribution and never by onetrace's
38
+ # own wheel. This wheel holds onetrace/auto/ and no onetrace/__init__.py, so installing it adds a
39
+ # folder to the installed onetrace and replaces none of its files.
40
+ [tool.setuptools]
41
+ packages = ["onetrace.auto"]
42
+ package-dir = {"" = "src"}
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,24 @@
1
+ """The one thing pyproject.toml can't say: the wheel carries onetrace-auto.pth at its top, beside the
2
+ onetrace/ folder, so that it lands in site-packages, where `site` reads it at interpreter start.
3
+
4
+ The file is copied as it is, byte for byte, by build_py into the folder the wheel is made from; the
5
+ wheel's RECORD lists it as it lists every file.
6
+ """
7
+ import os
8
+
9
+ from setuptools import setup
10
+ from setuptools.command.build_py import build_py
11
+
12
+ PTH = "onetrace-auto.pth"
13
+
14
+
15
+ class build_py_with_pth(build_py):
16
+ def run(self):
17
+ super().run()
18
+ self.copy_file(PTH, os.path.join(self.build_lib, PTH), preserve_mode=False)
19
+
20
+ def get_outputs(self, include_bytecode=True):
21
+ return super().get_outputs(include_bytecode) + [os.path.join(self.build_lib, PTH)]
22
+
23
+
24
+ setup(cmdclass={"build_py": build_py_with_pth})
@@ -0,0 +1,15 @@
1
+ """onetrace.auto: zero-configuration recording (the onetrace-auto distribution).
2
+
3
+ A team runs its app as it does today, with `ONETRACE_AUTO=1` set or under `onetrace-run`, and gets a
4
+ run folder with a receipt per hooked library call. Nothing here is imported unless asked: the
5
+ `onetrace-auto.pth` line this distribution installs imports `onetrace.auto._boot` only when
6
+ `ONETRACE_AUTO` is exactly "1" and `ONETRACE_DISABLE` is not "1".
7
+
8
+ - `_boot`: run at interpreter start; never raises into the app.
9
+ - `_hooks`: the hooks this version installs, the version gate, and the import finder that installs
10
+ a library's hook when the app imports it.
11
+ - `_wrapper`: the shape every hooked method takes; the app's call is made exactly once, with its own
12
+ arguments, and its return value or exception is the app's.
13
+ - `_state`: the process's run, opened at the first hooked call and closed when the process ends.
14
+ - `launcher`: `onetrace-run <command> [args...]`.
15
+ """
@@ -0,0 +1,15 @@
1
+ """Run at interpreter start by onetrace-auto.pth, only when ONETRACE_AUTO=1 and ONETRACE_DISABLE is not 1.
2
+
3
+ It installs the import finder, the exit and SIGTERM handlers and the fork reset (`_state.boot`), and
4
+ nothing else: no run is opened until the first hooked call. It catches everything, and when it can't
5
+ start it prints one line to stderr and the interpreter starts as usual. It never raises into the app.
6
+ """
7
+ try:
8
+ from . import _state
9
+ _state.boot()
10
+ except BaseException as _e: # noqa: BLE001 -- the app starts whatever happens here
11
+ try:
12
+ import sys as _sys
13
+ print(f"onetrace-auto: auto recording is off in this process: {type(_e).__name__}: {_e}", file=_sys.stderr)
14
+ except BaseException:
15
+ pass
@@ -0,0 +1,228 @@
1
+ """The hooks, the version gate and the import finder (design note 2.1, 2.6).
2
+
3
+ A hook is installed when its library is imported, not before: the boot module puts a finder at the
4
+ front of `sys.meta_path`, and when the app imports a hooked library's top-level module the finder
5
+ lets the import finish and then installs that library's hook. A library already imported at boot is
6
+ hooked at once. Importing a library at interpreter start would cost every process and change the
7
+ app's import order, so nothing here imports one.
8
+
9
+ A hook is installed only when the library's installed version, read from `importlib.metadata`, is
10
+ inside the hook's supported range. Outside it no hook is installed, one line goes to stderr (unless
11
+ `ONETRACE_QUIET=1`), and the run's manifest says why, in `auto.hooks`.
12
+ """
13
+ from __future__ import annotations
14
+
15
+ import importlib.abc
16
+ import importlib.metadata
17
+ import importlib.util
18
+ import os
19
+ import re
20
+ import sys
21
+ import threading
22
+ from dataclasses import dataclass
23
+
24
+
25
+ @dataclass(frozen=True)
26
+ class Hook:
27
+ library: str # the distribution's name, as importlib.metadata knows it: auto.library
28
+ module: str # the top-level module whose import installs the hook
29
+ floor: tuple # the supported range, floor <= version < ceiling, as release numbers
30
+ ceiling: tuple
31
+ stages: tuple # every stage name this hook can emit
32
+ install: object # install(module): replaces public methods on the library's public classes
33
+ # present(stage) -> bool: whether the installed version has what the stage records, read without
34
+ # importing the library (its distribution's file list); None: every stage is declared
35
+ present: object = None
36
+
37
+ @property
38
+ def range(self) -> str:
39
+ return f">={'.'.join(map(str, self.floor))},<{'.'.join(map(str, self.ceiling))}"
40
+
41
+
42
+ #: The hooks this version installs, in a fixed order. The order is the manifest's `auto.hooks`
43
+ #: order and, with each hook's stages, the run's declared stages, so it depends only on the version.
44
+ HOOKS: list = []
45
+ #: The modules of the hooks this version ships, in section 2's order. Each defines HOOK; none
46
+ #: imports its library. They are loaded once, ahead of any other hook, the first time the list is read.
47
+ SHIPPED = ("_openai", "_requests", "_httpx")
48
+ _shipped_loaded = False
49
+
50
+
51
+ def _load_shipped() -> None:
52
+ global _shipped_loaded
53
+ if _shipped_loaded:
54
+ return
55
+ with _lock:
56
+ if _shipped_loaded:
57
+ return
58
+ _shipped_loaded = True
59
+ import importlib
60
+ hooks = [importlib.import_module(f"{__package__}.{m}").HOOK for m in SHIPPED]
61
+ HOOKS[:0] = [h for h in hooks if all(x.library != h.library for x in HOOKS)]
62
+
63
+ _lock = threading.RLock()
64
+ _installed: dict = {} # library -> the version its hook was installed at
65
+ _not_hooked: dict = {} # library -> the status that says why it was not hooked
66
+ _finder = None
67
+
68
+
69
+ def register(hook: Hook) -> None:
70
+ """Add a hook to the list. A library already imported is hooked at once, once the finder is in."""
71
+ _load_shipped()
72
+ with _lock:
73
+ if any(h.library == hook.library for h in HOOKS):
74
+ raise ValueError(f"a hook for {hook.library!r} is already registered")
75
+ HOOKS.append(hook)
76
+ if _finder is not None and hook.module in sys.modules:
77
+ _on_import(hook.module, sys.modules[hook.module])
78
+
79
+
80
+ def declared_stages() -> list:
81
+ """Every stage name the hooks can emit, in the hooks' order: an auto run's declared stages."""
82
+ _load_shipped()
83
+ with _lock:
84
+ return [s for h in HOOKS for s in h.stages if h.present is None or _present(h, s)]
85
+
86
+
87
+ def _present(hook: Hook, stage: str) -> bool:
88
+ try:
89
+ return bool(hook.present(stage))
90
+ except Exception:
91
+ return False
92
+
93
+
94
+ def version_of(library: str):
95
+ """The version a library's hook was installed at, or None when it is not hooked."""
96
+ return _installed.get(library)
97
+
98
+
99
+ def hook_list() -> list:
100
+ """The manifest's `auto.hooks`: one entry per library, in the hooks' order, as things stand now.
101
+ `version` is written only on a hooked entry; a library not hooked says why in `status`."""
102
+ _load_shipped()
103
+ out = []
104
+ with _lock:
105
+ for h in HOOKS:
106
+ if h.library in _installed:
107
+ out.append({"library": h.library, "status": "hooked", "version": _installed[h.library]})
108
+ elif h.library in _not_hooked:
109
+ out.append({"library": h.library, "status": _not_hooked[h.library]})
110
+ else:
111
+ out.append({"library": h.library, "status": "not imported"})
112
+ return out
113
+
114
+
115
+ # A release number and nothing after it but a post-release or a local label. A pre-release or a
116
+ # development release is read as outside every range, as a PEP 440 specifier reads it by default.
117
+ _VERSION = re.compile(r"v?(\d+(?:\.\d+)*)(?:[-_.]?post\d*)?(?:\+[A-Za-z0-9.]+)?")
118
+
119
+
120
+ def _release(version: str):
121
+ m = _VERSION.fullmatch(version.strip())
122
+ return tuple(int(p) for p in m.group(1).split(".")) if m else None
123
+
124
+
125
+ def _pad(t: tuple, n: int) -> tuple:
126
+ return t + (0,) * (n - len(t))
127
+
128
+
129
+ def in_range(version: str, hook: Hook) -> bool:
130
+ r = _release(version)
131
+ if r is None:
132
+ return False
133
+ n = max(len(r), len(hook.floor), len(hook.ceiling))
134
+ return _pad(hook.floor, n) <= _pad(r, n) < _pad(hook.ceiling, n)
135
+
136
+
137
+ def _say(line: str) -> None:
138
+ if os.environ.get("ONETRACE_QUIET") != "1":
139
+ try:
140
+ print(line, file=sys.stderr)
141
+ except Exception:
142
+ pass
143
+
144
+
145
+ def _on_import(name: str, module) -> None:
146
+ """The library `name` has just been imported: install its hook, or record why not. Never raises."""
147
+ for hook in list(HOOKS):
148
+ if hook.module != name:
149
+ continue
150
+ with _lock:
151
+ if hook.library in _installed or hook.library in _not_hooked:
152
+ continue
153
+ try:
154
+ version = importlib.metadata.version(hook.library)
155
+ except Exception:
156
+ _not_hooked[hook.library] = "not hooked: no installed version found"
157
+ _say(f"onetrace-auto: {hook.library} is not hooked: no installed version found")
158
+ continue
159
+ if not in_range(version, hook):
160
+ _not_hooked[hook.library] = f"not hooked: version {version} is outside {hook.range}"
161
+ _say(f"onetrace-auto: {hook.library} {version} is not hooked: it is outside {hook.range}")
162
+ continue
163
+ try:
164
+ hook.install(module)
165
+ except Exception as e:
166
+ _not_hooked[hook.library] = f"not hooked: the hook could not be installed: {type(e).__name__}"
167
+ _say(f"onetrace-auto: {hook.library} is not hooked: the hook could not be installed: "
168
+ f"{type(e).__name__}")
169
+ continue
170
+ _installed[hook.library] = version
171
+
172
+
173
+ class _Loader(importlib.abc.Loader):
174
+ """The library's own loader, unchanged, with the hook installed once its module has run."""
175
+
176
+ def __init__(self, loader, name):
177
+ self._loader, self._name = loader, name
178
+
179
+ def create_module(self, spec):
180
+ return self._loader.create_module(spec)
181
+
182
+ def exec_module(self, module):
183
+ # The module sees its own loader, never this one.
184
+ module.__loader__ = self._loader
185
+ if getattr(module, "__spec__", None) is not None:
186
+ module.__spec__.loader = self._loader
187
+ self._loader.exec_module(module)
188
+ _on_import(self._name, module)
189
+
190
+ def __getattr__(self, attr):
191
+ return getattr(self._loader, attr)
192
+
193
+
194
+ class _Finder(importlib.abc.MetaPathFinder):
195
+ """Finds nothing itself: for a hooked library's top-level module it asks the finders after it,
196
+ and hands back their spec with a loader that installs the hook after the module has run."""
197
+
198
+ def __init__(self):
199
+ self._busy = set()
200
+
201
+ def find_spec(self, fullname, path=None, target=None):
202
+ if path is not None or fullname in self._busy or not any(h.module == fullname for h in HOOKS):
203
+ return None
204
+ self._busy.add(fullname)
205
+ try:
206
+ spec = importlib.util.find_spec(fullname)
207
+ except Exception:
208
+ return None
209
+ finally:
210
+ self._busy.discard(fullname)
211
+ if spec is None or spec.loader is None or not hasattr(spec.loader, "exec_module"):
212
+ return None
213
+ spec.loader = _Loader(spec.loader, fullname)
214
+ return spec
215
+
216
+
217
+ def install_finder() -> None:
218
+ """Put the finder at the front of sys.meta_path, and hook every library already imported."""
219
+ global _finder
220
+ _load_shipped()
221
+ with _lock:
222
+ if _finder is not None:
223
+ return
224
+ _finder = _Finder()
225
+ sys.meta_path.insert(0, _finder)
226
+ for hook in list(HOOKS):
227
+ if hook.module in sys.modules:
228
+ _on_import(hook.module, sys.modules[hook.module])