fastweb3-console 0.1.0__py3-none-any.whl

fastweb3_console-0.1.0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: fastweb3-console
+Version: 0.1.0
+Summary: Interactive console and script runner for working with EVM blockchains.
+Author: iamdefinitelyahuman
+License: MIT
+Project-URL: Homepage, https://github.com/iamdefinitelyahuman/fastweb3-console
+Project-URL: Repository, https://github.com/iamdefinitelyahuman/fastweb3-console
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastweb3-objects<0.2.0,>=0.1.3
+Requires-Dist: lazy-object-proxy>=1.12.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: prompt-toolkit<4.0.0,>=3.0.52
+Requires-Dist: pygments>=2.18
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: pre-commit>=3; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: mkdocs>=1.6; extra == "dev"
+Requires-Dist: mkdocs-material>=9.5; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Dynamic: license-file
+
+# fastweb3-console
+
+Interactive console and script runner for working with EVM blockchains.
+
+**NOTE**: This library is still in early alpha development. Prior to a `v1.0.0` (which may never come), expect breaking changes and no backward compatibility between versions.
+
+## Installation
+
+You can install the latest release via `pip`:
+
+```bash
+pip install fastweb3-console
+```
+
+Or clone the repository for the most up-to-date version:
+
+```bash
+git clone https://github.com/iamdefinitelyahuman/fastweb3-console.git
+cd fastweb3-console
+pip install -e .
+```
+
+## Usage
+
+Launch the console with:
+
+```bash
+fw3
+```
+
+The console starts as a normal Python REPL with the main [`fastweb3-objects`](https://github.com/iamdefinitelyahuman/fastweb3-objects) entry points already available:
+
+```py
+>>> accounts
+<Accounts ...>
+>>> Chain
+<class 'fw3_objects.chain.Chain'>
+>>> Contract
+<class 'fw3_objects.contract.Contract'>
+>>> Transaction
+<class 'fw3_objects.transaction.Transaction'>
+```
+
+Users familiar with the Brownie console should feel right at home.
+
+## Development
+
+First, install the dev dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run the test suite with:
+
+```bash
+pytest
+```
+
+Run linting with:
+
+```bash
+ruff check .
+```
+
+## License
+
+This project is licensed under the MIT license.

fastweb3_console-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+fastweb3_console-0.1.0.dist-info/licenses/LICENSE,sha256=S1B8PiiVvVAWPT42fJoAJdHprCKcCwU6RB8WlzAxlZE,1076
+fw3_console/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fw3_console/autosuggest.py,sha256=8iTw2XffOM2ceam0pLigGjwOBKB73aWXA9vpqjkpZmU,2032
+fw3_console/cli.py,sha256=84f98r11PiZ1UHU-eWfTCEWPHJkFfzZapvlkPfPOjj8,3373
+fw3_console/completion.py,sha256=P32kkV29oOoF3te6OX7g217DfQZha10aLjgXQnQvtxs,5746
+fw3_console/contracts.py,sha256=u24cLc6D1xKlbysdRA4Uigd75uwR1pt32eSCpyFr8Is,5094
+fw3_console/display.py,sha256=aHWBx19IK8d7_eR7rQVvUAvImsG36pWDhc50kv1aKis,2137
+fw3_console/history.py,sha256=sDIj50AU8atWEzL4fRHLYShqRfwXU5e_Kt0XPuv7f3U,3702
+fw3_console/parser.py,sha256=D8ajs_ApXjszzZjFMeLUDeebPamNQCpC7PHV6bSY42I,3180
+fw3_console/proxy_warnings.py,sha256=581OrezKGNI5guc31Zp5PKrYeuna6Hm5L1QTIo_85Nk,2235
+fw3_console/resolver.py,sha256=78SMEm-zI4FiUf6kbxJopDO2Y1JXyjswGkadIxPxhNU,5076
+fastweb3_console-0.1.0.dist-info/METADATA,sha256=onYjBknSBhjwyjQBjZaPcL4o9T2tFCQAaTaKLGKRyiU,2408
+fastweb3_console-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fastweb3_console-0.1.0.dist-info/entry_points.txt,sha256=7NQOTjgsiKceMAFOWqpGffoeONUnbhfyhpHgvwFS4Vs,45
+fastweb3_console-0.1.0.dist-info/top_level.txt,sha256=IDo0XskO5Vb7loaz5dSzUEr7PV9_wUvFmLQjHDgCSUE,12
+fastweb3_console-0.1.0.dist-info/RECORD,,

fastweb3_console-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fastweb3_console-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fw3 = fw3_console.cli:main

fastweb3_console-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iamdefinitelyahuman
+
+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.

fastweb3_console-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fw3_console

fw3_console/autosuggest.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+"""Ghost-text call suggestions for the interactive console."""
+
+from prompt_toolkit.auto_suggest import AutoSuggest, Suggestion
+
+from .contracts import call_suggestion_parts
+from .parser import active_call_context
+
+
+def make_call_suggestion(method, arg_index, current_arg, bound_receiver=False, invocation=None):
+    """Build the visible ghost text for the active call, if it is unambiguous."""
+    parts = call_suggestion_parts(method, bound_receiver, invocation)
+    if parts is None:
+        return None
+
+    if parts and isinstance(parts[0], list):
+        matches = [item for item in parts if len(item) > arg_index or (not item and arg_index == 0)]
+        if len(matches) != 1:
+            return None
+        parts = matches[0]
+
+    if arg_index >= len(parts):
+        return Suggestion(")")
+
+    current_part = parts[arg_index]
+    next_parts = parts[arg_index + 1 :]
+    typed = current_arg.lstrip()
+
+    if typed:
+        if len(typed) < len(current_part):
+            suggestion = current_part[len(typed) :]
+            if next_parts:
+                suggestion += ", " + ", ".join(next_parts)
+        else:
+            suggestion = ", ".join(next_parts)
+            if suggestion:
+                suggestion = ", " + suggestion
+        return Suggestion(suggestion + ")")
+
+    remaining = ", ".join(parts[arg_index:])
+    prefix = " " if current_arg else ""
+    return Suggestion(prefix + remaining + ")")
+
+
+class ConsoleAutoSuggest(AutoSuggest):
+    """Prompt-toolkit autosuggest adapter backed by call-context parsing."""
+
+    def __init__(self, namespace):
+        self.namespace = namespace
+
+    def get_suggestion(self, buffer, document):
+        context = active_call_context(document.text_before_cursor, self.namespace)
+        if context is None:
+            return None
+
+        return make_call_suggestion(
+            context.obj,
+            context.arg_index,
+            context.current_arg,
+            context.bound_receiver,
+            context.invocation,
+        )

fw3_console/cli.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+"""Interactive console entry point and prompt-toolkit wiring."""
+
+import sys
+from code import InteractiveConsole
+from importlib.metadata import version
+from pathlib import Path
+
+from fw3_objects import Accounts, Chain, Contract, Transaction
+from platformdirs import user_cache_dir
+from prompt_toolkit import PromptSession
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.lexers import PygmentsLexer
+from prompt_toolkit.styles import style_from_pygments_cls
+from pygments.lexers import PythonLexer
+
+from .autosuggest import ConsoleAutoSuggest
+from .completion import ConsoleCompleter
+from .display import PYGMENTS_STYLE, displayhook, write_highlighted
+from .history import SafeFileHistory
+from .proxy_warnings import warn_proxy_identity_comparisons
+
+_CONSOLE_STYLE = style_from_pygments_cls(PYGMENTS_STYLE)
+
+
+def _console_key_bindings():
+    """Return console key bindings that override awkward prompt defaults."""
+    key_bindings = KeyBindings()
+
+    @key_bindings.add("right")
+    def _(event):
+        event.current_buffer.cursor_right(count=event.arg)
+
+    return key_bindings
+
+
+class Console(InteractiveConsole):
+    """Interactive fastweb3 console.
+
+    This class owns the small amount of glue that makes the shell feel different
+    from a plain Python REPL: prompt-toolkit completions/autosuggest, sanitized
+    history, highlighted output, and warnings for proxy identity comparisons.
+    """
+
+    def __init__(self):
+        history_path = Path(user_cache_dir("fw3-console")) / "history"
+        history_path.parent.mkdir(parents=True, exist_ok=True)
+
+        namespace = {
+            "accounts": Accounts(unlock=False),
+            "Contract": Contract,
+            "Chain": Chain,
+            "Transaction": Transaction,
+        }
+
+        self.prompt_session = PromptSession(
+            completer=ConsoleCompleter(namespace),
+            lexer=PygmentsLexer(PythonLexer),
+            auto_suggest=ConsoleAutoSuggest(namespace),
+            key_bindings=_console_key_bindings(),
+            history=SafeFileHistory(history_path, namespace),
+            style=_CONSOLE_STYLE,
+        )
+
+        super().__init__(namespace)
+
+    def raw_input(self, prompt=""):
+        return self.prompt_session.prompt(prompt)
+
+    def runsource(self, source, filename="<input>", symbol="single"):
+        """Compile and run one input block with pre-execution console checks."""
+        try:
+            code = self.compile(source, filename, symbol)
+        except (OverflowError, SyntaxError, ValueError):
+            self.showsyntaxerror(filename)
+            return False
+
+        if code is None:
+            return True
+
+        warn_proxy_identity_comparisons(source, self.locals)
+        self.runcode(code)
+        return False
+
+    def runcode(self, code):
+        """Run code with the console displayhook installed temporarily."""
+        old_displayhook = sys.displayhook
+        sys.displayhook = displayhook
+        try:
+            super().runcode(code)
+        finally:
+            sys.displayhook = old_displayhook
+
+    def write(self, data):
+        write_highlighted(data)
+
+
+def main():
+    """Start the interactive console."""
+    ver = version("fastweb3-console")
+    print(f"fastweb3-console v{ver}: interactive console for EVM blockchains")
+    console = Console()
+    console.interact(banner="")

fw3_console/completion.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+"""Prompt-toolkit completions for the interactive console.
+
+Most of the behavior here is intentionally console-specific rather than general
+Python completion.  It completes globals on blank input and assignment RHSes,
+merges ABI method names into contract attribute completion, and installs small
+``__getitem_completions__`` hooks onto fastweb3 objects so ``obj[`` can suggest
+aliases, addresses, event names, or event argument names.
+"""
+
+import re
+
+from fw3_objects import Accounts
+
+try:
+    from fw3_objects.events import Event, EventArgs, EventGroup, EventList
+except ImportError:  # pragma: no cover - optional for tests without fw3-objects events
+    Event = EventArgs = EventGroup = EventList = None
+from prompt_toolkit.completion import Completer, Completion
+
+from .resolver import CannotComplete, contract_abi_names, normalize_for_completion, resolve_path
+
+_IDENTIFIER = r"[A-Za-z_][A-Za-z0-9_]*"
+_OPTIONAL_IDENTIFIER = rf"(?:{_IDENTIFIER})?"
+_PATH = rf"{_IDENTIFIER}(?:\.{_IDENTIFIER})*"
+
+_NAME_RE = re.compile(rf"(?P<prefix>{_IDENTIFIER})$")
+_ATTR_RE = re.compile(rf"(?P<path>{_PATH})\.(?P<prefix>{_OPTIONAL_IDENTIFIER})$")
+_GETITEM_RE = re.compile(rf"(?P<path>{_PATH})\[\s*(?P<prefix>(?:[\'\"][^\'\"]*)?)$")
+
+
+def _accounts_getitem_completions(self):
+    return [
+        *(repr(alias) for alias in self.aliases()),
+        *(repr(str(account)) for account in self.accounts()),
+    ]
+
+
+def _event_list_getitem_completions(self):
+    return [repr(name) for name in self.keys()]
+
+
+def _event_args_getitem_completions(self):
+    return [repr(name) for name in self.keys()]
+
+
+def _event_getitem_completions(self):
+    return self.args.__getitem_completions__()
+
+
+def _event_group_getitem_completions(self):
+    if len(self) != 1:
+        return []
+    return self[0].__getitem_completions__()
+
+
+def _install_getitem_completions():
+    """Attach console-only getitem completion hooks to supported objects.
+
+    The underlying objects intentionally do not depend on prompt-toolkit.  This
+    monkey-patch keeps completion behavior local to the console while giving the
+    completer a uniform ``__getitem_completions__`` protocol to ask for possible
+    keys.  Event classes are optional so tests and older fw3-objects versions can
+    still import the console package.
+    """
+    Accounts.__getitem_completions__ = _accounts_getitem_completions
+    if EventList is not None:
+        EventList.__getitem_completions__ = _event_list_getitem_completions
+    if EventArgs is not None:
+        EventArgs.__getitem_completions__ = _event_args_getitem_completions
+    if Event is not None:
+        Event.__getitem_completions__ = _event_getitem_completions
+    if EventGroup is not None:
+        EventGroup.__getitem_completions__ = _event_group_getitem_completions
+
+
+class ConsoleCompleter(Completer):
+    """Complete console globals, attributes, ABI names, and object getitem keys."""
+
+    def __init__(self, namespace):
+        self.namespace = namespace
+        _install_getitem_completions()
+
+    def get_completions(self, document, complete_event):
+        text = document.text_before_cursor
+        if not text.strip() or re.search(r"=\s*$", text):
+            yield from self._make_completions(set(self.namespace), "")
+            return
+
+        getitem_match = _GETITEM_RE.search(text)
+
+        if getitem_match is not None:
+            path = getitem_match.group("path").split(".")
+            prefix = getitem_match.group("prefix")
+            try:
+                obj = self._resolve_path(path)
+            except CannotComplete:
+                return
+            yield from self._getitem_completions(obj, prefix)
+            return
+
+        attr_match = _ATTR_RE.search(text)
+
+        if attr_match is not None:
+            path = attr_match.group("path").split(".")
+            prefix = attr_match.group("prefix")
+            try:
+                obj = self._resolve_path(path)
+            except CannotComplete:
+                return
+            yield from self._attribute_completions(obj, prefix)
+            return
+
+        name_match = _NAME_RE.search(text)
+        if name_match is None:
+            return
+
+        prefix = name_match.group("prefix")
+        yield from self._name_completions(prefix)
+
+    def _resolve_path(self, path):
+        return resolve_path(self.namespace, path)
+
+    def _name_completions(self, prefix):
+        names = set(self.namespace)
+        yield from self._make_completions(names, prefix)
+
+    def _attribute_completions(self, obj, prefix):
+        """Return normal ``dir`` names plus ABI-defined contract method names."""
+        obj = normalize_for_completion(obj)
+        try:
+            names = set(dir(obj))
+        except Exception:
+            names = set()
+
+        names |= contract_abi_names(obj)
+        yield from self._make_completions(names, prefix)
+
+    def _getitem_completions(self, obj, prefix):
+        """Yield bracket-key suggestions without letting hook failures leak out.
+
+        Completion runs on every keystroke.  A broken hook should mean "no
+        completions", not a crashed prompt.
+        """
+        obj = normalize_for_completion(obj)
+        hook = getattr(obj, "__getitem_completions__", None)
+        if hook is None:
+            return
+
+        try:
+            names = hook()
+        except Exception:
+            return
+
+        yield from self._make_completions(names, prefix, sort=False)
+
+    def _make_completions(self, names, prefix, sort=True):
+        if sort:
+            names = sorted(names)
+        for name in names:
+            if name.startswith(prefix) and (prefix.startswith("_") or not name.startswith("_")):
+                yield Completion(name, start_position=-len(prefix) if prefix else 0)

fw3_console/contracts.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+"""Build autosuggest text for contract methods and regular Python callables.
+
+Contract wrappers expose ABI metadata instead of ordinary Python signatures, so
+this module translates ABI inputs into the ghost text shown by prompt-toolkit.
+For normal callables it falls back to ``inspect.signature`` and finally the code
+object so builtins, Python functions, and dynamically generated methods all get a
+best-effort suggestion without calling the object.
+"""
+
+import inspect
+
+
+def instance_attr(obj, name):
+    """Read an instance attribute before falling back to normal getattr."""
+    try:
+        instance_attrs = object.__getattribute__(obj, "__dict__")
+    except AttributeError:
+        instance_attrs = None
+
+    if instance_attrs is not None and name in instance_attrs:
+        return instance_attrs[name]
+
+    return getattr(obj, name, None)
+
+
+def format_abi_input(abi_input):
+    typ = abi_input.get("type", "")
+    name = abi_input.get("name")
+    if name:
+        return f"{name}: {typ}"
+    return typ
+
+
+def abi_suggestion_parts(method_abi, method, invocation=None):
+    """Return ghost-text parts for one ABI method variant.
+
+    Transaction-style calls get console-only convenience kwargs appended:
+    ``sender=Account`` for transaction submission/gas estimation and ``value=Wei``
+    only when the target ABI is payable.
+    """
+    inputs = method_abi.get("inputs", [])
+    if not isinstance(inputs, list):
+        inputs = []
+
+    parts = [format_abi_input(item) for item in inputs if isinstance(item, dict)]
+
+    if invocation in {"estimate_gas", "transact"} or (
+        invocation is None and type(method).__name__ == "ContractTx"
+    ):
+        parts.append("sender=Account")
+
+    is_transaction = invocation == "transact" or (
+        invocation is None and type(method).__name__ == "ContractTx"
+    )
+    is_payable = method_abi.get("stateMutability") == "payable" or method_abi.get("payable") is True
+    if is_transaction and is_payable:
+        parts.append("value=Wei")
+
+    return parts
+
+
+def call_suggestion_parts(method, bound_receiver=False, invocation=None):
+    """Return suggestion parts for a callable-like object.
+
+    The return value is ``None`` for unsupported objects, a flat list for a single
+    signature, or a list of lists for overloaded ABI methods.  The autosuggest
+    layer uses the current argument index to disambiguate overloads.
+    """
+    method_abis = instance_attr(method, "method_abis")
+    if isinstance(method_abis, dict):
+        method_abis = list(method_abis.values())
+
+    if isinstance(method_abis, (list, tuple)):
+        return [
+            abi_suggestion_parts(abi, method, invocation)
+            for abi in method_abis
+            if isinstance(abi, dict)
+        ]
+
+    method_abi = instance_attr(method, "method_abi")
+    if isinstance(method_abi, dict):
+        return abi_suggestion_parts(method_abi, method, invocation)
+
+    return callable_suggestion_parts(method, bound_receiver)
+
+
+def format_default(default):
+    if default is inspect.Signature.empty:
+        return None
+    return repr(default)
+
+
+def format_signature_parameter(parameter):
+    text = parameter.name
+
+    if parameter.kind is inspect.Parameter.VAR_POSITIONAL:
+        text = f"*{text}"
+    elif parameter.kind is inspect.Parameter.VAR_KEYWORD:
+        text = f"**{text}"
+
+    default = format_default(parameter.default)
+    if default is not None:
+        text = f"{text}={default}"
+
+    return text
+
+
+def signature_suggestion_parts(method, bound_receiver):
+    """Use ``inspect.signature`` without showing annotations or return types."""
+    try:
+        signature = inspect.signature(method)
+    except (TypeError, ValueError):
+        return None
+
+    parameters = list(signature.parameters.values())
+    if bound_receiver and parameters and parameters[0].name in {"self", "cls"}:
+        parameters = parameters[1:]
+
+    return [format_signature_parameter(parameter) for parameter in parameters]
+
+
+def code_suggestion_parts(method, bound_receiver):
+    """Fallback for callable objects where ``inspect.signature`` is unavailable."""
+    code = getattr(method, "__code__", None)
+    if code is None:
+        return None
+
+    arg_count = code.co_argcount + getattr(code, "co_kwonlyargcount", 0)
+    names = list(code.co_varnames[:arg_count])
+    if bound_receiver and names and names[0] in {"self", "cls"}:
+        names = names[1:]
+
+    defaults = getattr(method, "__defaults__", None) or ()
+    default_start = len(names) - len(defaults)
+    parts = []
+    for index, name in enumerate(names):
+        if index >= default_start:
+            parts.append(f"{name}={defaults[index - default_start]!r}")
+        else:
+            parts.append(name)
+    return parts
+
+
+def callable_suggestion_parts(method, bound_receiver):
+    """Return best-effort ghost-text parts for a non-ABI callable."""
+    if not callable(method):
+        return None
+
+    parts = signature_suggestion_parts(method, bound_receiver)
+    if parts is not None:
+        return parts
+
+    return code_suggestion_parts(method, bound_receiver)

fw3_console/display.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+"""Console display hooks and syntax highlighting helpers."""
+
+import ast
+import builtins
+import sys
+
+from lazy_object_proxy import Proxy
+from prompt_toolkit.formatted_text import ANSI
+from prompt_toolkit.shortcuts import print_formatted_text
+from pygments import highlight
+from pygments.formatters import Terminal256Formatter
+from pygments.lexers import PythonLexer
+from pygments.lexers.python import PythonTracebackLexer
+from pygments.styles import get_style_by_name
+
+PYGMENTS_STYLE = get_style_by_name("native")
+OUTPUT_FORMATTER = Terminal256Formatter(style=PYGMENTS_STYLE)
+PYTHON_LEXER = PythonLexer()
+TRACEBACK_LEXER = PythonTracebackLexer()
+
+
+def highlight_output(text, lexer=PYTHON_LEXER):
+    return highlight(text, lexer, OUTPUT_FORMATTER).rstrip("\n")
+
+
+def is_python_literal(text):
+    try:
+        ast.literal_eval(text)
+    except (SyntaxError, ValueError):
+        return False
+    return True
+
+
+def displayhook(value):
+    """Render expression results like Python, with console-specific polish.
+
+    Direct ``Proxy`` results are unwrapped so dumping a proxy at the prompt shows
+    the underlying object.  ``builtins._`` is cleared before ``repr`` to match the
+    standard displayhook's recursion guard, then restored to the displayed value.
+    Literal-looking reprs are syntax-highlighted; repr failures fall back to
+    Python's default displayhook so the user still sees the real exception path.
+    """
+    if value is None:
+        return
+
+    if type(value) is Proxy:
+        value = value.__wrapped__
+
+    builtins._ = None
+    try:
+        output = repr(value)
+    except Exception:
+        sys.__displayhook__(value)
+        return
+
+    if is_python_literal(output):
+        print_formatted_text(ANSI(highlight_output(output)))
+    else:
+        print(output)
+
+    builtins._ = value
+
+
+def write_highlighted(data):
+    """Write console stderr using Python or traceback highlighting."""
+    lexer = TRACEBACK_LEXER if data.startswith("Traceback ") else PYTHON_LEXER
+    sys.stderr.write(highlight_output(data, lexer))
+    if data.endswith("\n"):
+        sys.stderr.write("\n")

fw3_console/history.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+"""Prompt history that strips sensitive call arguments before persistence.
+
+Console history is useful, but private keys and similar secrets must not be
+written to disk.  Callables marked with ``__sensitive__`` have their positional
+and keyword arguments removed from the stored history line while preserving the
+fact that the call happened.
+"""
+
+import ast
+from pathlib import Path
+from typing import Any
+
+from fw3_objects import Accounts
+from lazy_object_proxy import Proxy
+from prompt_toolkit.history import FileHistory
+
+
+class SafeFileHistory(FileHistory):
+    """File-backed prompt history with AST-based sensitive argument stripping."""
+
+    def __init__(self, filename: str | Path, namespace: dict[str, Any]):
+        self.namespace = namespace
+        _mark_sensitive_calls()
+        super().__init__(filename)
+
+    def append_string(self, string: str) -> None:
+        super().append_string(_sanitize_history_string(string, self.namespace))
+
+
+def _mark_sensitive_calls() -> None:
+    """Mark known secret-accepting APIs for history sanitization.
+
+    The marker lives on the external fw3 object method so the AST sanitizer can
+    resolve calls through normal console names instead of hard-coding source
+    strings such as ``accounts.add_private_key(...)``.
+    """
+    try:
+        Accounts.add_private_key.__sensitive__ = True
+    except AttributeError:
+        pass
+
+
+def _sanitize_history_string(source: str, namespace: dict[str, Any]) -> str:
+    """Strip arguments from sensitive calls in one history entry.
+
+    If the source is syntactically invalid we keep it unchanged.  A broken line
+    cannot be represented as a trustworthy AST, and guessing with regexes would
+    be more likely to corrupt unrelated history than safely remove a secret.
+    """
+    try:
+        tree = ast.parse(source.lstrip(), mode="exec")
+    except SyntaxError:
+        return source
+
+    stripper = _SensitiveCallStripper(namespace)
+    sanitized = stripper.visit(tree)
+
+    if not stripper.changed:
+        return source
+
+    ast.fix_missing_locations(sanitized)
+    return ast.unparse(sanitized)
+
+
+class _SensitiveCallStripper(ast.NodeTransformer):
+    """Remove arguments from calls whose resolved object is sensitive."""
+
+    def __init__(self, namespace: dict[str, Any]):
+        self.namespace = namespace
+        self.changed = False
+
+    def visit_Call(self, node: ast.Call) -> ast.Call:
+        self.generic_visit(node)
+
+        target = _resolve_ast_object(node.func, self.namespace)
+        if _is_sensitive(target):
+            node.args = []
+            node.keywords = []
+            self.changed = True
+
+        return node
+
+
+def _resolve_ast_object(node: ast.AST, namespace: dict[str, Any]) -> Any | None:
+    """Resolve simple ``name.attr`` AST paths against the console namespace."""
+    if isinstance(node, ast.Name):
+        return namespace.get(node.id)
+
+    if isinstance(node, ast.Attribute):
+        parent = _resolve_ast_object(node.value, namespace)
+        if parent is None:
+            return None
+        return getattr(parent, node.attr, None)
+
+    return None
+
+
+def _is_sensitive(value: Any) -> bool:
+    """Return whether a resolved callable is marked as sensitive.
+
+    Proxies are intentionally treated as not sensitive here.  Checking attributes
+    on an unresolved proxy may resolve it, and history sanitization must not
+    trigger lazy object side effects while the prompt is saving text.
+    """
+    if type(value) is Proxy:
+        return False
+
+    if getattr(value, "__sensitive__", False):
+        return True
+
+    func = getattr(value, "__func__", None)
+    return func is not None and getattr(func, "__sensitive__", False)

fw3_console/parser.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+"""Lightweight parser helpers for call autosuggest.
+
+This is intentionally not a full Python parser.  Autosuggest only needs the call
+whose opening parenthesis is still active at the cursor and the current argument
+index.  The scanner is string-aware and bracket-aware so commas inside strings,
+lists, dicts, tuples, or nested calls do not advance the outer call argument.
+"""
+
+from dataclasses import dataclass
+import re
+from typing import Any
+
+from .resolver import CannotComplete, resolve_call_path
+
+_IDENTIFIER = r"[A-Za-z_][A-Za-z0-9_]*"
+_CALL_RE = re.compile(rf"(?P<path>{_IDENTIFIER}(?:\.{_IDENTIFIER})*)$")
+
+
+@dataclass(frozen=True)
+class ActiveCall:
+    """Resolved call context used to build one autosuggest response."""
+
+    obj: Any
+    arg_index: int
+    current_arg: str
+    bound_receiver: bool = False
+    invocation: str | None = None
+
+
+_PAIRS = {("(", ")"), ("[", "]"), ("{", "}")}
+_OPENERS = "([{"
+_CLOSERS = ")] }".replace(" ", "")
+
+
+def _iter_code_chars(text):
+    """Yield non-string characters with their original offsets."""
+    quote = None
+    escaped = False
+
+    for index, char in enumerate(text):
+        if quote is not None:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == quote:
+                quote = None
+            continue
+
+        if char in {'"', "'"}:
+            quote = char
+            continue
+
+        yield index, char
+
+
+def find_active_open_paren(text):
+    """Return the still-open call parenthesis nearest the cursor, if any."""
+    stack = []
+
+    for index, char in _iter_code_chars(text):
+        if char in _OPENERS:
+            stack.append((char, index))
+        elif char in _CLOSERS and stack:
+            opener = stack[-1][0]
+            if (opener, char) in _PAIRS:
+                stack.pop()
+
+    for char, index in reversed(stack):
+        if char == "(":
+            return index
+    return None
+
+
+def count_call_args(text):
+    """Return the outer call arg index and current arg text after ``(``."""
+    arg_index = 0
+    arg_start = 0
+    stack = []
+
+    for index, char in _iter_code_chars(text):
+        if char in _OPENERS:
+            stack.append(char)
+        elif char in _CLOSERS and stack:
+            opener = stack[-1]
+            if (opener, char) in _PAIRS:
+                stack.pop()
+        elif char == "," and not stack:
+            arg_index += 1
+            arg_start = index + 1
+
+    return arg_index, text[arg_start:]
+
+
+def active_call_context(text, namespace):
+    """Resolve the active textual call into an object and argument position."""
+    open_paren = find_active_open_paren(text)
+    if open_paren is None:
+        return None
+
+    match = _CALL_RE.search(text[:open_paren].rstrip())
+    if match is None:
+        return None
+
+    path = match.group("path").split(".")
+    try:
+        obj, bound_receiver, invocation = resolve_call_path(namespace, path)
+    except CannotComplete:
+        return None
+
+    arg_index, current_arg = count_call_args(text[open_paren + 1 :])
+    return ActiveCall(obj, arg_index, current_arg, bound_receiver, invocation)

fw3_console/proxy_warnings.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+"""Warnings for identity comparisons involving lazy proxies.
+
+``is`` and ``is not`` never dispatch to the wrapped object; they compare the
+``Proxy`` instance itself.  The console checks compiled input before execution so
+users get a warning for this specific footgun without changing Python semantics.
+"""
+
+import ast
+import sys
+
+from lazy_object_proxy import Proxy
+
+from .resolver import CannotComplete, resolve_name
+
+
+def proxy_name(namespace, node):
+    """Return the source name if an AST node resolves to a Proxy."""
+    if not isinstance(node, ast.Name):
+        return None
+
+    try:
+        obj = resolve_name(namespace, node.id)
+    except CannotComplete:
+        return None
+
+    if type(obj) is Proxy:
+        return node.id
+    return None
+
+
+def proxy_identity_warnings(source, namespace):
+    """Build warnings for ``is`` / ``is not`` comparisons against proxies."""
+    try:
+        tree = ast.parse(source, mode="exec")
+    except SyntaxError:
+        return []
+
+    warnings = []
+    seen = set()
+
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Compare):
+            continue
+
+        operands = [node.left, *node.comparators]
+        for op, left, right in zip(node.ops, operands, operands[1:]):
+            if not isinstance(op, (ast.Is, ast.IsNot)):
+                continue
+
+            proxy_names = [
+                name
+                for name in (proxy_name(namespace, left), proxy_name(namespace, right))
+                if name
+            ]
+            if not proxy_names:
+                continue
+
+            names = ", ".join(f"`{name}`" for name in proxy_names)
+            key = (node.lineno, names)
+            if key in seen:
+                continue
+            seen.add(key)
+            warnings.append(
+                f"Warning: {names} is a Proxy. `is` / `is not` compares the proxy itself, "
+                "not the resolved object. Use `==` for value comparison."
+            )
+
+    return warnings
+
+
+def warn_proxy_identity_comparisons(source, namespace):
+    """Write proxy identity warnings to stderr before code execution."""
+    for warning in proxy_identity_warnings(source, namespace):
+        sys.stderr.write(warning + "\n")

fw3_console/resolver.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+"""Side-effect-conscious object resolution for completion and autosuggest.
+
+The console needs to inspect objects while the user is typing.  Some fw3 objects
+are lazy proxies or dynamic contract wrappers, so normal ``getattr`` can trigger
+resolution, network work, or descriptor execution.  Helpers in this module prefer
+static inspection and explicitly opt into dynamic lookup only for known contract
+ABI methods.
+"""
+
+import builtins
+import inspect
+
+from lazy_object_proxy import Proxy
+
+_CONTRACT_METHOD_INVOCATIONS = {"call", "estimate_gas", "transact"}
+
+
+class CannotComplete(Exception):
+    """Raised when resolving for completion would be unsafe or impossible."""
+
+
+
+def normalize_for_completion(obj):
+    """Return a safe object for inspection without forcing unresolved proxies.
+
+    Resolved ``Proxy`` objects are unwrapped so completion sees the real object.
+    Unresolved proxies abort completion because resolving them may perform work
+    the user did not ask for just by pressing a key.
+    """
+    if type(obj) is not Proxy:
+        return obj
+
+    if not object.__getattribute__(obj, "__resolved__"):
+        raise CannotComplete
+    return object.__getattribute__(obj, "__wrapped__")
+
+
+def instance_dict(obj):
+    try:
+        return object.__getattribute__(obj, "__dict__")
+    except AttributeError:
+        return {}
+
+
+def safe_getattr(obj, name):
+    """Read an attribute for completion while avoiding descriptor execution.
+
+    Instance attributes are returned directly because fastweb3 contract objects
+    often materialize ABI methods there.  Otherwise ``inspect.getattr_static`` is
+    used so properties and descriptors are not invoked while typing.
+    """
+    obj = normalize_for_completion(obj)
+
+    try:
+        instance_attrs = object.__getattribute__(obj, "__dict__")
+    except AttributeError:
+        instance_attrs = None
+
+    if instance_attrs is not None and name in instance_attrs:
+        return instance_attrs[name]
+
+    try:
+        return inspect.getattr_static(obj, name)
+    except AttributeError as exc:
+        raise CannotComplete from exc
+
+
+def contract_abi_names(obj):
+    """Return function names advertised by a contract-like object's ABI."""
+    instance_attrs = instance_dict(obj)
+
+    abi = instance_attrs.get("abi")
+    if not isinstance(abi, list):
+        return set()
+
+    return {
+        item["name"]
+        for item in abi
+        if isinstance(item, dict) and item.get("type", "function") == "function" and "name" in item
+    }
+
+
+def is_contract_method(obj):
+    """Detect fastweb3 contract method wrappers by their ABI attributes."""
+    instance_attrs = instance_dict(obj)
+    method_abi = instance_attrs.get("method_abi")
+    method_abis = instance_attrs.get("method_abis")
+
+    if isinstance(method_abi, dict):
+        return True
+    if isinstance(method_abis, dict):
+        return True
+    return isinstance(method_abis, (list, tuple))
+
+
+def resolve_name(namespace, name):
+    """Resolve a name from console locals, then Python builtins."""
+    try:
+        return namespace[name]
+    except KeyError:
+        try:
+            return getattr(builtins, name)
+        except AttributeError as exc:
+            raise CannotComplete from exc
+
+
+def resolve_path(namespace, path):
+    """Resolve ``foo.bar.baz`` for completion.
+
+    Normal attributes are resolved statically.  Missing attributes are allowed
+    only when the current object advertises an ABI function with that name, which
+    lets dynamic contract method access participate in completion.
+    """
+    obj = resolve_name(namespace, path[0])
+
+    for name in path[1:]:
+        try:
+            obj = safe_getattr(obj, name)
+        except CannotComplete:
+            if name not in contract_abi_names(obj):
+                raise
+            obj = getattr(obj, name)
+    return normalize_for_completion(obj)
+
+
+def resolve_call_path(namespace, path):
+    """Resolve the callable currently being typed and its console context.
+
+    In addition to ``token.transfer(``, contract calls may be typed as
+    ``token.transfer.call(``, ``.estimate_gas(``, or ``.transact(``.  The final
+    invocation suffix is reported separately so autosuggest can choose the right
+    ABI extras, while the resolved object remains the underlying contract method.
+    """
+    obj = resolve_name(namespace, path[0])
+    bound_receiver = False
+    invocation = None
+
+    for index, name in enumerate(path[1:], start=1):
+        receiver = normalize_for_completion(obj)
+        is_last = index == len(path) - 1
+
+        if is_last and name in _CONTRACT_METHOD_INVOCATIONS and is_contract_method(receiver):
+            invocation = name
+            obj = receiver
+            break
+
+        if is_last and not inspect.isclass(receiver):
+            bound_receiver = True
+
+        try:
+            obj = safe_getattr(obj, name)
+        except CannotComplete:
+            if name not in contract_abi_names(obj):
+                raise
+            obj = getattr(obj, name)
+    return normalize_for_completion(obj), bound_receiver, invocation