gh-141374: Add vi mode to PyREPL #141375

lkollar · 2025-11-10T20:43:22Z

This adds basic vi mode commands to pyrepl, supporting basic motions. The feature can be enabled by setting the PYREPL_VI_MODE environment variable.

Issue: Add vi mode to pyrepl #141374

The first line of multi-line input should display ps1 (primary prompt) not ps2 (continuation prompt). This is important for vi mode where users navigate through existing multi-line code with cursor movements.

In emacs mode _ is not a word boundary but in vi it is.

Vi has three character classes: word chars (alnum + _), punctuation (non-word, non-whitespace), and whitespace. Now w, e, and b treat punctuation sequences as separate words, matching vim behavior.

Use vi_backward_word on b key in vi mode as the original emacs mode implementation respects different word boundaries.

Let's not clutter the Reader with more vi state fields.

picnixz

I will only make a high-level review because I'm not a REPL expert but this needs polishing and I don't really like the extra churn for all users who do not care about vi mode (it makes the default REPL implementation tied to conditionals depending on the vi mode)

We also need a What's New entry.

picnixz · 2025-11-22T16:46:38Z

Lib/_pyrepl/commands.py



 class KillCommand(Command):
+    modifies_buffer = True


I'm not fond of having commands implementation depending on VI mode. Insteaad, I would suggest having two sets of commands that are distinct classes instead, e.g.:

class right(Command): ... class vi_right(right): ...

where you can override whatever you need. Having each command being aware of the VI mode makes the implementation too rigid.

When entering a specific vi mode, the command handler should be replaced by the corresponding vi-compatible handler.

Sounds good, I'm moving all of these into separate subclasses.

picnixz · 2025-11-22T16:47:53Z

Lib/_pyrepl/reader.py

+MAX_VI_UNDO_STACK_SIZE = 100
+
+
+from .types import ViMode, ViFindState


Group the imports.

picnixz · 2025-11-22T16:49:46Z

Lib/_pyrepl/reader.py

            p += 1
        return p

+    def vi_eow(self, p: int | None = None) -> int:


I would appreciate all VI-related implementation to be on a different mixin but I don't know if it's feasible.

I think we could make it work with a mixin, but there is a potentially simpler solution here: since the vi_ methods only need the pos and buffer properties of the Reader, I can create separate pure functions for all of these, which take these as arguments. All these functions can be kept in a separate file. This should make testing simpler as well.

def vi_bow(buffer: list[str], pos: int) -> int: ...

In vi_commands.py:

r.pos = vi_bow(r.buffer, r.pos)

picnixz · 2025-11-22T16:51:36Z

Lib/_pyrepl/reader.py

+            return 0
+
+        p -= 1
+


General comment: avoid blank lines and only use them to separate sections inside functions as per PEP-8. The stdlib is usually written compactly.

picnixz · 2025-11-22T16:53:09Z

Lib/_pyrepl/types.py

 type CharWidths = list[int]
+
+
+class ViMode(str, enum.Enum):


Use StrEnum instead. Personally, I wouldn't even use an enum and just use plain constants (0, 1).

picnixz · 2025-11-22T16:53:26Z

Lib/_pyrepl/unix_console.py

            or bool(self.pollob.poll(timeout))
        )

+


Avoid unrelated changes.

picnixz · 2025-11-22T16:54:22Z

Lib/_pyrepl/unix_console.py


        while self.event_queue.empty():
+            if self.event_queue.has_pending_escape_sequence():
+                current_time_ms = time.monotonic() * 1000


What is this? why can't someone just keep their key pressed?

Escape is the key to switch to normal mode, but it is also the first byte of all terminal escape sequences, so if we were to map esc to the normal mode switch, that would overlap with those sequences and we wouldn't be able to tell them apart. When this happens pyrepl actually disables the overlapping commands and prints a warning about this.

The solution is to wait a bit to see if any other keys have been pressed immediately after the esc to tell these apart. This should not affect how escape sequences work and only introduce a small delay in vi mode when switching modes. I think keeping esc pressed will work fine, unless I misunderstood your concern.

picnixz · 2025-11-22T16:55:14Z

Lib/_pyrepl/base_eventqueue.py

 from .trace import trace

 class BaseEventQueue:
+    _ESCAPE_TIMEOUT_MS = 50


I don't think it's correct to expect timeouts. People can write slowly. Or not. Hold a key, or not. I also can't figure an example of when this would happen.

picnixz · 2025-11-22T16:57:52Z

Lib/_pyrepl/readline.py



+def _is_vi_mode_enabled() -> bool:
+    return os.environ.get("PYREPL_VI_MODE", "").lower() in {"1", "true", "on", "yes"}


We need something better. Like PYTHON_REPL_VI_MODE instead. Before we had PYTHON_BASIC_REPL for basic repl.

Yes, I agree. PYTHON_REPL_VI_MODE sounds good to me.

picnixz · 2025-11-22T16:58:28Z

Lib/_pyrepl/readline.py

+            self.reader = ReadlineAlikeReader(
+                console=console,
+                config=self.config,
+                use_vi_mode=_is_vi_mode_enabled()
+            )


In this case, I would rather have two different classes. One reader for vi mode and one without. We can have a base reader class though.

I thought about this designing the feature, but the Reader is subclassed in multiple places and the ReadlineAlikeReader composes those subclasses, making it impractical to have a separate Reader for vi mode. There could be a separate ReadlineAlikeReader but that seems like the wrong abstraction.

Would you still have this concern with #141375 (comment) moving the vi_ methods out of Reader? Also, all emacs shortcuts are directly handled in Reader so having a separate class for vi seems inconsistent. After the cleanup, relatively little vi-specific logic would remain in Reader: keymap setup, mode switching, undo stack and find state handling.

bedevere-app · 2025-11-22T16:58:44Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

lkollar · 2025-11-22T18:09:19Z

I will only make a high-level review because I'm not a REPL expert but this needs polishing and I don't really like the extra churn for all users who do not care about vi mode (it makes the default REPL implementation tied to conditionals depending on the vi mode)

Thanks for the review @picnixz. I intended this PR as a starting point to collect feedback on the design & implementation. I'm happy to iterate further based on the feedback. I'll address the comments shortly.

picnixz · 2025-11-22T19:18:00Z

For the implementation I would advise waiting for the code owners first. They may have different opinions (or may decide to reject the feature)

lkollar requested review from ambv, lysnikolaou and pablogsal as code owners November 10, 2025 20:43

bedevere-app bot added the awaiting review label Nov 10, 2025

bedevere-app bot mentioned this pull request Nov 10, 2025

Add vi mode to pyrepl #141374

Open

vstinner changed the title ~~gh-141374: Add vi mode~~ gh-141374: Add vi mode to PyREPL Nov 13, 2025

lkollar added 14 commits November 21, 2025 20:23

Implement vi mode and basic motions in pyrepl

beca8d7

Fix multi-line prompt display

a054e5d

The first line of multi-line input should display ps1 (primary prompt) not ps2 (continuation prompt). This is important for vi mode where users navigate through existing multi-line code with cursor movements.

Properly detect single ESC key

cd7b85d

Fix word boundary handling

17ef56b

In emacs mode _ is not a word boundary but in vi it is.

Add a couple of compound delete commands

0b14fce

Handle punctuation as separate words in vi motions

23babd6

Vi has three character classes: word chars (alnum + _), punctuation (non-word, non-whitespace), and whitespace. Now w, e, and b treat punctuation sequences as separate words, matching vim behavior.

Use vi-specific backward word logic

237f559

Use vi_backward_word on b key in vi mode as the original emacs mode implementation respects different word boundaries.

Implement W and B vi motions

1406699

Implement basic find commands

aa5b41a

Move vi find state into a class

e8afc9e

Let's not clutter the Reader with more vi state fields.

Implement 'cw' and 'r' commands

f863425

Implement undo

fa1a578

Implement D, X, C and s commands

0a8a1e3

Add tests for multiline editing

d3e358d

lkollar force-pushed the pyrepl/vi-mode branch from d1421e2 to d3e358d Compare November 22, 2025 16:39

picnixz requested changes Nov 22, 2025

View reviewed changes

bedevere-app bot added awaiting changes and removed awaiting review labels Nov 22, 2025

lkollar added 3 commits November 22, 2025 18:26

Avoid polluting base classes with vi undo logic

aeb8345

Reorder imports

f40ecaf

Simplify ViMode enum

86defc0

lkollar added 4 commits November 27, 2025 21:10

Move most of the vi-specific logic out of Reader

12197cb

Fix off by one in undo stack size check

d7311af

Fix unbounded undo stack growth bug

cbe7707

Move import to top of file

a6fb266

		MAX_VI_UNDO_STACK_SIZE = 100


		from .types import ViMode, ViFindState



		def _is_vi_mode_enabled() -> bool:
		return os.environ.get("PYREPL_VI_MODE", "").lower() in {"1", "true", "on", "yes"}

Uh oh!

gh-141374: Add vi mode to PyREPL #141375

Are you sure you want to change the base?

gh-141374: Add vi mode to PyREPL #141375

Uh oh!

Conversation

lkollar commented Nov 10, 2025 • edited by bedevere-app bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

picnixz left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

picnixz Nov 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bedevere-app bot commented Nov 22, 2025

Uh oh!

lkollar commented Nov 22, 2025

Uh oh!

picnixz commented Nov 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lkollar commented Nov 10, 2025 •

edited by bedevere-app bot

Loading

picnixz left a comment •

edited

Loading

picnixz Nov 22, 2025 •

edited

Loading