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.
- onetrace_auto-0.7.0/MANIFEST.in +2 -0
- onetrace_auto-0.7.0/PKG-INFO +104 -0
- onetrace_auto-0.7.0/README.md +87 -0
- onetrace_auto-0.7.0/_reproducible_sdist.py +61 -0
- onetrace_auto-0.7.0/onetrace-auto.pth +1 -0
- onetrace_auto-0.7.0/pyproject.toml +42 -0
- onetrace_auto-0.7.0/setup.cfg +4 -0
- onetrace_auto-0.7.0/setup.py +24 -0
- onetrace_auto-0.7.0/src/onetrace/auto/__init__.py +15 -0
- onetrace_auto-0.7.0/src/onetrace/auto/_boot.py +15 -0
- onetrace_auto-0.7.0/src/onetrace/auto/_hooks.py +228 -0
- onetrace_auto-0.7.0/src/onetrace/auto/_httpx.py +132 -0
- onetrace_auto-0.7.0/src/onetrace/auto/_openai.py +291 -0
- onetrace_auto-0.7.0/src/onetrace/auto/_requests.py +163 -0
- onetrace_auto-0.7.0/src/onetrace/auto/_state.py +323 -0
- onetrace_auto-0.7.0/src/onetrace/auto/_wrapper.py +567 -0
- onetrace_auto-0.7.0/src/onetrace/auto/launcher.py +80 -0
- onetrace_auto-0.7.0/src/onetrace_auto.egg-info/PKG-INFO +104 -0
- onetrace_auto-0.7.0/src/onetrace_auto.egg-info/SOURCES.txt +21 -0
- onetrace_auto-0.7.0/src/onetrace_auto.egg-info/dependency_links.txt +1 -0
- onetrace_auto-0.7.0/src/onetrace_auto.egg-info/entry_points.txt +2 -0
- onetrace_auto-0.7.0/src/onetrace_auto.egg-info/requires.txt +1 -0
- onetrace_auto-0.7.0/src/onetrace_auto.egg-info/top_level.txt +1 -0
|
@@ -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,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])
|