libpython-linkcheck 0.1.0a1__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.
- libpython_linkcheck-0.1.0a1/LICENSE +21 -0
- libpython_linkcheck-0.1.0a1/MANIFEST.in +4 -0
- libpython_linkcheck-0.1.0a1/PKG-INFO +208 -0
- libpython_linkcheck-0.1.0a1/README.md +179 -0
- libpython_linkcheck-0.1.0a1/pyproject.toml +76 -0
- libpython_linkcheck-0.1.0a1/setup.cfg +4 -0
- libpython_linkcheck-0.1.0a1/src/libpython_linkcheck/__init__.py +22 -0
- libpython_linkcheck-0.1.0a1/src/libpython_linkcheck/__main__.py +42 -0
- libpython_linkcheck-0.1.0a1/src/libpython_linkcheck/_elf.py +207 -0
- libpython_linkcheck-0.1.0a1/src/libpython_linkcheck/_hook.py +187 -0
- libpython_linkcheck-0.1.0a1/src/libpython_linkcheck/_version.py +1 -0
- libpython_linkcheck-0.1.0a1/src/libpython_linkcheck/py.typed +0 -0
- libpython_linkcheck-0.1.0a1/src/libpython_linkcheck.egg-info/PKG-INFO +208 -0
- libpython_linkcheck-0.1.0a1/src/libpython_linkcheck.egg-info/SOURCES.txt +25 -0
- libpython_linkcheck-0.1.0a1/src/libpython_linkcheck.egg-info/dependency_links.txt +1 -0
- libpython_linkcheck-0.1.0a1/src/libpython_linkcheck.egg-info/top_level.txt +1 -0
- libpython_linkcheck-0.1.0a1/tests/conftest.py +54 -0
- libpython_linkcheck-0.1.0a1/tests/elfbuild.py +133 -0
- libpython_linkcheck-0.1.0a1/tests/extbuild.py +97 -0
- libpython_linkcheck-0.1.0a1/tests/fixtures/extmod.c +75 -0
- libpython_linkcheck-0.1.0a1/tests/pyrun.py +66 -0
- libpython_linkcheck-0.1.0a1/tests/test_cli.py +65 -0
- libpython_linkcheck-0.1.0a1/tests/test_elf.py +211 -0
- libpython_linkcheck-0.1.0a1/tests/test_hook.py +214 -0
- libpython_linkcheck-0.1.0a1/tests/test_linux_extensions.py +220 -0
- libpython_linkcheck-0.1.0a1/tests/test_readme.py +59 -0
- libpython_linkcheck-0.1.0a1/tests/test_version.py +7 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Itamar Oren
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: libpython-linkcheck
|
|
3
|
+
Version: 0.1.0a1
|
|
4
|
+
Summary: Warn when an imported Python extension directly links to libpython on Linux.
|
|
5
|
+
Author: Itamar Oren
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/itamaro/libpython-linkcheck
|
|
8
|
+
Project-URL: Source, https://github.com/itamaro/libpython-linkcheck
|
|
9
|
+
Project-URL: Issues, https://github.com/itamaro/libpython-linkcheck/issues
|
|
10
|
+
Keywords: libpython,elf,dt_needed,extension,audit-hook,linker
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
21
|
+
Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
22
|
+
Classifier: Topic :: Software Development :: Build Tools
|
|
23
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
24
|
+
Classifier: Typing :: Typed
|
|
25
|
+
Requires-Python: >=3.11
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
License-File: LICENSE
|
|
28
|
+
Dynamic: license-file
|
|
29
|
+
|
|
30
|
+
# libpython-linkcheck
|
|
31
|
+
|
|
32
|
+
Warn when an imported Python extension directly links to libpython on Linux.
|
|
33
|
+
|
|
34
|
+
On Linux, CPython extension modules should **not** link against libpython:
|
|
35
|
+
the interpreter that loads them already provides every `Py*` symbol. An
|
|
36
|
+
extension with `libpython3.X.so.1.0` in its `DT_NEEDED` entries requires that
|
|
37
|
+
exact library at load time. Under an interpreter without a shared libpython (a
|
|
38
|
+
statically linked build, such as Debian's and Ubuntu's `/usr/bin/python3`), it
|
|
39
|
+
either fails with "cannot open shared object file" or loads a second, separate
|
|
40
|
+
copy of the runtime. The manylinux policies forbid such links for these reasons.
|
|
41
|
+
|
|
42
|
+
`libpython-linkcheck` installs a CPython audit hook that inspects each
|
|
43
|
+
extension module's shared object right **before** CPython loads it, and issues
|
|
44
|
+
a `LibpythonLinkWarning` if the object's own `DT_NEEDED` entries name libpython.
|
|
45
|
+
|
|
46
|
+
## Install
|
|
47
|
+
|
|
48
|
+
```sh
|
|
49
|
+
pip install libpython-linkcheck
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The import name is `libpython_linkcheck`. It is pure Python, with no dependencies.
|
|
53
|
+
|
|
54
|
+
## Usage
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
import libpython_linkcheck
|
|
58
|
+
|
|
59
|
+
libpython_linkcheck.enable() # once, as early as possible
|
|
60
|
+
|
|
61
|
+
import some_extension # warns if some_extension's .so has DT_NEEDED libpython
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The warning names the module, the file, and the matching dependency, and
|
|
65
|
+
points at the line that did the import:
|
|
66
|
+
|
|
67
|
+
```text
|
|
68
|
+
app.py:5: LibpythonLinkWarning: extension module 'some_extension' links directly to libpython: /venv/lib/python3.15/site-packages/some_extension.cpython-315-x86_64-linux-gnu.so has DT_NEEDED libpython3.15.so.1.0
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
`enable()` returns `True` if it installed the hook and `False` if a hook was
|
|
72
|
+
already active in this interpreter. Calling it again is harmless and never
|
|
73
|
+
produces duplicate warnings. `is_enabled()` reports whether the hook is
|
|
74
|
+
active. Audit hooks cannot be removed, so the hook stays active until the
|
|
75
|
+
interpreter exits.
|
|
76
|
+
|
|
77
|
+
### Controlling the warning
|
|
78
|
+
|
|
79
|
+
`LibpythonLinkWarning` is a `RuntimeWarning` subclass, and all the normal
|
|
80
|
+
warning filters apply. With an `error` filter, the import raises
|
|
81
|
+
`LibpythonLinkWarning` before the shared object is loaded, so none of its code
|
|
82
|
+
(not even ELF constructors) runs.
|
|
83
|
+
|
|
84
|
+
In code (after `import libpython_linkcheck`):
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
import warnings
|
|
88
|
+
from libpython_linkcheck import LibpythonLinkWarning
|
|
89
|
+
|
|
90
|
+
# Fail such imports instead of warning:
|
|
91
|
+
warnings.filterwarnings("error", category=LibpythonLinkWarning)
|
|
92
|
+
# Silence one known extension (the message starts with "extension module '<name>'"):
|
|
93
|
+
warnings.filterwarnings(
|
|
94
|
+
"ignore", message=r"extension module 'legacy\._speedups'", category=LibpythonLinkWarning
|
|
95
|
+
)
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
The warning instance carries `.module` (the fully qualified module name),
|
|
99
|
+
`.filename` (the shared object), and `.needed` (a tuple of the matching
|
|
100
|
+
`DT_NEEDED` entries).
|
|
101
|
+
|
|
102
|
+
On the command line:
|
|
103
|
+
|
|
104
|
+
| Option | Effect |
|
|
105
|
+
| --- | --- |
|
|
106
|
+
| `python -Werror ...` | every warning, including this one, is an error |
|
|
107
|
+
| `python -W error::RuntimeWarning ...` | runtime warnings, including this one, are errors |
|
|
108
|
+
| `python -W "error:extension module 'foo._ext'" ...` | this warning is an error for one module (message prefix, matched literally) |
|
|
109
|
+
| `python -W error::libpython_linkcheck.LibpythonLinkWarning ...` | this warning is an error (see the note below) |
|
|
110
|
+
| `PYTHONWARNINGS=...` | same as `-W` |
|
|
111
|
+
|
|
112
|
+
**Note:** CPython resolves the category of a `-W` or `PYTHONWARNINGS` entry
|
|
113
|
+
during startup, before site-packages is on `sys.path`. For a normally
|
|
114
|
+
installed package that fails, and CPython itself prints
|
|
115
|
+
`Invalid -W option ignored: invalid module name: 'libpython_linkcheck'`.
|
|
116
|
+
When `enable()` installs the hook, it applies those dropped entries, in their
|
|
117
|
+
original order, so the filter does take effect for every import after
|
|
118
|
+
`enable()`. These entries then take precedence over filters added before
|
|
119
|
+
`enable()` was called. The other forms in the table work without this step.
|
|
120
|
+
|
|
121
|
+
### Checking files without importing them
|
|
122
|
+
|
|
123
|
+
```sh
|
|
124
|
+
python -m libpython_linkcheck build/lib*/mypkg/*.so
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
prints `FILE: DT_NEEDED libpython...` for each offending file. The exit status
|
|
128
|
+
is 0 if no file links libpython, 1 if any does, and 2 if a file could not be
|
|
129
|
+
read or is not ELF. From Python, `libpython_linkcheck.libpython_dependencies(path)`
|
|
130
|
+
returns the matching entries as a list.
|
|
131
|
+
|
|
132
|
+
## Try it
|
|
133
|
+
|
|
134
|
+
This builds an extension that links libpython and imports it with the hook
|
|
135
|
+
enabled. Copy and paste into a shell in a `python:3.15` container
|
|
136
|
+
(`podman run --rm -it docker.io/library/python:3.15-trixie bash`, or use `docker`):
|
|
137
|
+
|
|
138
|
+
<!-- readme-demo: the block below is executed by tests/test_readme.py -->
|
|
139
|
+
```sh
|
|
140
|
+
pip install libpython-linkcheck
|
|
141
|
+
mkdir demo && cd demo
|
|
142
|
+
cat > linked.c <<'EOF'
|
|
143
|
+
#include <Python.h>
|
|
144
|
+
static struct PyModuleDef def = {PyModuleDef_HEAD_INIT, "linked", NULL, 0, NULL};
|
|
145
|
+
PyMODINIT_FUNC PyInit_linked(void) { return PyModuleDef_Init(&def); }
|
|
146
|
+
EOF
|
|
147
|
+
cc -shared -fPIC $(python3-config --includes) linked.c \
|
|
148
|
+
-o linked$(python3-config --extension-suffix) \
|
|
149
|
+
-Wl,--no-as-needed $(python3-config --ldflags --embed)
|
|
150
|
+
|
|
151
|
+
# 1. Warns, then loads the module:
|
|
152
|
+
python -c 'import libpython_linkcheck; libpython_linkcheck.enable(); import linked; print("loaded", linked)'
|
|
153
|
+
# 2. With -Werror, the import fails before the shared object is loaded:
|
|
154
|
+
python -Werror -c 'import libpython_linkcheck; libpython_linkcheck.enable(); import linked' || echo "exit status $?"
|
|
155
|
+
# 3. Check the file without importing it:
|
|
156
|
+
python -m libpython_linkcheck linked*.so || echo "exit status $?"
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Expected output (paths and versions vary):
|
|
160
|
+
|
|
161
|
+
```text
|
|
162
|
+
<string>:1: LibpythonLinkWarning: extension module 'linked' links directly to libpython: /demo/linked.cpython-315-x86_64-linux-gnu.so has DT_NEEDED libpython3.15.so.1.0
|
|
163
|
+
loaded <module 'linked' from '/demo/linked.cpython-315-x86_64-linux-gnu.so'>
|
|
164
|
+
Traceback (most recent call last):
|
|
165
|
+
...
|
|
166
|
+
libpython_linkcheck.LibpythonLinkWarning: extension module 'linked' links directly to libpython: /demo/linked.cpython-315-x86_64-linux-gnu.so has DT_NEEDED libpython3.15.so.1.0
|
|
167
|
+
exit status 1
|
|
168
|
+
linked.cpython-315-x86_64-linux-gnu.so: DT_NEEDED libpython3.15.so.1.0
|
|
169
|
+
exit status 1
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
## What the 0.1.0a1 alpha supports
|
|
173
|
+
|
|
174
|
+
Supported and tested:
|
|
175
|
+
|
|
176
|
+
- CPython 3.11 through 3.15 on Linux (x86_64 and aarch64, glibc).
|
|
177
|
+
- Explicit activation: call `libpython_linkcheck.enable()` in each interpreter
|
|
178
|
+
that should be checked. Only extension modules imported **after** that call
|
|
179
|
+
are inspected.
|
|
180
|
+
- Every extension module loaded through the import system
|
|
181
|
+
(`importlib.machinery.ExtensionFileLoader`, which also serves
|
|
182
|
+
`importlib.util.spec_from_file_location` and similar).
|
|
183
|
+
- Only the extension's **own** `DT_NEEDED` entries; dependencies of its
|
|
184
|
+
dependencies are not inspected.
|
|
185
|
+
- libpython names recognized: versioned (`libpython3.12.so.1.0`,
|
|
186
|
+
`libpython3.12.so`), Stable ABI (`libpython3.so`), free-threaded
|
|
187
|
+
(`libpython3.13t.so.1.0`), and ABI-flagged (`libpython3.12d.so.1.0`)
|
|
188
|
+
names, including entries that carry a directory.
|
|
189
|
+
- Standard warning filters, `-Werror`, and `catch_warnings()`.
|
|
190
|
+
- Objects that cannot be read or parsed are skipped silently, so that
|
|
191
|
+
CPython's own loader reports the real error.
|
|
192
|
+
|
|
193
|
+
Not covered yet:
|
|
194
|
+
|
|
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
|
+
- Shared libraries opened with `ctypes` or `dlopen()` directly, and extension
|
|
202
|
+
modules that were already loaded before `enable()`.
|
|
203
|
+
- Other platforms: `enable()` works, but non-ELF files (Mach-O, PE) are never
|
|
204
|
+
reported. Other ELF platforms are untested.
|
|
205
|
+
|
|
206
|
+
## License
|
|
207
|
+
|
|
208
|
+
MIT
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
# libpython-linkcheck
|
|
2
|
+
|
|
3
|
+
Warn when an imported Python extension directly links to libpython on Linux.
|
|
4
|
+
|
|
5
|
+
On Linux, CPython extension modules should **not** link against libpython:
|
|
6
|
+
the interpreter that loads them already provides every `Py*` symbol. An
|
|
7
|
+
extension with `libpython3.X.so.1.0` in its `DT_NEEDED` entries requires that
|
|
8
|
+
exact library at load time. Under an interpreter without a shared libpython (a
|
|
9
|
+
statically linked build, such as Debian's and Ubuntu's `/usr/bin/python3`), it
|
|
10
|
+
either fails with "cannot open shared object file" or loads a second, separate
|
|
11
|
+
copy of the runtime. The manylinux policies forbid such links for these reasons.
|
|
12
|
+
|
|
13
|
+
`libpython-linkcheck` installs a CPython audit hook that inspects each
|
|
14
|
+
extension module's shared object right **before** CPython loads it, and issues
|
|
15
|
+
a `LibpythonLinkWarning` if the object's own `DT_NEEDED` entries name libpython.
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
pip install libpython-linkcheck
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The import name is `libpython_linkcheck`. It is pure Python, with no dependencies.
|
|
24
|
+
|
|
25
|
+
## Usage
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
import libpython_linkcheck
|
|
29
|
+
|
|
30
|
+
libpython_linkcheck.enable() # once, as early as possible
|
|
31
|
+
|
|
32
|
+
import some_extension # warns if some_extension's .so has DT_NEEDED libpython
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The warning names the module, the file, and the matching dependency, and
|
|
36
|
+
points at the line that did the import:
|
|
37
|
+
|
|
38
|
+
```text
|
|
39
|
+
app.py:5: LibpythonLinkWarning: extension module 'some_extension' links directly to libpython: /venv/lib/python3.15/site-packages/some_extension.cpython-315-x86_64-linux-gnu.so has DT_NEEDED libpython3.15.so.1.0
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`enable()` returns `True` if it installed the hook and `False` if a hook was
|
|
43
|
+
already active in this interpreter. Calling it again is harmless and never
|
|
44
|
+
produces duplicate warnings. `is_enabled()` reports whether the hook is
|
|
45
|
+
active. Audit hooks cannot be removed, so the hook stays active until the
|
|
46
|
+
interpreter exits.
|
|
47
|
+
|
|
48
|
+
### Controlling the warning
|
|
49
|
+
|
|
50
|
+
`LibpythonLinkWarning` is a `RuntimeWarning` subclass, and all the normal
|
|
51
|
+
warning filters apply. With an `error` filter, the import raises
|
|
52
|
+
`LibpythonLinkWarning` before the shared object is loaded, so none of its code
|
|
53
|
+
(not even ELF constructors) runs.
|
|
54
|
+
|
|
55
|
+
In code (after `import libpython_linkcheck`):
|
|
56
|
+
|
|
57
|
+
```python
|
|
58
|
+
import warnings
|
|
59
|
+
from libpython_linkcheck import LibpythonLinkWarning
|
|
60
|
+
|
|
61
|
+
# Fail such imports instead of warning:
|
|
62
|
+
warnings.filterwarnings("error", category=LibpythonLinkWarning)
|
|
63
|
+
# Silence one known extension (the message starts with "extension module '<name>'"):
|
|
64
|
+
warnings.filterwarnings(
|
|
65
|
+
"ignore", message=r"extension module 'legacy\._speedups'", category=LibpythonLinkWarning
|
|
66
|
+
)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The warning instance carries `.module` (the fully qualified module name),
|
|
70
|
+
`.filename` (the shared object), and `.needed` (a tuple of the matching
|
|
71
|
+
`DT_NEEDED` entries).
|
|
72
|
+
|
|
73
|
+
On the command line:
|
|
74
|
+
|
|
75
|
+
| Option | Effect |
|
|
76
|
+
| --- | --- |
|
|
77
|
+
| `python -Werror ...` | every warning, including this one, is an error |
|
|
78
|
+
| `python -W error::RuntimeWarning ...` | runtime warnings, including this one, are errors |
|
|
79
|
+
| `python -W "error:extension module 'foo._ext'" ...` | this warning is an error for one module (message prefix, matched literally) |
|
|
80
|
+
| `python -W error::libpython_linkcheck.LibpythonLinkWarning ...` | this warning is an error (see the note below) |
|
|
81
|
+
| `PYTHONWARNINGS=...` | same as `-W` |
|
|
82
|
+
|
|
83
|
+
**Note:** CPython resolves the category of a `-W` or `PYTHONWARNINGS` entry
|
|
84
|
+
during startup, before site-packages is on `sys.path`. For a normally
|
|
85
|
+
installed package that fails, and CPython itself prints
|
|
86
|
+
`Invalid -W option ignored: invalid module name: 'libpython_linkcheck'`.
|
|
87
|
+
When `enable()` installs the hook, it applies those dropped entries, in their
|
|
88
|
+
original order, so the filter does take effect for every import after
|
|
89
|
+
`enable()`. These entries then take precedence over filters added before
|
|
90
|
+
`enable()` was called. The other forms in the table work without this step.
|
|
91
|
+
|
|
92
|
+
### Checking files without importing them
|
|
93
|
+
|
|
94
|
+
```sh
|
|
95
|
+
python -m libpython_linkcheck build/lib*/mypkg/*.so
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
prints `FILE: DT_NEEDED libpython...` for each offending file. The exit status
|
|
99
|
+
is 0 if no file links libpython, 1 if any does, and 2 if a file could not be
|
|
100
|
+
read or is not ELF. From Python, `libpython_linkcheck.libpython_dependencies(path)`
|
|
101
|
+
returns the matching entries as a list.
|
|
102
|
+
|
|
103
|
+
## Try it
|
|
104
|
+
|
|
105
|
+
This builds an extension that links libpython and imports it with the hook
|
|
106
|
+
enabled. Copy and paste into a shell in a `python:3.15` container
|
|
107
|
+
(`podman run --rm -it docker.io/library/python:3.15-trixie bash`, or use `docker`):
|
|
108
|
+
|
|
109
|
+
<!-- readme-demo: the block below is executed by tests/test_readme.py -->
|
|
110
|
+
```sh
|
|
111
|
+
pip install libpython-linkcheck
|
|
112
|
+
mkdir demo && cd demo
|
|
113
|
+
cat > linked.c <<'EOF'
|
|
114
|
+
#include <Python.h>
|
|
115
|
+
static struct PyModuleDef def = {PyModuleDef_HEAD_INIT, "linked", NULL, 0, NULL};
|
|
116
|
+
PyMODINIT_FUNC PyInit_linked(void) { return PyModuleDef_Init(&def); }
|
|
117
|
+
EOF
|
|
118
|
+
cc -shared -fPIC $(python3-config --includes) linked.c \
|
|
119
|
+
-o linked$(python3-config --extension-suffix) \
|
|
120
|
+
-Wl,--no-as-needed $(python3-config --ldflags --embed)
|
|
121
|
+
|
|
122
|
+
# 1. Warns, then loads the module:
|
|
123
|
+
python -c 'import libpython_linkcheck; libpython_linkcheck.enable(); import linked; print("loaded", linked)'
|
|
124
|
+
# 2. With -Werror, the import fails before the shared object is loaded:
|
|
125
|
+
python -Werror -c 'import libpython_linkcheck; libpython_linkcheck.enable(); import linked' || echo "exit status $?"
|
|
126
|
+
# 3. Check the file without importing it:
|
|
127
|
+
python -m libpython_linkcheck linked*.so || echo "exit status $?"
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Expected output (paths and versions vary):
|
|
131
|
+
|
|
132
|
+
```text
|
|
133
|
+
<string>:1: LibpythonLinkWarning: extension module 'linked' links directly to libpython: /demo/linked.cpython-315-x86_64-linux-gnu.so has DT_NEEDED libpython3.15.so.1.0
|
|
134
|
+
loaded <module 'linked' from '/demo/linked.cpython-315-x86_64-linux-gnu.so'>
|
|
135
|
+
Traceback (most recent call last):
|
|
136
|
+
...
|
|
137
|
+
libpython_linkcheck.LibpythonLinkWarning: extension module 'linked' links directly to libpython: /demo/linked.cpython-315-x86_64-linux-gnu.so has DT_NEEDED libpython3.15.so.1.0
|
|
138
|
+
exit status 1
|
|
139
|
+
linked.cpython-315-x86_64-linux-gnu.so: DT_NEEDED libpython3.15.so.1.0
|
|
140
|
+
exit status 1
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
## What the 0.1.0a1 alpha supports
|
|
144
|
+
|
|
145
|
+
Supported and tested:
|
|
146
|
+
|
|
147
|
+
- CPython 3.11 through 3.15 on Linux (x86_64 and aarch64, glibc).
|
|
148
|
+
- Explicit activation: call `libpython_linkcheck.enable()` in each interpreter
|
|
149
|
+
that should be checked. Only extension modules imported **after** that call
|
|
150
|
+
are inspected.
|
|
151
|
+
- Every extension module loaded through the import system
|
|
152
|
+
(`importlib.machinery.ExtensionFileLoader`, which also serves
|
|
153
|
+
`importlib.util.spec_from_file_location` and similar).
|
|
154
|
+
- Only the extension's **own** `DT_NEEDED` entries; dependencies of its
|
|
155
|
+
dependencies are not inspected.
|
|
156
|
+
- libpython names recognized: versioned (`libpython3.12.so.1.0`,
|
|
157
|
+
`libpython3.12.so`), Stable ABI (`libpython3.so`), free-threaded
|
|
158
|
+
(`libpython3.13t.so.1.0`), and ABI-flagged (`libpython3.12d.so.1.0`)
|
|
159
|
+
names, including entries that carry a directory.
|
|
160
|
+
- Standard warning filters, `-Werror`, and `catch_warnings()`.
|
|
161
|
+
- Objects that cannot be read or parsed are skipped silently, so that
|
|
162
|
+
CPython's own loader reports the real error.
|
|
163
|
+
|
|
164
|
+
Not covered yet:
|
|
165
|
+
|
|
166
|
+
- Automatic activation (`sitecustomize`, `.pth` files, or a hook installed
|
|
167
|
+
by an embedding application before `Py_Initialize()`).
|
|
168
|
+
- Subinterpreters: a Python audit hook belongs to the interpreter that
|
|
169
|
+
installed it, so `enable()` must be called in each one. This is not yet tested.
|
|
170
|
+
- Free-threaded interpreters: their libpython names are recognized, but the
|
|
171
|
+
hook has not yet been tested running on a free-threaded build.
|
|
172
|
+
- Shared libraries opened with `ctypes` or `dlopen()` directly, and extension
|
|
173
|
+
modules that were already loaded before `enable()`.
|
|
174
|
+
- Other platforms: `enable()` works, but non-ELF files (Mach-O, PE) are never
|
|
175
|
+
reported. Other ELF platforms are untested.
|
|
176
|
+
|
|
177
|
+
## License
|
|
178
|
+
|
|
179
|
+
MIT
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "libpython-linkcheck"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Warn when an imported Python extension directly links to libpython on Linux."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.11"
|
|
13
|
+
authors = [{ name = "Itamar Oren" }]
|
|
14
|
+
keywords = ["libpython", "elf", "dt_needed", "extension", "audit-hook", "linker"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 3 - Alpha",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Operating System :: POSIX :: Linux",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Programming Language :: Python :: 3.13",
|
|
24
|
+
"Programming Language :: Python :: 3.14",
|
|
25
|
+
"Programming Language :: Python :: 3.15",
|
|
26
|
+
"Programming Language :: Python :: Implementation :: CPython",
|
|
27
|
+
"Topic :: Software Development :: Build Tools",
|
|
28
|
+
"Topic :: Software Development :: Quality Assurance",
|
|
29
|
+
"Typing :: Typed",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.urls]
|
|
33
|
+
Homepage = "https://github.com/itamaro/libpython-linkcheck"
|
|
34
|
+
Source = "https://github.com/itamaro/libpython-linkcheck"
|
|
35
|
+
Issues = "https://github.com/itamaro/libpython-linkcheck/issues"
|
|
36
|
+
|
|
37
|
+
[dependency-groups]
|
|
38
|
+
test = ["pytest==9.2.0"]
|
|
39
|
+
lint = ["ruff==0.17.6"]
|
|
40
|
+
dist = ["build==1.6.1", "twine==7.0.0"]
|
|
41
|
+
dev = [
|
|
42
|
+
{ include-group = "test" },
|
|
43
|
+
{ include-group = "lint" },
|
|
44
|
+
{ include-group = "dist" },
|
|
45
|
+
]
|
|
46
|
+
|
|
47
|
+
[tool.setuptools.dynamic]
|
|
48
|
+
version = { attr = "libpython_linkcheck._version.__version__" }
|
|
49
|
+
|
|
50
|
+
[tool.setuptools.packages.find]
|
|
51
|
+
where = ["src"]
|
|
52
|
+
|
|
53
|
+
[tool.setuptools.package-data]
|
|
54
|
+
libpython_linkcheck = ["py.typed"]
|
|
55
|
+
|
|
56
|
+
[tool.pytest.ini_options]
|
|
57
|
+
minversion = "8.0"
|
|
58
|
+
testpaths = ["tests"]
|
|
59
|
+
pythonpath = ["tests"]
|
|
60
|
+
addopts = ["-ra", "--strict-markers", "--strict-config", "--import-mode=importlib"]
|
|
61
|
+
xfail_strict = true
|
|
62
|
+
filterwarnings = ["error"]
|
|
63
|
+
|
|
64
|
+
[tool.ruff]
|
|
65
|
+
line-length = 99
|
|
66
|
+
target-version = "py311"
|
|
67
|
+
|
|
68
|
+
[tool.ruff.lint]
|
|
69
|
+
select = ["E", "W", "F", "I", "B", "UP", "SIM", "RUF", "PT", "PL", "C4", "PIE", "RET"]
|
|
70
|
+
ignore = [
|
|
71
|
+
"PLR2004", # magic values are clearer than named constants for ELF fields
|
|
72
|
+
"PLR0913",
|
|
73
|
+
]
|
|
74
|
+
|
|
75
|
+
[tool.ruff.lint.per-file-ignores]
|
|
76
|
+
"tests/**" = ["PLR0915", "S101"]
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
"""Warn when an imported Python extension directly links to libpython.
|
|
2
|
+
|
|
3
|
+
Call :func:`enable` to install an audit hook in the current interpreter.
|
|
4
|
+
Before CPython loads an extension module, the hook reads the shared object's
|
|
5
|
+
own DT_NEEDED entries and issues a :class:`LibpythonLinkWarning` if one of
|
|
6
|
+
them names libpython. The warning goes through the normal warnings
|
|
7
|
+
machinery, so filters apply; with ``-Werror`` the import fails before the
|
|
8
|
+
object is loaded.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from ._elf import ELFError, libpython_dependencies
|
|
12
|
+
from ._hook import LibpythonLinkWarning, enable, is_enabled
|
|
13
|
+
from ._version import __version__
|
|
14
|
+
|
|
15
|
+
__all__ = [
|
|
16
|
+
"ELFError",
|
|
17
|
+
"LibpythonLinkWarning",
|
|
18
|
+
"__version__",
|
|
19
|
+
"enable",
|
|
20
|
+
"is_enabled",
|
|
21
|
+
"libpython_dependencies",
|
|
22
|
+
]
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
"""Command line: report ELF objects whose own DT_NEEDED entries name libpython.
|
|
2
|
+
|
|
3
|
+
Exit status: 0 if no file links libpython, 1 if at least one does, 2 if any
|
|
4
|
+
file could not be read or is not a valid ELF object.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import argparse
|
|
10
|
+
import sys
|
|
11
|
+
from collections.abc import Sequence
|
|
12
|
+
|
|
13
|
+
from ._elf import ELFError, libpython_dependencies
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def main(argv: Sequence[str] | None = None) -> int:
|
|
17
|
+
parser = argparse.ArgumentParser(
|
|
18
|
+
prog="python -m libpython_linkcheck",
|
|
19
|
+
description=(
|
|
20
|
+
"Report ELF shared objects (e.g. extension modules) whose own DT_NEEDED "
|
|
21
|
+
"entries name libpython. Exit status: 0 none found, 1 found, 2 error."
|
|
22
|
+
),
|
|
23
|
+
)
|
|
24
|
+
parser.add_argument("files", nargs="+", metavar="FILE", help="ELF object to inspect")
|
|
25
|
+
args = parser.parse_args(argv)
|
|
26
|
+
|
|
27
|
+
found = error = False
|
|
28
|
+
for path in args.files:
|
|
29
|
+
try:
|
|
30
|
+
needed = libpython_dependencies(path)
|
|
31
|
+
except (OSError, ELFError) as e:
|
|
32
|
+
print(f"{path}: error: {e}", file=sys.stderr)
|
|
33
|
+
error = True
|
|
34
|
+
continue
|
|
35
|
+
if needed:
|
|
36
|
+
print(f"{path}: DT_NEEDED {', '.join(needed)}")
|
|
37
|
+
found = True
|
|
38
|
+
return 2 if error else 1 if found else 0
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
if __name__ == "__main__":
|
|
42
|
+
sys.exit(main())
|