unwrapt 1.0.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.
- unwrapt-1.0.0a1/LICENSE +24 -0
- unwrapt-1.0.0a1/PKG-INFO +238 -0
- unwrapt-1.0.0a1/README.md +206 -0
- unwrapt-1.0.0a1/pyproject.toml +113 -0
- unwrapt-1.0.0a1/setup.cfg +4 -0
- unwrapt-1.0.0a1/src/unwrapt/__init__.py +79 -0
- unwrapt-1.0.0a1/src/unwrapt/_compat.py +56 -0
- unwrapt-1.0.0a1/src/unwrapt/_config.py +289 -0
- unwrapt-1.0.0a1/src/unwrapt/_hook.py +216 -0
- unwrapt-1.0.0a1/src/unwrapt/_profile.py +310 -0
- unwrapt-1.0.0a1/src/unwrapt/_report.py +1024 -0
- unwrapt-1.0.0a1/src/unwrapt/bootstrap.py +37 -0
- unwrapt-1.0.0a1/src/unwrapt/py.typed +0 -0
- unwrapt-1.0.0a1/src/unwrapt/report.py +11 -0
- unwrapt-1.0.0a1/src/unwrapt.egg-info/PKG-INFO +238 -0
- unwrapt-1.0.0a1/src/unwrapt.egg-info/SOURCES.txt +32 -0
- unwrapt-1.0.0a1/src/unwrapt.egg-info/dependency_links.txt +1 -0
- unwrapt-1.0.0a1/src/unwrapt.egg-info/entry_points.txt +2 -0
- unwrapt-1.0.0a1/src/unwrapt.egg-info/not-zip-safe +1 -0
- unwrapt-1.0.0a1/src/unwrapt.egg-info/requires.txt +12 -0
- unwrapt-1.0.0a1/src/unwrapt.egg-info/top_level.txt +1 -0
- unwrapt-1.0.0a1/tests/test_bootstrap.py +105 -0
- unwrapt-1.0.0a1/tests/test_config.py +293 -0
- unwrapt-1.0.0a1/tests/test_inert_import.py +66 -0
- unwrapt-1.0.0a1/tests/test_lazy_modules.py +313 -0
- unwrapt-1.0.0a1/tests/test_profile.py +442 -0
- unwrapt-1.0.0a1/tests/test_profile_py315.py +131 -0
- unwrapt-1.0.0a1/tests/test_report.py +394 -0
- unwrapt-1.0.0a1/tests/test_report_cli.py +99 -0
- unwrapt-1.0.0a1/tests/test_shim.py +627 -0
- unwrapt-1.0.0a1/tests/test_shim_py315.py +207 -0
- unwrapt-1.0.0a1/tests/test_typing_packaging.py +27 -0
- unwrapt-1.0.0a1/tests/test_version.py +83 -0
- unwrapt-1.0.0a1/tests/test_worked_example.py +205 -0
unwrapt-1.0.0a1/LICENSE
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
Copyright (c) 2026, Graham Dumpleton
|
|
2
|
+
All rights reserved.
|
|
3
|
+
|
|
4
|
+
Redistribution and use in source and binary forms, with or without
|
|
5
|
+
modification, are permitted provided that the following conditions are met:
|
|
6
|
+
|
|
7
|
+
* Redistributions of source code must retain the above copyright notice, this
|
|
8
|
+
list of conditions and the following disclaimer.
|
|
9
|
+
|
|
10
|
+
* Redistributions in binary form must reproduce the above copyright notice,
|
|
11
|
+
this list of conditions and the following disclaimer in the documentation
|
|
12
|
+
and/or other materials provided with the distribution.
|
|
13
|
+
|
|
14
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
15
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
16
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
17
|
+
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
|
|
18
|
+
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
19
|
+
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
20
|
+
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
21
|
+
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
22
|
+
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
23
|
+
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
24
|
+
POSSIBILITY OF SUCH DAMAGE.
|
unwrapt-1.0.0a1/PKG-INFO
ADDED
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: unwrapt
|
|
3
|
+
Version: 1.0.0a1
|
|
4
|
+
Summary: Defer whole-module imports until first use on Pythons below 3.15, emulating PEP 810's __lazy_modules__, with a profile mode that reports what imports cost and what is worth deferring. Built on wrapt.
|
|
5
|
+
Author-email: Graham Dumpleton <Graham.Dumpleton@gmail.com>
|
|
6
|
+
License-Expression: BSD-2-Clause
|
|
7
|
+
Project-URL: Homepage, https://github.com/GrahamDumpleton/unwrapt
|
|
8
|
+
Project-URL: Documentation, https://unwrapt.readthedocs.io
|
|
9
|
+
Project-URL: Bug Tracker, https://github.com/GrahamDumpleton/unwrapt/issues/
|
|
10
|
+
Keywords: lazy imports,import,startup time,PEP 810,wrapt
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
17
|
+
Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
18
|
+
Requires-Python: >=3.12
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
Requires-Dist: wrapt>=2.4.1
|
|
22
|
+
Provides-Extra: dev
|
|
23
|
+
Requires-Dist: mypy; extra == "dev"
|
|
24
|
+
Requires-Dist: pytest; extra == "dev"
|
|
25
|
+
Requires-Dist: ruff; extra == "dev"
|
|
26
|
+
Requires-Dist: setuptools; extra == "dev"
|
|
27
|
+
Provides-Extra: docs
|
|
28
|
+
Requires-Dist: myst-parser; extra == "docs"
|
|
29
|
+
Requires-Dist: sphinx; extra == "docs"
|
|
30
|
+
Requires-Dist: sphinx-rtd-theme; extra == "docs"
|
|
31
|
+
Dynamic: license-file
|
|
32
|
+
|
|
33
|
+
<img src="https://raw.githubusercontent.com/GrahamDumpleton/unwrapt/develop/docs/_static/unwrapt-logo.svg" alt="unwrapt" width="240">
|
|
34
|
+
|
|
35
|
+
# unwrapt
|
|
36
|
+
|
|
37
|
+
**Don't open it until you need it.**
|
|
38
|
+
|
|
39
|
+
[](https://github.com/GrahamDumpleton/unwrapt/actions/workflows/build-test-release.yml)
|
|
40
|
+
[](https://unwrapt.readthedocs.io)
|
|
41
|
+
|
|
42
|
+
Every `import` in your program is a present your program unwraps
|
|
43
|
+
immediately, whether or not it uses what is inside. unwrapt leaves the
|
|
44
|
+
wrapping on until first use. It defers whole-module imports until the
|
|
45
|
+
moment they are touched, cutting start-up time, without changing your
|
|
46
|
+
application's code.
|
|
47
|
+
|
|
48
|
+
Python 3.15 adds lazy imports (PEP 810): a `lazy import x` statement,
|
|
49
|
+
and a module-level `__lazy_modules__` list that keeps the imports it
|
|
50
|
+
names deferred while remaining ordinary valid code on older Pythons.
|
|
51
|
+
unwrapt brings the `__lazy_modules__` behaviour to Python 3.12 to 3.14,
|
|
52
|
+
emulating it on top of [wrapt](https://github.com/GrahamDumpleton/wrapt)
|
|
53
|
+
so that the same source behaves the same on every version, and it
|
|
54
|
+
ships a profile mode that measures what your imports actually cost and
|
|
55
|
+
reports what is worth deferring, on any version including 3.15.
|
|
56
|
+
|
|
57
|
+
It is a sibling project to [wrapt](https://github.com/GrahamDumpleton/wrapt)
|
|
58
|
+
and
|
|
59
|
+
[autowrapt](https://github.com/GrahamDumpleton/autowrapt), and works
|
|
60
|
+
without changing your application code: with
|
|
61
|
+
[autowrapt](https://github.com/GrahamDumpleton/autowrapt) installed,
|
|
62
|
+
one environment variable activates it.
|
|
63
|
+
|
|
64
|
+
> **Status: beta, ahead of 1.0.0.** Pre-releases are published to
|
|
65
|
+
> PyPI, and until 1.0.0 is final a plain `pip install unwrapt` picks
|
|
66
|
+
> up the latest pre-release automatically, so there is no need to pin
|
|
67
|
+
> a specific version. Small API changes are still possible before
|
|
68
|
+
> 1.0.0. Reports of it working, or not, on real code, and of what
|
|
69
|
+
> confused or was missing, go to the
|
|
70
|
+
> [issue tracker](https://github.com/GrahamDumpleton/unwrapt/issues).
|
|
71
|
+
|
|
72
|
+
## Installation
|
|
73
|
+
|
|
74
|
+
unwrapt is on [PyPI](https://pypi.org/project/unwrapt/):
|
|
75
|
+
|
|
76
|
+
```console
|
|
77
|
+
$ pip install unwrapt
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
or with uv:
|
|
81
|
+
|
|
82
|
+
```console
|
|
83
|
+
$ uv add unwrapt
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
autowrapt is the companion that injects unwrapt at interpreter startup
|
|
87
|
+
without any application change. It is deliberately not a dependency of
|
|
88
|
+
unwrapt; install it alongside the application you want to affect:
|
|
89
|
+
|
|
90
|
+
```console
|
|
91
|
+
$ pip install autowrapt
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## At a glance
|
|
95
|
+
|
|
96
|
+
Your module declares what to defer, exactly as PEP 810 specifies, and
|
|
97
|
+
the code stays valid on every Python version:
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
# app.py
|
|
101
|
+
|
|
102
|
+
__lazy_modules__ = ["xml.dom"]
|
|
103
|
+
import xml.dom
|
|
104
|
+
|
|
105
|
+
print("loaded at startup:", "xml.dom" in sys.modules) # False
|
|
106
|
+
|
|
107
|
+
xml.dom.Node # first use unwraps it
|
|
108
|
+
|
|
109
|
+
print("loaded after use:", "xml.dom" in sys.modules) # True
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Run it with the bootstrap, and nothing else changes:
|
|
113
|
+
|
|
114
|
+
```console
|
|
115
|
+
$ AUTOWRAPT_BOOTSTRAP=unwrapt python app.py
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
The import returns a lazy proxy instead of the module; the first use
|
|
119
|
+
of the name imports the real module and swaps it into place, so after
|
|
120
|
+
first use there is no residual overhead. On Python 3.15 the
|
|
121
|
+
interpreter does all of this natively and unwrapt is not involved.
|
|
122
|
+
|
|
123
|
+
## What it does
|
|
124
|
+
|
|
125
|
+
- **Shim mode (Python 3.12 to 3.14).** With
|
|
126
|
+
`AUTOWRAPT_BOOTSTRAP=unwrapt`, unwrapt replaces
|
|
127
|
+
`builtins.__import__` with a hook that returns a wrapt lazy proxy
|
|
128
|
+
for each whole-module import your modules mark in their own
|
|
129
|
+
`__lazy_modules__`, reifying on first use. Chained to whatever
|
|
130
|
+
import wrappers were already installed, cheap on the pass-through
|
|
131
|
+
path, and never raising from its own bookkeeping.
|
|
132
|
+
|
|
133
|
+
- **Wrapping things you can't edit.** A JSON configuration names
|
|
134
|
+
imports to defer in modules whose source you do not control:
|
|
135
|
+
`UNWRAPT_CONFIG=lazy.json`. On Python 3.15 and later this is the
|
|
136
|
+
only thing unwrapt does: the interpreter handles `__lazy_modules__`
|
|
137
|
+
natively, unwrapt never touches it or native behaviour, and with no
|
|
138
|
+
configuration it installs nothing at all.
|
|
139
|
+
|
|
140
|
+
- **Peeking at the label.** `UNWRAPT_DEBUG=1` logs each deferred
|
|
141
|
+
import to stderr, and the active mode at startup.
|
|
142
|
+
|
|
143
|
+
- **Finding what is worth wrapping.** `UNWRAPT_PROFILE=1` records
|
|
144
|
+
every import call of a real run, with timings and the tree of nested
|
|
145
|
+
imports, and reports the candidates ranked by cumulative time, the
|
|
146
|
+
heavy modules by self time, the import chains that explain why each
|
|
147
|
+
one loaded, and the best cut in each chain. Every row shows both
|
|
148
|
+
routes: what native 3.15 lazy imports can defer, and what the shim
|
|
149
|
+
can, with the reasons spelled out. The report comes as text or JSON,
|
|
150
|
+
and the [choosing what to
|
|
151
|
+
defer](https://unwrapt.readthedocs.io/en/latest/choosing-what-to-defer.html)
|
|
152
|
+
guide is the way to turn it into decisions.
|
|
153
|
+
|
|
154
|
+
## What it is not
|
|
155
|
+
|
|
156
|
+
- **Not a replacement for PEP 810.** On 3.15+ the interpreter is the
|
|
157
|
+
mechanism; unwrapt only applies the external configuration there,
|
|
158
|
+
and never reads `__lazy_modules__` or alters native behaviour.
|
|
159
|
+
|
|
160
|
+
- **Not a source rewriter.** Nothing about your files changes; the
|
|
161
|
+
profile mode only reports.
|
|
162
|
+
|
|
163
|
+
- **Not able to defer every import form.** `from x import y` and
|
|
164
|
+
`import a.b as c` stay eager under the shim on Pythons below 3.15:
|
|
165
|
+
the attribute fetch resolves the proxy immediately. The profile
|
|
166
|
+
flags exactly these rows, deferrable natively on 3.15 but not by the
|
|
167
|
+
shim, and the guide covers the rewrite.
|
|
168
|
+
|
|
169
|
+
## Known limitations
|
|
170
|
+
|
|
171
|
+
- `from x import y` and `import a.b as c` stay eager in shim mode.
|
|
172
|
+
|
|
173
|
+
- Only module-level imports are considered. Function bodies and class
|
|
174
|
+
bodies are left alone (function-level imports are already deferred
|
|
175
|
+
until the function runs).
|
|
176
|
+
|
|
177
|
+
- A `try/except ImportError` around an import is invisible to the
|
|
178
|
+
hook: deferring a guarded optional dependency moves its ImportError
|
|
179
|
+
to first use. Do not list those.
|
|
180
|
+
|
|
181
|
+
- Already-imported modules are returned as-is. In particular, wrapt
|
|
182
|
+
itself and the standard library modules it imports (json, inspect,
|
|
183
|
+
copy, subprocess and friends) are always in sys.modules before the
|
|
184
|
+
hook goes in, so they can never be deferred in a process running
|
|
185
|
+
unwrapt.
|
|
186
|
+
|
|
187
|
+
- Older Pythons import eagerly without unwrapt. Never rely on
|
|
188
|
+
laziness for correctness: import side effects and circular imports
|
|
189
|
+
that only work lazily behave differently, and errors surface at
|
|
190
|
+
first use instead of at the import statement.
|
|
191
|
+
|
|
192
|
+
- Imports through `importlib.import_module`, the C import API, and
|
|
193
|
+
anything imported before the bootstrap runs are unaffected.
|
|
194
|
+
|
|
195
|
+
- There is per-import hook overhead for every import statement in the
|
|
196
|
+
process while the shim is installed; the non-deferred path exits
|
|
197
|
+
early and stays small, but it is not zero.
|
|
198
|
+
|
|
199
|
+
- Proxies copied elsewhere before first use (assigned to another name,
|
|
200
|
+
bound into a container) remain proxies and still work, with the
|
|
201
|
+
small proxy overhead.
|
|
202
|
+
|
|
203
|
+
## Documentation
|
|
204
|
+
|
|
205
|
+
Full documentation is at [unwrapt.readthedocs.io](https://unwrapt.readthedocs.io).
|
|
206
|
+
Start with the [getting started](https://unwrapt.readthedocs.io/en/latest/getting-started.html)
|
|
207
|
+
page: everything on it can be pasted into a Python interpreter. For
|
|
208
|
+
the profile mode, start with the [choosing what to
|
|
209
|
+
defer](https://unwrapt.readthedocs.io/en/latest/choosing-what-to-defer.html)
|
|
210
|
+
strategy guide, which turns the report into decisions step by step.
|
|
211
|
+
|
|
212
|
+
## Developed with AI
|
|
213
|
+
|
|
214
|
+
This package was developed with the help of AI coding assistants,
|
|
215
|
+
working to the author's design and direction, with the author
|
|
216
|
+
reviewing what they produce. If you would rather not use software
|
|
217
|
+
produced that way, that is understood, and this package is not for
|
|
218
|
+
you.
|
|
219
|
+
|
|
220
|
+
## Requirements
|
|
221
|
+
|
|
222
|
+
- Python 3.12 or later.
|
|
223
|
+
|
|
224
|
+
- wrapt 2.4.1 or later.
|
|
225
|
+
|
|
226
|
+
- For zero-code injection: autowrapt 2.0 or later (not a dependency of
|
|
227
|
+
unwrapt).
|
|
228
|
+
|
|
229
|
+
## Issues
|
|
230
|
+
|
|
231
|
+
Bug reports and feature requests go to the
|
|
232
|
+
[issue tracker](https://github.com/GrahamDumpleton/unwrapt/issues).
|
|
233
|
+
A report is easiest to act on when it names the unwrapt and Python
|
|
234
|
+
versions and includes a small application that reproduces the problem.
|
|
235
|
+
|
|
236
|
+
## License
|
|
237
|
+
|
|
238
|
+
BSD 2-Clause, see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
<img src="https://raw.githubusercontent.com/GrahamDumpleton/unwrapt/develop/docs/_static/unwrapt-logo.svg" alt="unwrapt" width="240">
|
|
2
|
+
|
|
3
|
+
# unwrapt
|
|
4
|
+
|
|
5
|
+
**Don't open it until you need it.**
|
|
6
|
+
|
|
7
|
+
[](https://github.com/GrahamDumpleton/unwrapt/actions/workflows/build-test-release.yml)
|
|
8
|
+
[](https://unwrapt.readthedocs.io)
|
|
9
|
+
|
|
10
|
+
Every `import` in your program is a present your program unwraps
|
|
11
|
+
immediately, whether or not it uses what is inside. unwrapt leaves the
|
|
12
|
+
wrapping on until first use. It defers whole-module imports until the
|
|
13
|
+
moment they are touched, cutting start-up time, without changing your
|
|
14
|
+
application's code.
|
|
15
|
+
|
|
16
|
+
Python 3.15 adds lazy imports (PEP 810): a `lazy import x` statement,
|
|
17
|
+
and a module-level `__lazy_modules__` list that keeps the imports it
|
|
18
|
+
names deferred while remaining ordinary valid code on older Pythons.
|
|
19
|
+
unwrapt brings the `__lazy_modules__` behaviour to Python 3.12 to 3.14,
|
|
20
|
+
emulating it on top of [wrapt](https://github.com/GrahamDumpleton/wrapt)
|
|
21
|
+
so that the same source behaves the same on every version, and it
|
|
22
|
+
ships a profile mode that measures what your imports actually cost and
|
|
23
|
+
reports what is worth deferring, on any version including 3.15.
|
|
24
|
+
|
|
25
|
+
It is a sibling project to [wrapt](https://github.com/GrahamDumpleton/wrapt)
|
|
26
|
+
and
|
|
27
|
+
[autowrapt](https://github.com/GrahamDumpleton/autowrapt), and works
|
|
28
|
+
without changing your application code: with
|
|
29
|
+
[autowrapt](https://github.com/GrahamDumpleton/autowrapt) installed,
|
|
30
|
+
one environment variable activates it.
|
|
31
|
+
|
|
32
|
+
> **Status: beta, ahead of 1.0.0.** Pre-releases are published to
|
|
33
|
+
> PyPI, and until 1.0.0 is final a plain `pip install unwrapt` picks
|
|
34
|
+
> up the latest pre-release automatically, so there is no need to pin
|
|
35
|
+
> a specific version. Small API changes are still possible before
|
|
36
|
+
> 1.0.0. Reports of it working, or not, on real code, and of what
|
|
37
|
+
> confused or was missing, go to the
|
|
38
|
+
> [issue tracker](https://github.com/GrahamDumpleton/unwrapt/issues).
|
|
39
|
+
|
|
40
|
+
## Installation
|
|
41
|
+
|
|
42
|
+
unwrapt is on [PyPI](https://pypi.org/project/unwrapt/):
|
|
43
|
+
|
|
44
|
+
```console
|
|
45
|
+
$ pip install unwrapt
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
or with uv:
|
|
49
|
+
|
|
50
|
+
```console
|
|
51
|
+
$ uv add unwrapt
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
autowrapt is the companion that injects unwrapt at interpreter startup
|
|
55
|
+
without any application change. It is deliberately not a dependency of
|
|
56
|
+
unwrapt; install it alongside the application you want to affect:
|
|
57
|
+
|
|
58
|
+
```console
|
|
59
|
+
$ pip install autowrapt
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## At a glance
|
|
63
|
+
|
|
64
|
+
Your module declares what to defer, exactly as PEP 810 specifies, and
|
|
65
|
+
the code stays valid on every Python version:
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
# app.py
|
|
69
|
+
|
|
70
|
+
__lazy_modules__ = ["xml.dom"]
|
|
71
|
+
import xml.dom
|
|
72
|
+
|
|
73
|
+
print("loaded at startup:", "xml.dom" in sys.modules) # False
|
|
74
|
+
|
|
75
|
+
xml.dom.Node # first use unwraps it
|
|
76
|
+
|
|
77
|
+
print("loaded after use:", "xml.dom" in sys.modules) # True
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Run it with the bootstrap, and nothing else changes:
|
|
81
|
+
|
|
82
|
+
```console
|
|
83
|
+
$ AUTOWRAPT_BOOTSTRAP=unwrapt python app.py
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The import returns a lazy proxy instead of the module; the first use
|
|
87
|
+
of the name imports the real module and swaps it into place, so after
|
|
88
|
+
first use there is no residual overhead. On Python 3.15 the
|
|
89
|
+
interpreter does all of this natively and unwrapt is not involved.
|
|
90
|
+
|
|
91
|
+
## What it does
|
|
92
|
+
|
|
93
|
+
- **Shim mode (Python 3.12 to 3.14).** With
|
|
94
|
+
`AUTOWRAPT_BOOTSTRAP=unwrapt`, unwrapt replaces
|
|
95
|
+
`builtins.__import__` with a hook that returns a wrapt lazy proxy
|
|
96
|
+
for each whole-module import your modules mark in their own
|
|
97
|
+
`__lazy_modules__`, reifying on first use. Chained to whatever
|
|
98
|
+
import wrappers were already installed, cheap on the pass-through
|
|
99
|
+
path, and never raising from its own bookkeeping.
|
|
100
|
+
|
|
101
|
+
- **Wrapping things you can't edit.** A JSON configuration names
|
|
102
|
+
imports to defer in modules whose source you do not control:
|
|
103
|
+
`UNWRAPT_CONFIG=lazy.json`. On Python 3.15 and later this is the
|
|
104
|
+
only thing unwrapt does: the interpreter handles `__lazy_modules__`
|
|
105
|
+
natively, unwrapt never touches it or native behaviour, and with no
|
|
106
|
+
configuration it installs nothing at all.
|
|
107
|
+
|
|
108
|
+
- **Peeking at the label.** `UNWRAPT_DEBUG=1` logs each deferred
|
|
109
|
+
import to stderr, and the active mode at startup.
|
|
110
|
+
|
|
111
|
+
- **Finding what is worth wrapping.** `UNWRAPT_PROFILE=1` records
|
|
112
|
+
every import call of a real run, with timings and the tree of nested
|
|
113
|
+
imports, and reports the candidates ranked by cumulative time, the
|
|
114
|
+
heavy modules by self time, the import chains that explain why each
|
|
115
|
+
one loaded, and the best cut in each chain. Every row shows both
|
|
116
|
+
routes: what native 3.15 lazy imports can defer, and what the shim
|
|
117
|
+
can, with the reasons spelled out. The report comes as text or JSON,
|
|
118
|
+
and the [choosing what to
|
|
119
|
+
defer](https://unwrapt.readthedocs.io/en/latest/choosing-what-to-defer.html)
|
|
120
|
+
guide is the way to turn it into decisions.
|
|
121
|
+
|
|
122
|
+
## What it is not
|
|
123
|
+
|
|
124
|
+
- **Not a replacement for PEP 810.** On 3.15+ the interpreter is the
|
|
125
|
+
mechanism; unwrapt only applies the external configuration there,
|
|
126
|
+
and never reads `__lazy_modules__` or alters native behaviour.
|
|
127
|
+
|
|
128
|
+
- **Not a source rewriter.** Nothing about your files changes; the
|
|
129
|
+
profile mode only reports.
|
|
130
|
+
|
|
131
|
+
- **Not able to defer every import form.** `from x import y` and
|
|
132
|
+
`import a.b as c` stay eager under the shim on Pythons below 3.15:
|
|
133
|
+
the attribute fetch resolves the proxy immediately. The profile
|
|
134
|
+
flags exactly these rows, deferrable natively on 3.15 but not by the
|
|
135
|
+
shim, and the guide covers the rewrite.
|
|
136
|
+
|
|
137
|
+
## Known limitations
|
|
138
|
+
|
|
139
|
+
- `from x import y` and `import a.b as c` stay eager in shim mode.
|
|
140
|
+
|
|
141
|
+
- Only module-level imports are considered. Function bodies and class
|
|
142
|
+
bodies are left alone (function-level imports are already deferred
|
|
143
|
+
until the function runs).
|
|
144
|
+
|
|
145
|
+
- A `try/except ImportError` around an import is invisible to the
|
|
146
|
+
hook: deferring a guarded optional dependency moves its ImportError
|
|
147
|
+
to first use. Do not list those.
|
|
148
|
+
|
|
149
|
+
- Already-imported modules are returned as-is. In particular, wrapt
|
|
150
|
+
itself and the standard library modules it imports (json, inspect,
|
|
151
|
+
copy, subprocess and friends) are always in sys.modules before the
|
|
152
|
+
hook goes in, so they can never be deferred in a process running
|
|
153
|
+
unwrapt.
|
|
154
|
+
|
|
155
|
+
- Older Pythons import eagerly without unwrapt. Never rely on
|
|
156
|
+
laziness for correctness: import side effects and circular imports
|
|
157
|
+
that only work lazily behave differently, and errors surface at
|
|
158
|
+
first use instead of at the import statement.
|
|
159
|
+
|
|
160
|
+
- Imports through `importlib.import_module`, the C import API, and
|
|
161
|
+
anything imported before the bootstrap runs are unaffected.
|
|
162
|
+
|
|
163
|
+
- There is per-import hook overhead for every import statement in the
|
|
164
|
+
process while the shim is installed; the non-deferred path exits
|
|
165
|
+
early and stays small, but it is not zero.
|
|
166
|
+
|
|
167
|
+
- Proxies copied elsewhere before first use (assigned to another name,
|
|
168
|
+
bound into a container) remain proxies and still work, with the
|
|
169
|
+
small proxy overhead.
|
|
170
|
+
|
|
171
|
+
## Documentation
|
|
172
|
+
|
|
173
|
+
Full documentation is at [unwrapt.readthedocs.io](https://unwrapt.readthedocs.io).
|
|
174
|
+
Start with the [getting started](https://unwrapt.readthedocs.io/en/latest/getting-started.html)
|
|
175
|
+
page: everything on it can be pasted into a Python interpreter. For
|
|
176
|
+
the profile mode, start with the [choosing what to
|
|
177
|
+
defer](https://unwrapt.readthedocs.io/en/latest/choosing-what-to-defer.html)
|
|
178
|
+
strategy guide, which turns the report into decisions step by step.
|
|
179
|
+
|
|
180
|
+
## Developed with AI
|
|
181
|
+
|
|
182
|
+
This package was developed with the help of AI coding assistants,
|
|
183
|
+
working to the author's design and direction, with the author
|
|
184
|
+
reviewing what they produce. If you would rather not use software
|
|
185
|
+
produced that way, that is understood, and this package is not for
|
|
186
|
+
you.
|
|
187
|
+
|
|
188
|
+
## Requirements
|
|
189
|
+
|
|
190
|
+
- Python 3.12 or later.
|
|
191
|
+
|
|
192
|
+
- wrapt 2.4.1 or later.
|
|
193
|
+
|
|
194
|
+
- For zero-code injection: autowrapt 2.0 or later (not a dependency of
|
|
195
|
+
unwrapt).
|
|
196
|
+
|
|
197
|
+
## Issues
|
|
198
|
+
|
|
199
|
+
Bug reports and feature requests go to the
|
|
200
|
+
[issue tracker](https://github.com/GrahamDumpleton/unwrapt/issues).
|
|
201
|
+
A report is easiest to act on when it names the unwrapt and Python
|
|
202
|
+
versions and includes a small application that reproduces the problem.
|
|
203
|
+
|
|
204
|
+
## License
|
|
205
|
+
|
|
206
|
+
BSD 2-Clause, see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
# Reading the dynamic version imports the package. unwrapt's
|
|
3
|
+
# __init__.py stays inert: it imports nothing beyond the standard
|
|
4
|
+
# library and installs no hook, so wrapt is not needed at build time.
|
|
5
|
+
requires = ["setuptools>=62.0", "wheel"]
|
|
6
|
+
build-backend = "setuptools.build_meta"
|
|
7
|
+
|
|
8
|
+
[project]
|
|
9
|
+
name = "unwrapt"
|
|
10
|
+
dynamic = ["version"]
|
|
11
|
+
description = "Defer whole-module imports until first use on Pythons below 3.15, emulating PEP 810's __lazy_modules__, with a profile mode that reports what imports cost and what is worth deferring. Built on wrapt."
|
|
12
|
+
readme = "README.md"
|
|
13
|
+
license = "BSD-2-Clause"
|
|
14
|
+
license-files = ["LICENSE"]
|
|
15
|
+
authors = [
|
|
16
|
+
{name = "Graham Dumpleton", email = "Graham.Dumpleton@gmail.com"}
|
|
17
|
+
]
|
|
18
|
+
requires-python = ">=3.12"
|
|
19
|
+
keywords = ["lazy imports", "import", "startup time", "PEP 810", "wrapt"]
|
|
20
|
+
classifiers = [
|
|
21
|
+
"Development Status :: 4 - Beta",
|
|
22
|
+
"Programming Language :: Python :: 3",
|
|
23
|
+
"Programming Language :: Python :: 3.12",
|
|
24
|
+
"Programming Language :: Python :: 3.13",
|
|
25
|
+
"Programming Language :: Python :: 3.14",
|
|
26
|
+
"Programming Language :: Python :: 3.15",
|
|
27
|
+
"Programming Language :: Python :: Implementation :: CPython",
|
|
28
|
+
]
|
|
29
|
+
dependencies = [
|
|
30
|
+
"wrapt>=2.4.1",
|
|
31
|
+
]
|
|
32
|
+
|
|
33
|
+
[project.urls]
|
|
34
|
+
Homepage = "https://github.com/GrahamDumpleton/unwrapt"
|
|
35
|
+
Documentation = "https://unwrapt.readthedocs.io"
|
|
36
|
+
"Bug Tracker" = "https://github.com/GrahamDumpleton/unwrapt/issues/"
|
|
37
|
+
|
|
38
|
+
# The zero-code injection trigger, in the shape autowrapt consumes:
|
|
39
|
+
# AUTOWRAPT_BOOTSTRAP=unwrapt names this entry point group, which
|
|
40
|
+
# autowrapt hands to wrapt.discover_post_import_hooks() at interpreter
|
|
41
|
+
# startup. Each entry maps a trigger module to a callback; hooking os,
|
|
42
|
+
# which is always already imported by then, makes the callback fire
|
|
43
|
+
# immediately at startup, before the application's own imports. Inert
|
|
44
|
+
# metadata unless autowrapt is installed and the environment variable
|
|
45
|
+
# is set; unwrapt itself has no dependency on autowrapt and never
|
|
46
|
+
# imports it.
|
|
47
|
+
|
|
48
|
+
[project.entry-points.unwrapt]
|
|
49
|
+
os = "unwrapt.bootstrap:bootstrap"
|
|
50
|
+
|
|
51
|
+
[project.optional-dependencies]
|
|
52
|
+
dev = [
|
|
53
|
+
"mypy",
|
|
54
|
+
"pytest",
|
|
55
|
+
"ruff",
|
|
56
|
+
"setuptools",
|
|
57
|
+
]
|
|
58
|
+
docs = [
|
|
59
|
+
"myst-parser",
|
|
60
|
+
"sphinx",
|
|
61
|
+
"sphinx-rtd-theme",
|
|
62
|
+
]
|
|
63
|
+
|
|
64
|
+
[tool.setuptools]
|
|
65
|
+
package-dir = {"" = "src"}
|
|
66
|
+
zip-safe = false
|
|
67
|
+
packages = ["unwrapt"]
|
|
68
|
+
|
|
69
|
+
[tool.setuptools.package-data]
|
|
70
|
+
unwrapt = ["py.typed"]
|
|
71
|
+
|
|
72
|
+
[tool.setuptools.dynamic]
|
|
73
|
+
version = {attr = "unwrapt.__version__"}
|
|
74
|
+
|
|
75
|
+
[dependency-groups]
|
|
76
|
+
test = [
|
|
77
|
+
# autowrapt is a test dependency only, so the end to end bootstrap
|
|
78
|
+
# tests can run: the package itself neither depends on it nor
|
|
79
|
+
# imports it, and the tests skip themselves when it is absent
|
|
80
|
+
# (the CI plain install job runs without it).
|
|
81
|
+
"autowrapt",
|
|
82
|
+
"pytest",
|
|
83
|
+
]
|
|
84
|
+
dev = [
|
|
85
|
+
{include-group = "test"},
|
|
86
|
+
"mypy",
|
|
87
|
+
"ruff",
|
|
88
|
+
"setuptools",
|
|
89
|
+
]
|
|
90
|
+
|
|
91
|
+
[tool.pytest.ini_options]
|
|
92
|
+
testpaths = ["tests"]
|
|
93
|
+
|
|
94
|
+
[tool.mypy]
|
|
95
|
+
python_version = "3.12"
|
|
96
|
+
strict = true
|
|
97
|
+
files = ["src/unwrapt", "tests"]
|
|
98
|
+
|
|
99
|
+
[tool.ruff]
|
|
100
|
+
line-length = 88
|
|
101
|
+
target-version = "py312"
|
|
102
|
+
|
|
103
|
+
[tool.ruff.lint]
|
|
104
|
+
# Version information is defined before the imports in __init__.py.
|
|
105
|
+
per-file-ignores = {"src/unwrapt/__init__.py" = ["E402"]}
|
|
106
|
+
select = [
|
|
107
|
+
"E", # pycodestyle errors
|
|
108
|
+
"W", # pycodestyle warnings
|
|
109
|
+
"F", # pyflakes
|
|
110
|
+
"I", # isort
|
|
111
|
+
"UP", # pyupgrade
|
|
112
|
+
"B", # flake8-bugbear
|
|
113
|
+
]
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
"""
|
|
2
|
+
unwrapt defers whole-module imports until first use, without changing
|
|
3
|
+
application code.
|
|
4
|
+
|
|
5
|
+
On Pythons below 3.15 it emulates the __lazy_modules__ mechanism of
|
|
6
|
+
PEP 810 by replacing builtins.__import__ with a hook that returns a
|
|
7
|
+
lazy proxy for each marked import. From Python 3.15, where the
|
|
8
|
+
interpreter provides the mechanism natively, it applies only an
|
|
9
|
+
external configuration of extra deferrals. It is built on wrapt,
|
|
10
|
+
designed to be injected with autowrapt, and has a profile mode that
|
|
11
|
+
reports what an application's imports cost and what is worth
|
|
12
|
+
deferring.
|
|
13
|
+
|
|
14
|
+
Importing this package must stay inert: it installs nothing and
|
|
15
|
+
imports nothing beyond the standard library. The build backend imports
|
|
16
|
+
it to read the version, and importing it at any time must have no
|
|
17
|
+
effect on the running process. install() is the entry point that does
|
|
18
|
+
the work.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def _format_version(parts: tuple[str, ...]) -> str:
|
|
23
|
+
base = ".".join(parts[:3])
|
|
24
|
+
|
|
25
|
+
if len(parts) == 3:
|
|
26
|
+
return base
|
|
27
|
+
|
|
28
|
+
suffix = parts[3]
|
|
29
|
+
return (
|
|
30
|
+
f"{base}.{suffix}" if suffix.startswith(("dev", "post")) else f"{base}{suffix}"
|
|
31
|
+
)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
__version_info__: tuple[str, ...] = ("1", "0", "0", "a1")
|
|
35
|
+
__version__ = _format_version(__version_info__)
|
|
36
|
+
|
|
37
|
+
from unwrapt._compat import is_installed
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def install(module: object = None) -> bool:
|
|
41
|
+
"""Install the unwrapt import hook for this process.
|
|
42
|
+
|
|
43
|
+
The mode is chosen once, here, from the environment. With
|
|
44
|
+
UNWRAPT_PROFILE set, the recording hook of profile mode is
|
|
45
|
+
installed and no deferral happens: the two modes are mutually
|
|
46
|
+
exclusive in one process by design, because profiling an
|
|
47
|
+
already-deferred program measures something different. Otherwise
|
|
48
|
+
the shim hook is installed, subject to the Python version rules
|
|
49
|
+
described in the documentation: below 3.15 it defers imports
|
|
50
|
+
marked by the importing module's own __lazy_modules__ and by the
|
|
51
|
+
external configuration, and from 3.15, where the interpreter
|
|
52
|
+
handles __lazy_modules__ natively, it applies only the external
|
|
53
|
+
configuration and installs nothing when there is none.
|
|
54
|
+
|
|
55
|
+
Calling install() a second time does nothing, whatever mode was
|
|
56
|
+
installed first.
|
|
57
|
+
|
|
58
|
+
The module argument is ignored. It exists so the function can serve
|
|
59
|
+
directly as the autowrapt post import hook callback, which is
|
|
60
|
+
handed the trigger module (os, per the entry point) and carries no
|
|
61
|
+
information.
|
|
62
|
+
|
|
63
|
+
Returns True when this call installed a hook, False when one was
|
|
64
|
+
already installed or there was nothing to install.
|
|
65
|
+
"""
|
|
66
|
+
|
|
67
|
+
from unwrapt import _config
|
|
68
|
+
from unwrapt._hook import install_shim
|
|
69
|
+
from unwrapt._profile import install_profile
|
|
70
|
+
|
|
71
|
+
settings = _config.read_settings()
|
|
72
|
+
|
|
73
|
+
if settings.profile:
|
|
74
|
+
return install_profile(settings)
|
|
75
|
+
|
|
76
|
+
return install_shim(settings)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
__all__ = ["__version__", "__version_info__", "install", "is_installed"]
|