diff --git a/README.rst b/README.rst index 0312436..f008b38 100644 --- a/README.rst +++ b/README.rst @@ -17,6 +17,9 @@ defer-imports A library that implements `PEP 690 `_–esque lazy imports in pure Python, but at a user's behest within a context manager. +.. contents:: Overview + :depth: 2 + Installation ============ @@ -76,73 +79,68 @@ Use Cases Extra: Console Usage -------------------- -``defer-imports`` works while within a regular Python REPL, as long as that work is being done in a package being imported and not with direct usage of the ``defer_imports.until_use`` context manager. To directly use the context manager, use the included interactive console: - -- From the command line:: - - > python -m defer_imports - Python 3.11.9 (tags/v3.11.9:de54cf5, Apr 2 2024, 10:12:12) [MSC v.1938 64 bit (AMD64)] on win32 - Type "help", "copyright", "credits" or "license" for more information. - (DeferredInteractiveConsole) - >>> import defer_imports - >>> with defer_imports.until_use: - ... import typing - ... - >>> import sys - >>> "typing" in sys.modules +.. class:: details + +**Not relevant if you only plan to use ``defer-imports`` as a library.** + ``defer-imports`` works while within a regular Python REPL, as long as that work is being done in a package being imported and not with direct usage of the ``defer_imports.until_use`` context manager. To directly use the context manager, use the included interactive console: + + - From the command line:: + + > python -m defer_imports + Python 3.11.9 (tags/v3.11.9:de54cf5, Apr 2 2024, 10:12:12) [MSC v.1938 64 bit (AMD64)] on win32 + Type "help", "copyright", "credits" or "license" for more information. + (DeferredInteractiveConsole) + >>> import defer_imports + >>> with defer_imports.until_use: + ... import typing + ... + >>> import sys + >>> "typing" in sys.modules + False + >>> typing + + >>> "typing" in sys.modules + True + + - From within a standard Python interpreter: + + .. code-block:: pycon + + >>> from defer_imports import console + >>> console.interact() + Python 3.11.9 (tags/v3.11.9:de54cf5, Apr 2 2024, 10:12:12) [MSC v.1938 64 bit (AMD64)] on win32 + Type "help", "copyright", "credits" or "license" for more information. + (DeferredInteractiveConsole) + >>> import defer_imports + >>> with defer_imports.until_use: + ... import typing + ... + >>> import sys + >>> "typing" in sys.modules + False + >>> typing + + >>> "typing" in sys.modules + True + + + Additionally, if you're using IPython in a terminal or in a Jupyter environment, there is a function you can call to ensure the context manager works there as well: + + .. code-block:: ipython + + In [1]: from defer_imports import console + In [2]: console.instrument_ipython() + In [3]: import defer_imports + In [4]: with defer_imports.until_use: + ...: import numpy + ...: + In [5]: import sys + In [6]: print("numpy" in sys.modules) False - >>> typing - - >>> "typing" in sys.modules + In [7]: numpy + In [8]: print("numpy" in sys.modules) True -- From within a standard Python interpreter: - - .. code-block:: pycon - - >>> from defer_imports import console - >>> console.interact() - Python 3.11.9 (tags/v3.11.9:de54cf5, Apr 2 2024, 10:12:12) [MSC v.1938 64 bit (AMD64)] on win32 - Type "help", "copyright", "credits" or "license" for more information. - (DeferredInteractiveConsole) - >>> import defer_imports - >>> with defer_imports.until_use: - ... import typing - ... - >>> import sys - >>> "typing" in sys.modules - False - >>> typing - - >>> "typing" in sys.modules - True - - -Additionally, if you're using IPython in a terminal or in a Jupyter environment, there is a function you can call to ensure the context manager works there as well: - -.. code-block:: ipython - - In [1]: from defer_imports import console - - In [2]: console.instrument_ipython() - - In [3]: import defer_imports - - In [4]: with defer_imports.until_use: - ...: import numpy - ...: - - In [5]: import sys - - In [6]: "numpy" in sys.modules - - In [7]: print("numpy" in sys.modules) - False - - In [8]: numpy - - In [9]: print("numpy" in sys.modules) - True Features ========