ipython-smart-await 0.1.0__tar.gz

ipython_smart_await-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: release
+
+# Publishes to PyPI via Trusted Publishing (OIDC) when a GitHub Release is published.
+# No API token is used: configure the trusted publisher on PyPI for this project, workflow
+# `release.yml`, and environment `pypi`.
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Check metadata
+        run: |
+          pip install twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ipython_smart_await-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,36 @@
+name: test
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v3
+        with:
+          version: 0.14.2
+      - name: ruff check
+        run: ruff check --no-fix
+      - name: ruff format --check
+        run: ruff format --check
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install --upgrade pip && pip install -e ".[test]"
+      - name: Run tests
+        run: pytest -v

ipython_smart_await-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.ipynb_checkpoints/

ipython_smart_await-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.14.2
+  hooks:
+    # Run the linter.
+    - id: ruff-check
+    # Run the formatter.
+    - id: ruff-format

ipython_smart_await-0.1.0/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.

ipython_smart_await-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,51 @@
+# 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/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ipython-smart-await"
+version = "0.1.0"
+description = "Auto-await coroutine results (calls, subscripts, item-assignment) in the IPython REPL."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Doron Zarhi", email = "doronz@kayhut.com" },
+    { name = "Benjy Wiener", email = "benjywiener@gmail.com" },
+]
+keywords = ["ipython", "asyncio", "await", "repl", "extension", "jupyter"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: IPython",
+    "Framework :: Jupyter",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["ipython>=8"]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/doronz88/ipython-smart-await"
+Repository = "https://github.com/doronz88/ipython-smart-await"
+Issues = "https://github.com/doronz88/ipython-smart-await/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["smart_await"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+fix = true
+
+[tool.ruff.lint]
+select = [
+    # flake8-2020
+    "YTT",
+    # flake8-bugbear
+    "B",
+    # flake8-builtins
+    "A",
+    # flake8-comprehensions
+    "C4",
+    # flake8-debugger
+    "T10",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+    # pycodestyle
+    "E",
+    "W",
+    # pyflakes
+    "F",
+    # pygrep-hooks
+    "PGH",
+    # pyupgrade
+    "UP",
+    # ruff
+    "RUF",
+    # tryceratops
+    "TRY",
+]
+ignore = [
+    # LineTooLong
+    "E501",
+    # Custom error classes
+    "TRY003",
+    # Abstract `raise` to an inner function
+    "TRY301",
+    # Use of `functools.lru_cache` or `functools.cache` on methods can lead to memory leaks
+    "B019",
+]
+
+[tool.ruff.lint.isort]
+lines-after-imports = 2
+extra-standard-library = ["typing_extensions"]
+
+[tool.ruff.format]
+preview = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ipython_smart_await-0.1.0/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)

ipython_smart_await-0.1.0/tests/test_smart_await.py

@@ -0,0 +1,107 @@
+import ast
+import asyncio
+
+import pytest
+from IPython.core.interactiveshell import InteractiveShell
+
+import smart_await
+
+
+@pytest.fixture
+def ip() -> InteractiveShell:
+    shell = InteractiveShell.instance()
+    # Drive top-level awaits synchronously to completion for the tests.
+    shell.loop_runner = lambda coro: asyncio.new_event_loop().run_until_complete(coro)
+    # Reset any transformers/namespace left by a previous test.
+    shell.ast_transformers = [t for t in shell.ast_transformers if type(t).__name__ != "_SmartAwaitTransformer"]
+    smart_await.load_ipython_extension(shell)
+    return shell
+
+
+def _rewrite(ip: InteractiveShell, src: str) -> str:
+    tree = ast.parse(src)
+    for transformer in ip.ast_transformers:
+        tree = transformer.visit(tree)
+    ast.fix_missing_locations(tree)
+    return ast.unparse(tree)
+
+
+class FakeSym:
+    """Minimal async-symbol stand-in: coroutine __getitem__, async setindex, un-awaitable __setitem__."""
+
+    def __init__(self) -> None:
+        self.store: dict = {}
+
+    def __getitem__(self, index):
+        async def _get():
+            return self.store.get(index)
+
+        return _get()
+
+    async def setindex(self, index, value) -> None:
+        self.store[index] = value
+
+    def __setitem__(self, index, value) -> None:
+        raise TypeError("use setindex")
+
+
+def test_call_is_wrapped(ip: InteractiveShell) -> None:
+    assert _rewrite(ip, "foo()") == "_maybe_await(foo())"
+
+
+def test_subscript_read_is_wrapped(ip: InteractiveShell) -> None:
+    assert _rewrite(ip, "a[0]") == "_maybe_await(a[0])"
+
+
+def test_subscript_assign_is_rewritten(ip: InteractiveShell) -> None:
+    assert _rewrite(ip, "a[0] = 7") == "_setitem(a, 0, 7)"
+
+
+def test_plain_assign_untouched(ip: InteractiveShell) -> None:
+    assert _rewrite(ip, "x = 9") == "x = 9"
+
+
+def test_slice_assign_untouched(ip: InteractiveShell) -> None:
+    assert _rewrite(ip, "a[1:2] = 3") == "a[1:2] = 3"
+
+
+def test_ellipsis_opt_out(ip: InteractiveShell) -> None:
+    assert _rewrite(ip, "...(foo())") == "foo()"
+
+
+def test_call_auto_awaited(ip: InteractiveShell) -> None:
+    async def foo():
+        return 42
+
+    ip.user_ns["foo"] = foo
+    assert ip.run_cell("foo()").result == 42
+
+
+def test_subscript_read_auto_awaited(ip: InteractiveShell) -> None:
+    a = FakeSym()
+    a.store[0] = "hello"
+    ip.user_ns["a"] = a
+    assert ip.run_cell("a[0]").result == "hello"
+
+
+def test_subscript_assign_routes_to_setindex(ip: InteractiveShell) -> None:
+    a = FakeSym()
+    ip.user_ns["a"] = a
+    assert ip.run_cell("a[0] = 7").success
+    assert a.store == {0: 7}
+
+
+def test_dict_assign_unaffected(ip: InteractiveShell) -> None:
+    ip.user_ns["d"] = {}
+    assert ip.run_cell("d['k'] = 5").success
+    assert ip.user_ns["d"] == {"k": 5}
+
+
+def test_ellipsis_returns_raw_coroutine(ip: InteractiveShell) -> None:
+    async def foo():
+        return 1
+
+    ip.user_ns["foo"] = foo
+    result = ip.run_cell("...(foo())").result
+    assert asyncio.iscoroutine(result)
+    result.close()