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.
Files changed (34) hide show
  1. unwrapt-1.0.0a1/LICENSE +24 -0
  2. unwrapt-1.0.0a1/PKG-INFO +238 -0
  3. unwrapt-1.0.0a1/README.md +206 -0
  4. unwrapt-1.0.0a1/pyproject.toml +113 -0
  5. unwrapt-1.0.0a1/setup.cfg +4 -0
  6. unwrapt-1.0.0a1/src/unwrapt/__init__.py +79 -0
  7. unwrapt-1.0.0a1/src/unwrapt/_compat.py +56 -0
  8. unwrapt-1.0.0a1/src/unwrapt/_config.py +289 -0
  9. unwrapt-1.0.0a1/src/unwrapt/_hook.py +216 -0
  10. unwrapt-1.0.0a1/src/unwrapt/_profile.py +310 -0
  11. unwrapt-1.0.0a1/src/unwrapt/_report.py +1024 -0
  12. unwrapt-1.0.0a1/src/unwrapt/bootstrap.py +37 -0
  13. unwrapt-1.0.0a1/src/unwrapt/py.typed +0 -0
  14. unwrapt-1.0.0a1/src/unwrapt/report.py +11 -0
  15. unwrapt-1.0.0a1/src/unwrapt.egg-info/PKG-INFO +238 -0
  16. unwrapt-1.0.0a1/src/unwrapt.egg-info/SOURCES.txt +32 -0
  17. unwrapt-1.0.0a1/src/unwrapt.egg-info/dependency_links.txt +1 -0
  18. unwrapt-1.0.0a1/src/unwrapt.egg-info/entry_points.txt +2 -0
  19. unwrapt-1.0.0a1/src/unwrapt.egg-info/not-zip-safe +1 -0
  20. unwrapt-1.0.0a1/src/unwrapt.egg-info/requires.txt +12 -0
  21. unwrapt-1.0.0a1/src/unwrapt.egg-info/top_level.txt +1 -0
  22. unwrapt-1.0.0a1/tests/test_bootstrap.py +105 -0
  23. unwrapt-1.0.0a1/tests/test_config.py +293 -0
  24. unwrapt-1.0.0a1/tests/test_inert_import.py +66 -0
  25. unwrapt-1.0.0a1/tests/test_lazy_modules.py +313 -0
  26. unwrapt-1.0.0a1/tests/test_profile.py +442 -0
  27. unwrapt-1.0.0a1/tests/test_profile_py315.py +131 -0
  28. unwrapt-1.0.0a1/tests/test_report.py +394 -0
  29. unwrapt-1.0.0a1/tests/test_report_cli.py +99 -0
  30. unwrapt-1.0.0a1/tests/test_shim.py +627 -0
  31. unwrapt-1.0.0a1/tests/test_shim_py315.py +207 -0
  32. unwrapt-1.0.0a1/tests/test_typing_packaging.py +27 -0
  33. unwrapt-1.0.0a1/tests/test_version.py +83 -0
  34. unwrapt-1.0.0a1/tests/test_worked_example.py +205 -0
@@ -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.
@@ -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
+ [![Tests](https://github.com/GrahamDumpleton/unwrapt/actions/workflows/build-test-release.yml/badge.svg?branch=develop)](https://github.com/GrahamDumpleton/unwrapt/actions/workflows/build-test-release.yml)
40
+ [![Documentation](https://readthedocs.org/projects/unwrapt/badge/?version=latest)](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
+ [![Tests](https://github.com/GrahamDumpleton/unwrapt/actions/workflows/build-test-release.yml/badge.svg?branch=develop)](https://github.com/GrahamDumpleton/unwrapt/actions/workflows/build-test-release.yml)
8
+ [![Documentation](https://readthedocs.org/projects/unwrapt/badge/?version=latest)](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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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"]