ipython-smart-await 0.1.0__py3-none-any.whl

ipython_smart_await-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: ipython-smart-await
+Version: 0.1.0
+Summary: Auto-await coroutine results (calls, subscripts, item-assignment) in the IPython REPL.
+Project-URL: Homepage, https://github.com/doronz88/ipython-smart-await
+Project-URL: Repository, https://github.com/doronz88/ipython-smart-await
+Project-URL: Issues, https://github.com/doronz88/ipython-smart-await/issues
+Author-email: Doron Zarhi <doronz@kayhut.com>, Benjy Wiener <benjywiener@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,await,extension,ipython,jupyter,repl
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: IPython
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: ipython>=8
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# ipython-smart-await
+
+Auto-`await` coroutine results in the IPython REPL — drive a pure-`async` API without typing
+`await` everywhere.
+
+When loaded, the extension rewrites each input cell so that expressions which evaluate to a
+coroutine are awaited automatically on IPython's loop runner.
+
+## Install
+
+```bash
+pip install ipython-smart-await
+```
+
+## Usage
+
+```python
+%load_ext smart_await
+```
+
+Then, given some async API bound to `p`:
+
+```python
+p.get_pid()          # -> awaited automatically (no `await` needed)
+a[0]                 # -> awaited if `a.__getitem__` returns a coroutine
+a[0] = 7             # -> routed to `a.setindex(0, 7)` (awaited) when `a` has an async `setindex`
+```
+
+### Opting out
+
+Wrap a call in `...( )` to get the raw, un-awaited value:
+
+```python
+coro = ...(p.get_pid())   # `coro` is the coroutine itself
+```
+
+Cells that already use `await` / `async` constructs are left untouched.
+
+## How it works
+
+The extension installs an `ast` transformer (an IPython AST transformer) that wraps:
+
+- **calls** (`foo()`) and **subscript reads** (`a[0]`) in a helper that awaits the result only if
+  it is a coroutine (non-coroutines pass through unchanged);
+- **single-target subscript assignment** (`a[0] = v`) into a call that routes to an async
+  `setindex(key, value)` when the target exposes one, otherwise a normal item assignment — so
+  dicts, lists, numpy arrays, etc. are unaffected.
+
+## License
+
+MIT

ipython_smart_await-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+smart_await/__init__.py,sha256=6GXF9GQ-ZVJ85GB_LuGWXkCEoZwUTgtBmng2In9pXGs,4855
+ipython_smart_await-0.1.0.dist-info/METADATA,sha256=XYYMHrKrHax_sAFq3dRPH2KUSwgBFl6Drc4ECrYoIfA,2625
+ipython_smart_await-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+ipython_smart_await-0.1.0.dist-info/licenses/LICENSE,sha256=ie6PhMw578kaNgE6OBe92yIftXs_aWLGppprmIYsYzI,1082
+ipython_smart_await-0.1.0.dist-info/RECORD,,

ipython_smart_await-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

ipython_smart_await-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Doron Zarhi, Benjy Wiener
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

smart_await/__init__.py

@@ -0,0 +1,110 @@
+"""Auto-await coroutine results in the IPython REPL.
+
+Loading this extension (``%load_ext smart_await``) rewrites each input cell so that
+expressions which evaluate to a coroutine are awaited automatically:
+
+- calls:               ``foo()``        -> awaited if ``foo()`` returns a coroutine
+- subscript reads:     ``a[0]``         -> awaited if ``a.__getitem__`` returns a coroutine
+- subscript assigns:   ``a[0] = 7``     -> routed to ``a.setindex(0, 7)`` (awaited) when ``a``
+                                           exposes an async ``setindex``; otherwise a normal
+                                           ``a[0] = 7``
+
+Wrap any call in ``...( )`` to opt out and get the raw (un-awaited) value, e.g. ``...(foo())``.
+
+The cell is left untouched when it already uses ``await``/``async`` constructs.
+"""
+
+import ast
+import asyncio
+import builtins
+import warnings
+from functools import partial
+from typing import Any
+
+from IPython.core.interactiveshell import InteractiveShell
+
+
+__version__ = "0.1.0"
+__all__ = ["load_ipython_extension"]
+
+
+def _maybe_await(ip: InteractiveShell, obj: object) -> object:
+    """Await ``obj`` on the shell's loop runner if it is a coroutine, else return it unchanged."""
+    if asyncio.iscoroutine(obj):
+        return ip.loop_runner(obj)
+    return obj
+
+
+def _setitem(ip: InteractiveShell, target: Any, key: object, value: object) -> None:
+    """Backing for rewritten ``target[key] = value``.
+
+    Objects whose ``__setitem__`` can't be awaited may instead expose an async ``setindex``.
+    Route through it (awaited) when present; otherwise fall back to normal item assignment so
+    dicts/lists/etc. are unaffected.
+    """
+    setindex = getattr(target, "setindex", None)
+    if setindex is None:
+        target[key] = value
+        return
+    _maybe_await(ip, setindex(key, value))
+
+
+class _SmartAwaitTransformer(ast.NodeTransformer):
+    def __init__(self, ip: InteractiveShell) -> None:
+        super().__init__()
+        self.ip: InteractiveShell = ip
+
+    def visit_Module(self, node: ast.Module) -> ast.Module:
+        # Only transform cells that don't already use async constructs (await / async for / ...).
+        unparsed = ast.unparse(node)
+        if not self.ip.should_run_async(unparsed, transformed_cell=unparsed):
+            self.generic_visit(node)
+            ast.fix_missing_locations(node)
+        return node
+
+    def visit_Call(self, node: ast.Call) -> ast.AST:
+        match node:
+            # Skip anything inside `...(<expr>)` (explicit opt-out).
+            case ast.Call(ast.Constant(value=builtins.Ellipsis), args=[inner]):
+                return inner
+
+        visited_node = self.generic_visit(node)
+        assert isinstance(visited_node, ast.expr)
+        return ast.Call(func=ast.Name(_maybe_await.__name__, ctx=ast.Load()), args=[visited_node], keywords=[])
+
+    def visit_Subscript(self, node: ast.Subscript) -> ast.AST:
+        visited_node = self.generic_visit(node)
+        assert isinstance(visited_node, ast.expr)
+        # Only reads yield a (possibly awaitable) value; never wrap an assignment/deletion target.
+        if not isinstance(node.ctx, ast.Load):
+            return visited_node
+        return ast.Call(func=ast.Name(_maybe_await.__name__, ctx=ast.Load()), args=[visited_node], keywords=[])
+
+    def visit_Assign(self, node: ast.Assign) -> ast.AST:
+        visited_node = self.generic_visit(node)
+        assert isinstance(visited_node, ast.Assign)
+        # Rewrite `target[key] = value` into `_setitem(target, key, value)` so subscript assignment
+        # can be awaited. Only the simple single-target, non-slice form is rewritten; everything
+        # else (plain names, tuples, slices) is left as-is.
+        match visited_node.targets:
+            case [ast.Subscript(value=target, slice=key, ctx=ast.Store())] if not isinstance(key, ast.Slice):
+                return ast.Expr(
+                    value=ast.Call(
+                        func=ast.Name(_setitem.__name__, ctx=ast.Load()),
+                        args=[target, key, visited_node.value],
+                        keywords=[],
+                    )
+                )
+        return visited_node
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> ast.AsyncFunctionDef:
+        # Don't descend into `async def`s; they manage their own awaiting.
+        return node
+
+
+def load_ipython_extension(ip: InteractiveShell) -> None:
+    """Load the extension: register the helpers and the AST transformer."""
+    ip.user_ns_hidden[_maybe_await.__name__] = ip.user_ns[_maybe_await.__name__] = partial(_maybe_await, ip)
+    ip.user_ns_hidden[_setitem.__name__] = ip.user_ns[_setitem.__name__] = partial(_setitem, ip)
+    ip.ast_transformers.append(_SmartAwaitTransformer(ip))
+    warnings.filterwarnings("ignore", message=r"'ellipsis' object is not callable", category=SyntaxWarning)