libpython-linkcheck 0.1.0a1__py3-none-any.whl → 0.1.0a2__py3-none-any.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.
@@ -51,7 +51,7 @@ class NotELFError(ELFError):
51
51
  """The file does not start with the ELF magic number."""
52
52
 
53
53
 
54
- def is_libpython(needed: str) -> bool:
54
+ def py_is_libpython(needed: str) -> bool:
55
55
  """Return True if a DT_NEEDED entry names a libpython shared library.
56
56
 
57
57
  Entries containing a path (``/usr/lib/libpython3.12.so.1.0``) are matched
@@ -60,6 +60,33 @@ def is_libpython(needed: str) -> bool:
60
60
  return _LIBPYTHON_RE.fullmatch(needed.rpartition("/")[2]) is not None
61
61
 
62
62
 
63
+ def py_read_needed(path: str | os.PathLike[str] | os.PathLike[bytes] | bytes) -> list[str]:
64
+ """Pure-Python implementation of :func:`read_needed`."""
65
+ with open(path, "rb") as f:
66
+ return _read_needed(f)
67
+
68
+
69
+ def _native_read_needed(path: str | os.PathLike[str] | os.PathLike[bytes] | bytes) -> list[str]:
70
+ status, value = _native.read_needed(path)
71
+ if status == 0:
72
+ return value
73
+ if status == 2:
74
+ raise NotELFError(value)
75
+ raise ELFError(value)
76
+
77
+
78
+ if os.environ.get("LIBPYTHON_LINKCHECK_IMPLEMENTATION") == "python":
79
+ _native = None # forced pure-Python implementation (debugging/testing)
80
+ else:
81
+ try:
82
+ from . import _native # type: ignore[attr-defined]
83
+ except ImportError:
84
+ _native = None
85
+
86
+ #: "native" when the C implementation is in use, else "python".
87
+ IMPLEMENTATION = "python" if _native is None else "native"
88
+
89
+
63
90
  def read_needed(path: str | os.PathLike[str] | os.PathLike[bytes] | bytes) -> list[str]:
64
91
  """Return the DT_NEEDED entries of the ELF object at *path*, in order.
65
92
 
@@ -67,8 +94,20 @@ def read_needed(path: str | os.PathLike[str] | os.PathLike[bytes] | bytes) -> li
67
94
  Raises :class:`NotELFError` if the file is not ELF, :class:`ELFError` if it
68
95
  is malformed, and :class:`OSError` if it cannot be read.
69
96
  """
70
- with open(path, "rb") as f:
71
- return _read_needed(f)
97
+ if _native is None:
98
+ return py_read_needed(path)
99
+ return _native_read_needed(path)
100
+
101
+
102
+ def is_libpython(needed: str) -> bool:
103
+ """Return True if a DT_NEEDED entry names a libpython shared library.
104
+
105
+ Entries containing a path (``/usr/lib/libpython3.12.so.1.0``) are matched
106
+ on their final component.
107
+ """
108
+ if _native is None:
109
+ return py_is_libpython(needed)
110
+ return _native.is_libpython(needed)
72
111
 
73
112
 
74
113
  def libpython_dependencies(
@@ -9,19 +9,36 @@ import threading
9
9
  import warnings
10
10
  from typing import Any
11
11
 
12
+ from . import _elf
12
13
  from ._elf import libpython_dependencies
13
14
 
14
15
  #: Audit event used to ask "is a libpython-linkcheck hook installed here?".
15
- #: Every hook implementation appends an identifier to the list passed as the
16
- #: event's only argument. This lets ``enable()`` detect a hook installed by
17
- #: another copy of this module (or, in future, by native code) without relying
18
- #: on module globals.
16
+ #: Every hook appends ``(kind, category)`` to the list passed as the event's
17
+ #: only argument: kind is "python" (this module's hook), "native" (the C hook
18
+ #: installed by enable()) or "embedded" (the runtime-wide C hook registered by
19
+ #: an embedding application with LibpythonLinkcheck_Install()). This lets
20
+ #: enable() detect any of them, and lets every hook in an interpreter share
21
+ #: one warning category, without relying on module globals.
19
22
  PROBE_EVENT = "libpython_linkcheck.probe"
20
23
 
21
24
  _enable_lock = threading.Lock()
22
25
 
23
26
 
24
- class LibpythonLinkWarning(RuntimeWarning):
27
+ def _probe() -> list[tuple[str, Any]]:
28
+ found: list[Any] = []
29
+ sys.audit(PROBE_EVENT, found)
30
+ # 0.1.0a1 answered with a bare "python" string.
31
+ return [e if isinstance(e, tuple) and len(e) == 2 else (str(e), None) for e in found]
32
+
33
+
34
+ def _adopted_category() -> type[RuntimeWarning] | None:
35
+ for _, category in _probe():
36
+ if isinstance(category, type) and issubclass(category, RuntimeWarning):
37
+ return category
38
+ return None
39
+
40
+
41
+ class _PyLibpythonLinkWarning(RuntimeWarning):
25
42
  """An extension module about to be loaded has a DT_NEEDED entry for libpython.
26
43
 
27
44
  Instances raised by the hook carry three attributes:
@@ -40,11 +57,21 @@ class LibpythonLinkWarning(RuntimeWarning):
40
57
 
41
58
 
42
59
  # Report the public location in tracebacks and warning filters.
43
- LibpythonLinkWarning.__module__ = "libpython_linkcheck"
60
+ _PyLibpythonLinkWarning.__module__ = "libpython_linkcheck"
61
+ _PyLibpythonLinkWarning.__qualname__ = _PyLibpythonLinkWarning.__name__ = "LibpythonLinkWarning"
62
+
63
+ # One class per interpreter, shared by every hook: the C implementation keeps
64
+ # it in the interpreter's state dict; without it, adopt the class of a hook
65
+ # that is already installed (e.g. by an embedding application).
66
+ LibpythonLinkWarning: type[RuntimeWarning]
67
+ if _elf._native is not None:
68
+ LibpythonLinkWarning = _elf._native.category()
69
+ else:
70
+ LibpythonLinkWarning = _adopted_category() or _PyLibpythonLinkWarning
44
71
 
45
72
 
46
- def _make_warning(module: str, filename: str, needed: list[str]) -> LibpythonLinkWarning:
47
- warning = LibpythonLinkWarning(
73
+ def _make_warning(module: str, filename: str, needed: list[str]) -> RuntimeWarning:
74
+ warning: Any = LibpythonLinkWarning(
48
75
  f"extension module {module!r} links directly to libpython: "
49
76
  f"{filename} has DT_NEEDED {', '.join(needed)}"
50
77
  )
@@ -78,7 +105,7 @@ def _audit_hook(event: str, args: tuple[Any, ...]) -> None:
78
105
  if len(args) == 5 and args[1] is not None and args[2] is None:
79
106
  _check_extension(args[0], args[1])
80
107
  elif event == PROBE_EVENT and args and isinstance(args[0], list):
81
- args[0].append("python")
108
+ args[0].append(("python", LibpythonLinkWarning))
82
109
 
83
110
 
84
111
  # How -W / PYTHONWARNINGS entries can spell the category.
@@ -150,9 +177,8 @@ def _apply_dropped_warnoptions() -> None:
150
177
 
151
178
 
152
179
  def _installed_hooks() -> list[str]:
153
- found: list[str] = []
154
- sys.audit(PROBE_EVENT, found)
155
- return found
180
+ """Kinds of the libpython-linkcheck hooks active in this interpreter."""
181
+ return [kind for kind, _ in _probe()]
156
182
 
157
183
 
158
184
  def is_enabled() -> bool:
@@ -178,7 +204,8 @@ def enable() -> bool:
178
204
  with _enable_lock:
179
205
  if is_enabled():
180
206
  return False
181
- sys.addaudithook(_audit_hook)
207
+ native = _elf._native
208
+ sys.addaudithook(_audit_hook if native is None else native.audit_hook)
182
209
  if not is_enabled():
183
210
  # sys.addaudithook() silently skips the hook if an existing hook
184
211
  # raised a RuntimeError subclass for the "sys.addaudithook" event.
@@ -1 +1 @@
1
- __version__ = "0.1.0a1"
1
+ __version__ = "0.1.0a2"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: libpython-linkcheck
3
- Version: 0.1.0a1
3
+ Version: 0.1.0a2
4
4
  Summary: Warn when an imported Python extension directly links to libpython on Linux.
5
5
  Author: Itamar Oren
6
6
  License-Expression: MIT
@@ -49,7 +49,9 @@ a `LibpythonLinkWarning` if the object's own `DT_NEEDED` entries name libpython.
49
49
  pip install libpython-linkcheck
50
50
  ```
51
51
 
52
- The import name is `libpython_linkcheck`. It is pure Python, with no dependencies.
52
+ The import name is `libpython_linkcheck`. It has no dependencies. On Linux
53
+ (x86_64 and aarch64, glibc) pip installs a native wheel that runs the check
54
+ in C; elsewhere it installs a pure-Python wheel with the same behavior.
53
55
 
54
56
  ## Usage
55
57
 
@@ -129,6 +131,59 @@ is 0 if no file links libpython, 1 if any does, and 2 if a file could not be
129
131
  read or is not ELF. From Python, `libpython_linkcheck.libpython_dependencies(path)`
130
132
  returns the matching entries as a list.
131
133
 
134
+ ## Activating it automatically
135
+
136
+ Installing `libpython-linkcheck` never activates anything by itself. To check
137
+ every program run by an interpreter, choose one of these explicitly:
138
+
139
+ | Activation | How | Covers | Not under |
140
+ | --- | --- | --- | --- |
141
+ | User code | `libpython_linkcheck.enable()` | the calling interpreter, from that call on | — |
142
+ | `sitecustomize` | `sitecustomize.py` in site-packages calling `enable()` | interpreters using that site-packages (a venv's own, or the base installation's) | `-S` |
143
+ | `usercustomize` | `usercustomize.py` in the user site directory calling `enable()` | that user's interpreters outside venvs | `-s`, `-I`, `-S`, venvs |
144
+ | `.pth` + `.start` | install `libpython-linkcheck-autoenable` (see `autoenable/`), or copy its two files into site-packages | interpreters using that site-packages, before `sitecustomize` and user code | `-S` |
145
+ | Executable | `LibpythonLinkcheck_Install()` in the program's `main()` (next section) | the whole runtime, including subinterpreters | — (works under `-I -S`) |
146
+
147
+ Every path can be combined with the others: whichever runs first installs the
148
+ hook, and later `enable()` calls detect it and return `False`, so each
149
+ extension module is reported once. A hook installed by `enable()` (any of the
150
+ first four rows) covers only the interpreter that installed it; a
151
+ subinterpreter needs its own `enable()` call. Extension modules imported
152
+ before activation, including by `.pth` files processed earlier, are not
153
+ inspected.
154
+
155
+ `libpython-linkcheck-autoenable` is not on PyPI; build it from the
156
+ repository with `python -m build --wheel autoenable`. On Python 3.11–3.14 its
157
+ `.pth` file's import line calls `enable()`; on 3.15 and later the matching
158
+ [PEP 829](https://peps.python.org/pep-0829/) `.start` file
159
+ (`libpython_linkcheck:enable`) does, and disables that import line.
160
+
161
+ ## Embedding: a hook installed before Python starts
162
+
163
+ Applications that embed CPython, and CPython distributions that build their
164
+ own `python` executable, can register the check in C before the runtime
165
+ starts. No Python package is imported, it covers every interpreter
166
+ (including subinterpreters), and it works under `-I -S`:
167
+
168
+ ```c
169
+ #include "libpython_linkcheck.h"
170
+
171
+ int main(int argc, char **argv) {
172
+ if (LibpythonLinkcheck_Install() < 0) {
173
+ return 1;
174
+ }
175
+ return Py_BytesMain(argc, argv);
176
+ }
177
+ ```
178
+
179
+ Compile `src/csrc/linkcheck_hook.c` and `src/csrc/linkcheck_elf.c` (from the
180
+ sdist or the repository) into the program, with `src/csrc` on the include
181
+ path; the program links libpython as embedders do. The warning category is
182
+ the same `libpython_linkcheck.LibpythonLinkWarning` that the package
183
+ exposes, and a later `libpython_linkcheck.enable()` call detects the hook
184
+ and returns `False` instead of installing a second one. See
185
+ `src/csrc/libpython_linkcheck.h` for the exact contract.
186
+
132
187
  ## Try it
133
188
 
134
189
  This builds an extension that links libpython and imports it with the hook
@@ -169,14 +224,24 @@ linked.cpython-315-x86_64-linux-gnu.so: DT_NEEDED libpython3.15.so.1.0
169
224
  exit status 1
170
225
  ```
171
226
 
172
- ## What the 0.1.0a1 alpha supports
227
+ ## What is supported
173
228
 
174
229
  Supported and tested:
175
230
 
176
- - CPython 3.11 through 3.15 on Linux (x86_64 and aarch64, glibc).
231
+ - CPython 3.11 through 3.15 on Linux (x86_64 and aarch64, glibc), and the
232
+ free-threaded builds of 3.14 and 3.15. Importing and enabling the
233
+ package keeps the GIL disabled.
234
+ - Distributions: native `manylinux_2_28` wheels (x86_64, aarch64) for
235
+ CPython 3.11–3.15 and free-threaded 3.14t/3.15t, which use the C
236
+ implementation; a pure-Python `py3-none-any` wheel for every other
237
+ platform; and an sdist, which compiles the C implementation on POSIX.
238
+ - Every activation path in [the table above](#activating-it-automatically),
239
+ each tested in a fresh venv against a real linked extension, alone and
240
+ combined.
177
241
  - Explicit activation: call `libpython_linkcheck.enable()` in each interpreter
178
- that should be checked. Only extension modules imported **after** that call
179
- are inspected.
242
+ that should be checked; the hook it installs covers only that interpreter,
243
+ including when it is a subinterpreter. Only extension modules imported
244
+ **after** that call are inspected.
180
245
  - Every extension module loaded through the import system
181
246
  (`importlib.machinery.ExtensionFileLoader`, which also serves
182
247
  `importlib.util.spec_from_file_location` and similar).
@@ -192,12 +257,6 @@ Supported and tested:
192
257
 
193
258
  Not covered yet:
194
259
 
195
- - Automatic activation (`sitecustomize`, `.pth` files, or a hook installed
196
- by an embedding application before `Py_Initialize()`).
197
- - Subinterpreters: a Python audit hook belongs to the interpreter that
198
- installed it, so `enable()` must be called in each one. This is not yet tested.
199
- - Free-threaded interpreters: their libpython names are recognized, but the
200
- hook has not yet been tested running on a free-threaded build.
201
260
  - Shared libraries opened with `ctypes` or `dlopen()` directly, and extension
202
261
  modules that were already loaded before `enable()`.
203
262
  - Other platforms: `enable()` works, but non-ELF files (Mach-O, PE) are never
@@ -0,0 +1,11 @@
1
+ libpython_linkcheck/__init__.py,sha256=oQduYDgMqyw1VM_3LvOxeMx0J7LZN4F4awrQhQwsKFQ,746
2
+ libpython_linkcheck/__main__.py,sha256=PJp3ryjaSJevsvwJsA-4h3gv_2yTuRREnpg2OK-_wJQ,1300
3
+ libpython_linkcheck/_elf.py,sha256=FIJSqbddY-PMiu4uLnsJhcNJJs9V9Ev7QGE42Fgxpxw,8842
4
+ libpython_linkcheck/_hook.py,sha256=0W2OpQYjrYle13KAV3kV8Q9ZcQqTCvgjwxgJ6eD7EBU,8224
5
+ libpython_linkcheck/_version.py,sha256=MVC3xG9U8KXXTiZ2FMZ9ARASAJV2A-Qu7UcliE-N_hI,24
6
+ libpython_linkcheck/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
7
+ libpython_linkcheck-0.1.0a2.dist-info/licenses/LICENSE,sha256=nxJKW9vh32DdsG7aSRztYSpEowhSV1m6PRAceUBXDGw,1068
8
+ libpython_linkcheck-0.1.0a2.dist-info/METADATA,sha256=5QqK6k3Pn93SycZ8kSrEtKgWikQbpWV158ceWoJKlYk,12250
9
+ libpython_linkcheck-0.1.0a2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
10
+ libpython_linkcheck-0.1.0a2.dist-info/top_level.txt,sha256=IZprL5FIqWd22Moutmpxn7-QKBZCsPfEGn2XhdxG7VE,20
11
+ libpython_linkcheck-0.1.0a2.dist-info/RECORD,,
@@ -1,11 +0,0 @@
1
- libpython_linkcheck/__init__.py,sha256=oQduYDgMqyw1VM_3LvOxeMx0J7LZN4F4awrQhQwsKFQ,746
2
- libpython_linkcheck/__main__.py,sha256=PJp3ryjaSJevsvwJsA-4h3gv_2yTuRREnpg2OK-_wJQ,1300
3
- libpython_linkcheck/_elf.py,sha256=pnkVjF0LDB0bvcR5-UcBT8rC5IzvVm1dVss42nFxAxI,7594
4
- libpython_linkcheck/_hook.py,sha256=lYXM4A-P_91MaF6NrlKm-tW345glvfX7JfG7cxbhz3E,6896
5
- libpython_linkcheck/_version.py,sha256=lmvUfjeqbjbsnD2PLlUjZbqEGZrq6yUD6t2LZsM61ak,24
6
- libpython_linkcheck/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
7
- libpython_linkcheck-0.1.0a1.dist-info/licenses/LICENSE,sha256=nxJKW9vh32DdsG7aSRztYSpEowhSV1m6PRAceUBXDGw,1068
8
- libpython_linkcheck-0.1.0a1.dist-info/METADATA,sha256=jBX3p-pqLboSo0TfVePN8gdvacw83gQUklvz78xILn0,9065
9
- libpython_linkcheck-0.1.0a1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
10
- libpython_linkcheck-0.1.0a1.dist-info/top_level.txt,sha256=IZprL5FIqWd22Moutmpxn7-QKBZCsPfEGn2XhdxG7VE,20
11
- libpython_linkcheck-0.1.0a1.dist-info/RECORD,,