robotcode-repl 2.9.0.dev51__py3-none-any.whl → 2.9.0.dev74__py3-none-any.whl

robotcode/repl/base_interpreter.py

@@ -597,13 +597,19 @@ class BaseInterpreter(abc.ABC):
                     # Checked after marking the statement: a SIGTERM in between can't be missed.
                     if kw is None or self._termination_requested:
                         break
-                    self.set_last_result(self.run_keyword(kw))
+                    result = self.run_keyword(kw)
+                    self.set_last_result(result)
+                    self.show_result(kw, result)
                 finally:
                     self._running_statement = False
 
     def set_last_result(self, result: Any) -> None:
         self.last_result = result
 
+    def show_result(self, statement: Keyword, result: Any) -> None:
+        """Show the result of a statement of the input after it has run. Each interpreter knows how;
+        the REPL server returns results through its protocol."""
+
     @abc.abstractmethod
     def log_message(
         self, message: str, level: str, html: Union[str, bool] = False, timestamp: Union[datetime, str, None] = None

robotcode/repl/cli.py

@@ -1,10 +1,12 @@
+import contextlib
 import os
 import sys
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple
+from typing import ContextManager, Dict, List, Optional, Tuple
 
 import click
 
+from robotcode.core.utils.cli import show_hidden_arguments
 from robotcode.plugin import Application, pass_application
 from robotcode.plugin._agent_detection import is_running_in_ai_agent
 from robotcode.plugin.click_helper.aliases import AliasedCommand
@@ -15,6 +17,7 @@ from robotcode.runner.cli.robot import ROBOT_OPTIONS, ROBOT_VERSION_OPTIONS, loa
 from .__version__ import __version__
 from ._backends import BACKEND_CHOICES
 from ._debug import DebugController, DebugTerminated
+from ._session import SessionError, SessionInterpreter, SessionKind, SessionServer, project_folder
 from .console_interpreter import _LINE_BREAK_RE, ConsoleInterpreter
 from .prompt_toolkit_interpreter import PromptToolkitConsoleInterpreter
 from .run import ReplResult, run_repl
@@ -28,6 +31,7 @@ def _pick_interpreter(
     inspect: bool,
     no_history: bool,
     backend: str,
+    show_prompt: bool,
 ) -> ConsoleInterpreter:
     """Construct the interpreter that matches ``backend``.
 
@@ -43,6 +47,7 @@ def _pick_interpreter(
             show_keywords=show_keywords,
             inspect=inspect,
             no_history=no_history,
+            show_prompt=show_prompt,
         )
     if backend not in ("auto", "prompt-toolkit"):
         raise ValueError(f"Unknown backend: {backend!r}. Choose from {BACKEND_CHOICES}.")
@@ -52,6 +57,7 @@ def _pick_interpreter(
         show_keywords=show_keywords,
         inspect=inspect,
         no_history=no_history,
+        show_prompt=show_prompt,
     )
 
 
@@ -153,6 +159,20 @@ def _resolve_backend(plain: bool, backend: str) -> str:
     return backend
 
 
+def _resolve_show_prompt(show_prompt: Optional[bool]) -> bool:
+    """Whether `repl` shows its `>>> ` / `... ` prompt.
+
+    Always on an interactive terminal. Otherwise `--show-prompt` / `--no-show-prompt`
+    (or `ROBOTCODE_REPL_SHOW_PROMPT`) decides, and without either a recognised AI
+    agent gets the prompt: it marks where the output of a statement ends.
+    """
+    if _is_interactive_stdin():
+        return True
+    if show_prompt is not None:
+        return show_prompt
+    return is_running_in_ai_agent()
+
+
 def _resolve_attached(
     debugger_attached: Optional[bool],
     *,
@@ -302,6 +322,15 @@ SHELL_OPTIONS = [
         default=False,
         help="Activate inspection mode. This forces a prompt to appear after the REPL script is executed.",
     ),
+    click.option(
+        "--show-prompt/--no-show-prompt",
+        default=None,
+        envvar="ROBOTCODE_REPL_SHOW_PROMPT",
+        help="Show (`--show-prompt`) or hide (`--no-show-prompt`) the `>>>` prompt when the input is not a "
+        "terminal, such as piped input. Without either option it shows there only in the session of a "
+        "recognised AI agent, where it marks the end of each statement's output. On a terminal the prompt "
+        "always shows.",
+    ),
     click.option(
         "-d",
         "--outputdir",
@@ -365,6 +394,52 @@ SHELL_OPTIONS = [
     ),
 ]
 
+# The session that `robotcode session start` runs `repl` or `robot-debug` as.
+SESSION_OPTIONS = [
+    click.option(
+        "--serve-session",
+        metavar="ID",
+        hidden=show_hidden_arguments(),
+        help="Serve the session ID that `robotcode session start` started. This is an internal option.",
+    ),
+    click.option(
+        "--serve-output",
+        type=int,
+        metavar="FD",
+        hidden=show_hidden_arguments(),
+        help="Read the output of the session from the pipe FD, a handle on Windows, into memory. "
+        "This is an internal option.",
+    ),
+    click.option(
+        "--serve-idle-timeout",
+        type=float,
+        default=15,
+        metavar="MINUTES",
+        hidden=show_hidden_arguments(),
+        help="End the session after it has waited at its prompt for MINUTES without a request. "
+        "This is an internal option.",
+    ),
+]
+
+
+def _session_server(
+    app: Application,
+    serve_session: Optional[str],
+    serve_output: Optional[int],
+    kind: SessionKind,
+    idle_timeout: float,
+) -> Optional[SessionServer]:
+    if serve_session is None:
+        return None
+    if serve_output is None:
+        raise click.UsageError("--serve-session needs --serve-output.")
+    try:
+        # The folder `session start` ran in decides the project, also for a debug run of a suite elsewhere.
+        return SessionServer(serve_session, kind, project_folder(app), idle_timeout * 60, serve_output)
+    except SessionError as e:
+        raise click.ClickException(str(e)) from e
+
+
 # Debugger options — shared by `repl` and `robot-debug`. `--debugger-attached`
 # is the master switch (does anything pause at all?); the `--break*` flags are
 # the individual pause triggers. (`robot-debug` adds `--stop-on-entry`, which
@@ -421,6 +496,7 @@ DEBUG_OPTIONS = [
 @add_options(*REPL_BASE_OPTIONS)
 @add_options(*SHELL_OPTIONS)
 @add_options(*DEBUG_OPTIONS)
+@add_options(*SESSION_OPTIONS)
 @click.version_option(version=__version__, prog_name="RobotCode REPL")
 @pass_application
 def repl(
@@ -430,6 +506,7 @@ def repl(
     pythonpath: Tuple[str, ...],
     show_keywords: bool,
     inspect: bool,
+    show_prompt: Optional[bool],
     no_history: bool,
     backend: str,
     plain: bool,
@@ -447,6 +524,9 @@ def repl(
     break_on_all_exceptions: bool,
     break_on_failed_test: bool,
     break_on_failed_suite: bool,
+    serve_session: Optional[str],
+    serve_output: Optional[int],
+    serve_idle_timeout: float,
 ) -> None:
     """Run Robot Framework interactively (alias `shell`).
 
@@ -473,13 +553,19 @@ def repl(
 
     backend = _resolve_backend(plain, backend)
 
-    interpreter = _pick_interpreter(
-        app=app,
-        files=list(files),
-        show_keywords=show_keywords,
-        inspect=inspect,
-        no_history=no_history,
-        backend=backend,
+    server = _session_server(app, serve_session, serve_output, SessionKind.REPL, serve_idle_timeout)
+    interpreter = (
+        SessionInterpreter(server, app=app, files=list(files), show_keywords=show_keywords, inspect=inspect)
+        if server is not None
+        else _pick_interpreter(
+            app=app,
+            files=list(files),
+            show_keywords=show_keywords,
+            inspect=inspect,
+            no_history=no_history,
+            backend=backend,
+            show_prompt=_resolve_show_prompt(show_prompt),
+        )
     )
     # Only `repl` fails its session test on unhandled failures — not `robot-debug`,
     # which builds its interpreter the same way.
@@ -487,7 +573,7 @@ def repl(
     # The debugger stays wired for the whole interactive session and is torn down
     # with the interpreter when the session ends — so, unlike `robot`, there is no
     # per-run unregister here. `attached` decides whether it actually pauses.
-    _attach_debugger(
+    controller = _attach_debugger(
         interpreter,
         break_at=break_at,
         attached=attached,
@@ -496,26 +582,31 @@ def repl(
         break_on_failed_test=break_on_failed_test,
         break_on_failed_suite=break_on_failed_suite,
     )
+    if server is not None:
+        server.keep_breakpoints(controller)
+
+    # A session records the exit code of the command when the REPL exits, and stays open.
+    session: ContextManager[object] = server if server is not None else contextlib.nullcontext()
+    with session:
+        result = run_repl(
+            interpreter=interpreter,
+            app=app,
+            variable=variable,
+            variablefile=variablefile,
+            pythonpath=pythonpath,
+            outputdir=outputdir,
+            output=output,
+            report=report,
+            log=log,
+            xunit=xunit,
+            source=source,
+            files=files,
+            statusrc=statusrc,
+        )
 
-    result = run_repl(
-        interpreter=interpreter,
-        app=app,
-        variable=variable,
-        variablefile=variablefile,
-        pythonpath=pythonpath,
-        outputdir=outputdir,
-        output=output,
-        report=report,
-        log=log,
-        xunit=xunit,
-        source=source,
-        files=files,
-        statusrc=statusrc,
-    )
-
-    # Script files without `--inspect` end on their own, like piped input.
-    interactive = _is_interactive_stdin() and (not files or inspect)
-    app.exit(_session_exit_code(result, statusrc=statusrc, interactive=interactive))
+        # Script files without `--inspect` end on their own, like piped input.
+        interactive = _is_interactive_stdin() and (not files or inspect)
+        app.exit(_session_exit_code(result, statusrc=statusrc, interactive=interactive))
 
 
 @wrappable
@@ -529,6 +620,7 @@ def repl(
 @add_options(*REPL_BASE_OPTIONS)
 @add_options(*(option for option in ROBOT_OPTIONS if option not in ROBOT_VERSION_OPTIONS))
 @add_options(*DEBUG_OPTIONS)
+@add_options(*SESSION_OPTIONS)
 @click.option(
     "--stop-on-entry",
     is_flag=True,
@@ -556,6 +648,9 @@ def robot_debug(
     break_on_all_exceptions: bool,
     break_on_failed_test: bool,
     break_on_failed_suite: bool,
+    serve_session: Optional[str],
+    serve_output: Optional[int],
+    serve_idle_timeout: float,
 ) -> None:
     """Run a real Robot Framework suite with the debugger attached (alias `run-debug`).
 
@@ -572,8 +667,20 @@ def robot_debug(
 
     backend = _resolve_backend(plain, backend)
 
-    interpreter = _pick_interpreter(
-        app=app, files=[], show_keywords=False, inspect=False, no_history=no_history, backend=backend
+    server = _session_server(app, serve_session, serve_output, SessionKind.DEBUG, serve_idle_timeout)
+    # A run stops at `(rdb) `, which always shows; `robot-debug` has no option for `>>> `.
+    interpreter = (
+        SessionInterpreter(server, app=app, files=[], show_keywords=False, inspect=False)
+        if server is not None
+        else _pick_interpreter(
+            app=app,
+            files=[],
+            show_keywords=False,
+            inspect=False,
+            no_history=no_history,
+            backend=backend,
+            show_prompt=_is_interactive_stdin(),
+        )
     )
     controller = _attach_debugger(
         interpreter,
@@ -585,14 +692,18 @@ def robot_debug(
         break_on_failed_test=break_on_failed_test,
         break_on_failed_suite=break_on_failed_suite,
     )
+    if server is not None:
+        server.keep_breakpoints(controller)
 
     # `robot-debug` produces the same console output as `robotcode robot` — the run
     # is fully visible. At a stop the debug prompt is interleaved with Robot's live
     # console; `_render_stop` breaks off any in-progress status line, and the run's
     # output resumes on continue/step/detach. The console mode is left to Robot's
     # default (or the user's `--console`), not forced.
+    # A session records the exit code of the run when the run ends, and stays open.
+    session: ContextManager[object] = server if server is not None else contextlib.nullcontext()
     try:
-        with interpreter.forward_events(echo_messages=False):
+        with session, interpreter.forward_events(echo_messages=False):
             _invoke_runner(
                 ctx,
                 by_longname,

robotcode/repl/console_interpreter.py

@@ -28,7 +28,7 @@ from typing import TYPE_CHECKING, Any, Callable, Dict, Iterator, List, Optional,
 
 import click
 from robot import result, running
-from robot.errors import ExecutionFailed, ExecutionPassed
+from robot.errors import ExecutionFailed, ExecutionPassed, ExecutionStatus
 from robot.running import Keyword
 from robot.running.context import EXECUTION_CONTEXTS
 from robot.utils import normalize
@@ -334,6 +334,7 @@ class ConsoleInterpreter(BaseInterpreter):
     """
 
     # The prompt shown while paused at a debug stop (vs the `>>> ` REPL prompt).
+    PROMPT = ">>> "
     DEBUG_PROMPT = "(rdb) "
 
     # Whether `show_doc` opens a scrollable fullscreen viewer (prompt_toolkit) vs
@@ -348,6 +349,7 @@ class ConsoleInterpreter(BaseInterpreter):
         show_keywords: bool = False,
         inspect: Optional[bool] = False,
         no_history: bool = False,
+        show_prompt: bool = False,
     ) -> None:
         del no_history  # plain mode has no history file to honour the flag against
         super().__init__()
@@ -356,6 +358,8 @@ class ConsoleInterpreter(BaseInterpreter):
         self.files = files
         self.show_keywords = show_keywords
         self.inspect = inspect
+        # Whether `>>> ` and `... ` show; `robotcode repl` decides it (`_resolve_show_prompt`).
+        self.show_prompt = show_prompt
 
         self.executed_files: List[Path] = []
         # REPL inputs that parsed cleanly — `.save` exports them as a
@@ -368,6 +372,8 @@ class ConsoleInterpreter(BaseInterpreter):
         # runs, then the session ends without reading again — on a terminal, a
         # read after Ctrl-D waits for more input instead of ending.
         self._input_ended = False
+        # Set while the statements of a script file run: like the body of a test, they show no results.
+        self._input_from_file = False
         # Set while a prompt waits for input: SIGTERM then ends the wait (`_end_waiting`).
         self._reading = False
 
@@ -575,7 +581,8 @@ class ConsoleInterpreter(BaseInterpreter):
         pager ignores them.
         """
         del scroll_to, outline  # only the scrollable viewer (prompt_toolkit) uses them
-        body = f"{title}\n{'=' * len(title)}\n\n{markdown}"
+        # Documentation can end with empty lines of its markdown; the output ends with the text.
+        body = f"{title}\n{'=' * len(title)}\n\n{markdown}".rstrip()
         if self.app is not None:
             self.app.echo_via_pager(body, color=False)
 
@@ -686,6 +693,10 @@ class ConsoleInterpreter(BaseInterpreter):
                         self._dispatch_dot_command(line)
                     else:
                         self._evaluate_at_stop(line)
+                except ExecutionStatus:
+                    # Robot Framework has reported the failure of the keyword, or its `Pass Execution`, as a message
+                    # already; the REPL prompt adds nothing to it either.
+                    pass
                 except Exception as e:  # a throwing command must not eject the debug prompt
                     # `.abort` (SystemExit), Ctrl-C, and DebugTerminated are
                     # BaseException, not Exception, so they still propagate.
@@ -761,7 +772,7 @@ class ConsoleInterpreter(BaseInterpreter):
         return f"{path}:{frame.line}" if frame.line is not None else path
 
     def _render_stop(self, stop: StopEvent) -> None:
-        self._echo("")  # break off any in-progress runner console status line
+        self._end_console_line()
         parts = [f"* {stop.reason.value}", stop.frame.name]
         loc = self._location(stop.frame)
         if loc:
@@ -772,6 +783,11 @@ class ConsoleInterpreter(BaseInterpreter):
         self._echo(line)
         self._show_displays()
 
+    def _end_console_line(self) -> None:
+        """Break off the line of the run's console that a stop comes in, such as the name of a test that Robot
+        Framework has written before its status."""
+        self._echo("")
+
     def _show_displays(self) -> None:
         """Auto-evaluate the `.display` expressions in the selected frame at a stop."""
         if not self._display_exprs or self._controller is None:
@@ -837,8 +853,8 @@ class ConsoleInterpreter(BaseInterpreter):
         width = max(len(f.name) for f in stack)
         self._echo(self._frame_line(self._frame_no, self._selected_frame(), width))
 
-    def _evaluate_at_stop(self, line: str) -> None:
-        """Run `line` as Robot keyword(s) in the paused context.
+    def _evaluate_at_stop(self, line: str) -> bool:
+        """Run `line` as Robot keyword(s) in the paused context; False when it can't run.
 
         Wrapped in `suppress_pausing()` so the evaluated keyword's own events
         don't re-trigger a stop, and in `forward_events(echo_messages=True)` so
@@ -848,18 +864,18 @@ class ConsoleInterpreter(BaseInterpreter):
         # output.xml when we stop; a keyword written after it makes the file unreadable.
         if self._stop is not None and self._stop.reason == StopReason.EXCEPTION and self._stop.frame.type == "SUITE":
             self._echo("! Keywords can't run at the end of a suite: its output is already closed.")
-            return
+            return False
         try:
             test, errors = self.get_test_body_from_string(line)
         except Exception as e:  # surface any parse failure to the prompt
             self._echo(f"! {e}")
-            return
+            return False
         if errors:
             for err in errors:
                 self._echo(f"! {err}")
-            return
+            return False
         if not test.body:
-            return
+            return True
         # Keywords evaluated at a stop don't count for the session status.
         record_failures, self.record_failures = self.record_failures, False
         try:
@@ -868,7 +884,8 @@ class ConsoleInterpreter(BaseInterpreter):
                     self.set_last_result(self.run_keyword(kw))
         finally:
             self.record_failures = record_failures
-        self._echo(f"=> {_repr.repr(self.last_result)}")
+        self._echo_result(test.body[-1], self.last_result)
+        return True
 
     # ------------------------------------------------------------------
     # Robot integration
@@ -892,6 +909,18 @@ class ConsoleInterpreter(BaseInterpreter):
             # than crash the REPL.
             pass
 
+    def show_result(self, statement: Keyword, result: Any) -> None:
+        if not self._input_from_file:
+            self._echo_result(statement, result)
+
+    def _echo_result(self, statement: Any, result: Any) -> None:
+        """Print the result of `statement` as `=> <value>`, at the `>>>` and the `(rdb)` prompt alike.
+        `None` shows nothing, and neither does an assignment: the message that sets the variable
+        names the value."""
+        if result is None or getattr(statement, "assign", None):
+            return
+        self._echo(f"=> {_repr.repr(result)}")
+
     def _alias_setting_imports(self, test: "running.TestCase") -> None:
         """REPL-only: rewrite top-level ``Library`` / ``Resource`` / ``Variables``
         keyword calls into the BuiltIn ``Import …`` keywords.
@@ -929,8 +958,10 @@ class ConsoleInterpreter(BaseInterpreter):
             text = file.read_text(encoding="utf-8")
 
             # Run like a test body: an invalid statement fails when execution reaches it.
+            self._input_from_file = True
             yield from self._body_to_run(self.parse_input(text))
         else:
+            self._input_from_file = False
             if self._input_ended:
                 raise EOFError
 
@@ -938,8 +969,8 @@ class ConsoleInterpreter(BaseInterpreter):
             last_one = False
             while True:
                 prompt = ""
-                if sys.stdin.isatty():
-                    prompt = ">>> " if not lines else "... "
+                if self.show_prompt:
+                    prompt = self.PROMPT if not lines else "... "
 
                 prefill = compute_indent(lines) if lines else ""
                 try:

robotcode/repl/hooks.py

@@ -6,8 +6,9 @@ from robotcode.plugin import hookimpl
 
 from .cli import repl, robot_debug
 from .doc_cli import doc
+from .session_cli import session
 
 
 @hookimpl
 def register_cli_commands() -> List[click.Command]:
-    return [repl, robot_debug, doc]
+    return [repl, robot_debug, doc, session]

robotcode/repl/prompt_toolkit_interpreter.py

@@ -67,6 +67,7 @@ class PromptToolkitConsoleInterpreter(ConsoleInterpreter):
         show_keywords: bool = False,
         inspect: Optional[bool] = False,
         no_history: bool = False,
+        show_prompt: bool = False,
     ) -> None:
         super().__init__(
             app=app,
@@ -74,6 +75,7 @@ class PromptToolkitConsoleInterpreter(ConsoleInterpreter):
             show_keywords=show_keywords,
             inspect=inspect,
             no_history=no_history,
+            show_prompt=show_prompt,
         )
 
         self._history_store: History