vith 0.9.0__tar.gz

vith-0.9.0/LICENSE

@@ -0,0 +1,28 @@
+Copyright (c) 2015-2023, Jonathan Slenders
+Copyright (c) 2026, Chaiwat Suttipongsakul
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this
+  list of conditions and the following disclaimer in the documentation and/or
+  other materials provided with the distribution.
+
+* Neither the name of the {organization} nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

vith-0.9.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: vith
+Version: 0.9.0
+Summary: Vith — a pure-Python Vi clone with Thai & Lao script support (fork of pyvim)
+Author: Jonathan Slenders
+Author-email: Chaiwat Suttipongsakul <cwt@bashell.com>
+Maintainer-email: Chaiwat Suttipongsakul <cwt@bashell.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/cwt/vith
+Project-URL: Repository, https://github.com/cwt/vith.git
+Project-URL: Upstream, https://github.com/prompt-toolkit/pyvim
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Text Editors
+Classifier: Topic :: Text Editors :: Text Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: prompt_toolkit<3.1.0,>=3.0.0
+Requires-Dist: pyflakes
+Requires-Dist: pygments
+Requires-Dist: docopt
+Provides-Extra: jedi
+Requires-Dist: jedi; extra == "jedi"
+Dynamic: license-file
+
+# vith (วิธ) — a fork of pyvim
+
+**vith** (Thai: **วิธ**, from วิธี / Pali-Skt *vidhi*, "method"; also a portmanteau of **Vi**M + **TH**Ai) is a fork of [pyvim](https://github.com/prompt-toolkit/pyvim) — "an implementation of Vim in Python" originally created by Jonathan Slenders.
+
+The upstream project was idle for several years, so this fork continues development independently. It adds **Thai & Lao script support** (terminal cell-cluster navigation and editing, two-tier word segmentation, SARA AM differential rendering) and **speed / latency / modern-Python stability** work (streamed + cached Pygments highlighting, lazy colorscheme loading, O(1) pyflakes error index, Python 3.14+/3.15 `asyncio` startup fix).
+
+Full credit and history are preserved: Jonathan Slenders' original changelog is retained verbatim in the `CHANGELOG` appendix, and the BSD 3-clause license is retained with stacked copyright.
+
+This fork is published as a separate PyPI package (`vith`) and is not a drop-in replacement for `pyvim`.
+
+---
+
+*An implementation of Vim in Python*
+
+```sh
+pip install vith
+```
+
+This fork runs on **Python 3.10+** (`prompt_toolkit` 3.0) and adds two large, machine-verified plans (documented in the `docs/` Open Knowledge bundle):
+
+- **Thai & Lao script support**: terminal cell-cluster navigation and editing (`h`, `l`, `j`, `k`, `x`, `X`, `s`, `r`, `~`, `$`, `e`...), two-tier Thai word segmentation (`libthai` with an always-available orthographic fallback) and SARA AM (`U+0E33`/`U+0EB3`) differential renderer fixes. See [`docs/thai_support_plan.md`](docs/thai_support_plan.md).
+- **Speed, latency & modern-Python stability**: streamed + cached Pygments highlighting, per-line word-span caches for Thai word motions, lazy colorscheme loading, cached word completion, an O(1) pyflakes error index, and the Python 3.14+/3.15 `asyncio` startup-crash fix. See [`docs/speed_latency_plan.md`](docs/speed_latency_plan.md).
+
+All changes are audited in [`docs/bugs/`](docs/bugs/) (findings, each reproduced and fixed); quality is enforced with pytest, mypy and ruff.
+
+Issues, questions, wishes, comments, feedback, remarks? Please create a GitHub issue, I appreciate it.
+
+---
+
+## Installation
+
+Simply install `vith` using pip:
+
+```sh
+pip install vith
+```
+
+For Python autocompletion support (via Jedi):
+
+```sh
+pip install "vith[jedi]"
+```
+
+It is a good idea to add the following to your `~/.bashrc` if you really want to use it:
+
+```sh
+alias vi=vith
+export EDITOR=vith
+```
+
+## The good things
+
+The editor is written completely in Python. (There are no C extensions). This makes development a lot faster. It's easy to prototype and integrate new features.
+
+We have already many nice things, for instance:
+
+- Syntax highlighting of files, using the Pygments lexers.
+- Horizontal and vertical splits, as well as tab pages. (Similar to Vim.)
+- All of the functionality of [prompt_toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit). This includes a lot of Vi key bindings, it's platform independent and runs every Python version covered by `python_requires >= 3.10`.
+- Thai/Lao input files: cell-cluster safe navigation and *syntax-aware* word segmentation, including dictionary segmentation when `libthai` is installed.
+- Several `:set ...` commands have been implemented, like `incsearch`, `number`, `ignorecase`, `wildmenu`, `expandtab`, `hlsearch`, `ruler`, `paste` and `tabstop`.
+- Other working commands: `vsplit`, `tabnew`, `only`, `badd`, and many others.
+- For Python source code, auto completion uses the amazing Jedi library, and code checking is done (asynchronously) through Pyflakes.
+- Colorschemes can be changed at runtime.
+
+Further, when the project develops, it should also become possible to write extensions in Python, and use Python as a scripting language. (Instead of vimscript, for instance.)
+
+We can also do some cool stuff. Like for instance running the editor on the Python asyncio event loop and having other coroutines interact with the editor.
+
+## Configuring vith
+
+It is possible to create a `.vithrc` file for a custom configuration (with graceful fallback to `~/.pyvimrc`). Have a look at this example: [`vithrc`](examples/config/vithrc)
+
+## Limitations
+
+Compared to Vi Improved, Vith is still less powerful in many aspects.
+
+- `prompt_toolkit` does not (or not yet) allow buffers to have an individual cursor when buffers are opened in several windows. Currently, this results in some unexpected behaviour, when a file is displayed in two windows at the same time. (The cursor could be displayed in the wrong window and other windows will sometimes scroll along when the cursor moves.) This has to be fixed in the future.
+- The data structure for a buffer is extremely simple. (Right now, it's just a Python string, and an integer for the cursor position.) This works extremely well for development and quickly prototyping of new features.
+- A lot of nice Vim features, like line folding, macros, etcetera are not yet implemented.
+- Windows support is not that nice. It works, but could be improved.
+
+## Roadmap
+
+Pull requests and issues are welcome. Feel free to create a GitHub issue to discuss ideas or report problems.
+
+Maybe some day we will have a better data structure (Rope), that makes it possible to open really large files. (With good algorithms, Python does not have to be slower than C code.)
+
+Maybe we will also have line folding and probably block editing. Maybe some day we will have a built-in Python debugger or mouse support. We'll see. :)
+
+## Testing
+
+To run all tests, install the development requirements (pytest, mypy, ruff):
+
+```sh
+python -m pip install -r requirements-dev.txt
+```
+
+And then run from the root `vith` directory:
+
+```sh
+python -m pytest tests
+```
+
+Quality gates: `mypy .` (typing, checked against the 3.10 floor), `ruff check` (lint) and `ruff format --check .` (formatting). The reproducible measurements quoted in the docs come from:
+
+```sh
+python tools/bench_plans.py
+```
+
+## Why was PyVim originally created?
+
+*(From Jonathan Slenders' original PyVim documentation)*:
+
+> "The main reason is maybe because it was a small step after I created the Python `prompt-toolkit` library. That is a library which is actually only a simply pure Python readline replacement, but with some nice additions like syntax highlighting and multiline editing. It was never intended to be a toolkit for full-screen terminal applications, but at some point I realised that everything we need for an editor was in there and I liked to challenge its design. So, I started an editor and the first proof of concept was literally just a few hundred lines of code, but it was already a working editor.
+>
+> The creation of `pyvim` will make sure that we have a solid architecture for `prompt-toolkit`, but it also aims to demonstrate the flexibility of the library. When it makes sense, features of `pyvim` will move back to `prompt-toolkit`, which in turn also results in a better Python REPL. (see [ptpython](https://github.com/prompt-toolkit/ptpython), an alternative REPL.)
+>
+> Above all, it is really fun to create an editor."
+
+## Why was the Vith fork created?
+
+Upstream `pyvim` has been idle for several years. Vith was created to bring modern Python support and first-class Southeast Asian language capabilities to terminal-based editing:
+
+- **Thai & Lao cell-cluster editing**: character-wise motions (`h`, `l`, `x`, `s`, `r`, `~`...) treat combining sequences as indivisible display cells, preventing dangling accents or cursor misalignment.
+- **Syntax-aware word segmentation**: two-tier word boundaries combining dictionary lookup (`libthai`) with an orthographic cluster fallback.
+- **Differential rendering fixes**: terminal diff-renderer updates for `SARA AM` (`U+0E33`/`U+0EB3`) and right-margin combining marks.
+- **Performance & latency**: streamed Pygments syntax lexing, deferred colorscheme compilation, singleton word-completion caches, and an O(1) pyflakes error index.
+- **Modern Python stability**: clean startup on Python 3.14+/3.15 asyncio event loops, PEP 621 packaging, and complete type annotations.
+
+## Alternatives
+
+Certainly have a look at the alternatives:
+
+- [Kaa](https://github.com/kaaedit/kaa) by @atsuoishimoto
+- [Vai](https://github.com/stefanoborini/vai) by @stefanoborini
+- [Vis](https://github.com/martanne/vis) by @martanne
+
+## Q & A
+
+**Q: Do you use curses?**  
+**A:** No, it uses only `prompt-toolkit`.
+
+## Thanks
+
+- To Jonathan Slenders, for creating PyVim and prompt_toolkit.
+- To Vi Improved, by Bram Moolenaar, for the inspiration.
+- To Jedi, pyflakes and docopt.
+- To the Python wcwidth port of Jeff Quast for support of double width characters.
+- To Guido van Rossum, for creating Python.

vith-0.9.0/README.md

@@ -0,0 +1,150 @@
+# vith (วิธ) — a fork of pyvim
+
+**vith** (Thai: **วิธ**, from วิธี / Pali-Skt *vidhi*, "method"; also a portmanteau of **Vi**M + **TH**Ai) is a fork of [pyvim](https://github.com/prompt-toolkit/pyvim) — "an implementation of Vim in Python" originally created by Jonathan Slenders.
+
+The upstream project was idle for several years, so this fork continues development independently. It adds **Thai & Lao script support** (terminal cell-cluster navigation and editing, two-tier word segmentation, SARA AM differential rendering) and **speed / latency / modern-Python stability** work (streamed + cached Pygments highlighting, lazy colorscheme loading, O(1) pyflakes error index, Python 3.14+/3.15 `asyncio` startup fix).
+
+Full credit and history are preserved: Jonathan Slenders' original changelog is retained verbatim in the `CHANGELOG` appendix, and the BSD 3-clause license is retained with stacked copyright.
+
+This fork is published as a separate PyPI package (`vith`) and is not a drop-in replacement for `pyvim`.
+
+---
+
+*An implementation of Vim in Python*
+
+```sh
+pip install vith
+```
+
+This fork runs on **Python 3.10+** (`prompt_toolkit` 3.0) and adds two large, machine-verified plans (documented in the `docs/` Open Knowledge bundle):
+
+- **Thai & Lao script support**: terminal cell-cluster navigation and editing (`h`, `l`, `j`, `k`, `x`, `X`, `s`, `r`, `~`, `$`, `e`...), two-tier Thai word segmentation (`libthai` with an always-available orthographic fallback) and SARA AM (`U+0E33`/`U+0EB3`) differential renderer fixes. See [`docs/thai_support_plan.md`](docs/thai_support_plan.md).
+- **Speed, latency & modern-Python stability**: streamed + cached Pygments highlighting, per-line word-span caches for Thai word motions, lazy colorscheme loading, cached word completion, an O(1) pyflakes error index, and the Python 3.14+/3.15 `asyncio` startup-crash fix. See [`docs/speed_latency_plan.md`](docs/speed_latency_plan.md).
+
+All changes are audited in [`docs/bugs/`](docs/bugs/) (findings, each reproduced and fixed); quality is enforced with pytest, mypy and ruff.
+
+Issues, questions, wishes, comments, feedback, remarks? Please create a GitHub issue, I appreciate it.
+
+---
+
+## Installation
+
+Simply install `vith` using pip:
+
+```sh
+pip install vith
+```
+
+For Python autocompletion support (via Jedi):
+
+```sh
+pip install "vith[jedi]"
+```
+
+It is a good idea to add the following to your `~/.bashrc` if you really want to use it:
+
+```sh
+alias vi=vith
+export EDITOR=vith
+```
+
+## The good things
+
+The editor is written completely in Python. (There are no C extensions). This makes development a lot faster. It's easy to prototype and integrate new features.
+
+We have already many nice things, for instance:
+
+- Syntax highlighting of files, using the Pygments lexers.
+- Horizontal and vertical splits, as well as tab pages. (Similar to Vim.)
+- All of the functionality of [prompt_toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit). This includes a lot of Vi key bindings, it's platform independent and runs every Python version covered by `python_requires >= 3.10`.
+- Thai/Lao input files: cell-cluster safe navigation and *syntax-aware* word segmentation, including dictionary segmentation when `libthai` is installed.
+- Several `:set ...` commands have been implemented, like `incsearch`, `number`, `ignorecase`, `wildmenu`, `expandtab`, `hlsearch`, `ruler`, `paste` and `tabstop`.
+- Other working commands: `vsplit`, `tabnew`, `only`, `badd`, and many others.
+- For Python source code, auto completion uses the amazing Jedi library, and code checking is done (asynchronously) through Pyflakes.
+- Colorschemes can be changed at runtime.
+
+Further, when the project develops, it should also become possible to write extensions in Python, and use Python as a scripting language. (Instead of vimscript, for instance.)
+
+We can also do some cool stuff. Like for instance running the editor on the Python asyncio event loop and having other coroutines interact with the editor.
+
+## Configuring vith
+
+It is possible to create a `.vithrc` file for a custom configuration (with graceful fallback to `~/.pyvimrc`). Have a look at this example: [`vithrc`](examples/config/vithrc)
+
+## Limitations
+
+Compared to Vi Improved, Vith is still less powerful in many aspects.
+
+- `prompt_toolkit` does not (or not yet) allow buffers to have an individual cursor when buffers are opened in several windows. Currently, this results in some unexpected behaviour, when a file is displayed in two windows at the same time. (The cursor could be displayed in the wrong window and other windows will sometimes scroll along when the cursor moves.) This has to be fixed in the future.
+- The data structure for a buffer is extremely simple. (Right now, it's just a Python string, and an integer for the cursor position.) This works extremely well for development and quickly prototyping of new features.
+- A lot of nice Vim features, like line folding, macros, etcetera are not yet implemented.
+- Windows support is not that nice. It works, but could be improved.
+
+## Roadmap
+
+Pull requests and issues are welcome. Feel free to create a GitHub issue to discuss ideas or report problems.
+
+Maybe some day we will have a better data structure (Rope), that makes it possible to open really large files. (With good algorithms, Python does not have to be slower than C code.)
+
+Maybe we will also have line folding and probably block editing. Maybe some day we will have a built-in Python debugger or mouse support. We'll see. :)
+
+## Testing
+
+To run all tests, install the development requirements (pytest, mypy, ruff):
+
+```sh
+python -m pip install -r requirements-dev.txt
+```
+
+And then run from the root `vith` directory:
+
+```sh
+python -m pytest tests
+```
+
+Quality gates: `mypy .` (typing, checked against the 3.10 floor), `ruff check` (lint) and `ruff format --check .` (formatting). The reproducible measurements quoted in the docs come from:
+
+```sh
+python tools/bench_plans.py
+```
+
+## Why was PyVim originally created?
+
+*(From Jonathan Slenders' original PyVim documentation)*:
+
+> "The main reason is maybe because it was a small step after I created the Python `prompt-toolkit` library. That is a library which is actually only a simply pure Python readline replacement, but with some nice additions like syntax highlighting and multiline editing. It was never intended to be a toolkit for full-screen terminal applications, but at some point I realised that everything we need for an editor was in there and I liked to challenge its design. So, I started an editor and the first proof of concept was literally just a few hundred lines of code, but it was already a working editor.
+>
+> The creation of `pyvim` will make sure that we have a solid architecture for `prompt-toolkit`, but it also aims to demonstrate the flexibility of the library. When it makes sense, features of `pyvim` will move back to `prompt-toolkit`, which in turn also results in a better Python REPL. (see [ptpython](https://github.com/prompt-toolkit/ptpython), an alternative REPL.)
+>
+> Above all, it is really fun to create an editor."
+
+## Why was the Vith fork created?
+
+Upstream `pyvim` has been idle for several years. Vith was created to bring modern Python support and first-class Southeast Asian language capabilities to terminal-based editing:
+
+- **Thai & Lao cell-cluster editing**: character-wise motions (`h`, `l`, `x`, `s`, `r`, `~`...) treat combining sequences as indivisible display cells, preventing dangling accents or cursor misalignment.
+- **Syntax-aware word segmentation**: two-tier word boundaries combining dictionary lookup (`libthai`) with an orthographic cluster fallback.
+- **Differential rendering fixes**: terminal diff-renderer updates for `SARA AM` (`U+0E33`/`U+0EB3`) and right-margin combining marks.
+- **Performance & latency**: streamed Pygments syntax lexing, deferred colorscheme compilation, singleton word-completion caches, and an O(1) pyflakes error index.
+- **Modern Python stability**: clean startup on Python 3.14+/3.15 asyncio event loops, PEP 621 packaging, and complete type annotations.
+
+## Alternatives
+
+Certainly have a look at the alternatives:
+
+- [Kaa](https://github.com/kaaedit/kaa) by @atsuoishimoto
+- [Vai](https://github.com/stefanoborini/vai) by @stefanoborini
+- [Vis](https://github.com/martanne/vis) by @martanne
+
+## Q & A
+
+**Q: Do you use curses?**  
+**A:** No, it uses only `prompt-toolkit`.
+
+## Thanks
+
+- To Jonathan Slenders, for creating PyVim and prompt_toolkit.
+- To Vi Improved, by Bram Moolenaar, for the inspiration.
+- To Jedi, pyflakes and docopt.
+- To the Python wcwidth port of Jeff Quast for support of double width characters.
+- To Guido van Rossum, for creating Python.

vith-0.9.0/pyproject.toml

@@ -0,0 +1,71 @@
+# Tool configuration and PEP 621 packaging for vith.
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vith"
+version = "0.9.0"
+description = "Vith — a pure-Python Vi clone with Thai & Lao script support (fork of pyvim)"
+readme = "README.md"
+license = "BSD-3-Clause"
+authors = [
+    { name = "Jonathan Slenders" },
+    { name = "Chaiwat Suttipongsakul", email = "cwt@bashell.com" },
+]
+maintainers = [
+    { name = "Chaiwat Suttipongsakul", email = "cwt@bashell.com" },
+]
+requires-python = ">=3.10"
+dependencies = [
+    "prompt_toolkit>=3.0.0,<3.1.0",
+    "pyflakes",
+    "pygments",
+    "docopt",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Topic :: Text Editors",
+    "Topic :: Text Editors :: Text Processing",
+]
+[project.urls]
+Homepage = "https://github.com/cwt/vith"
+Repository = "https://github.com/cwt/vith.git"
+Upstream = "https://github.com/prompt-toolkit/pyvim"
+
+[project.optional-dependencies]
+jedi = [
+    "jedi",
+]
+
+[project.scripts]
+vith = "vith.entry_points.run_vith:run"
+
+[tool.setuptools.packages.find]
+include = ["vith*"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+extend-exclude = ["docs", "examples"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = [
+    # `ruff format` keeps long string literals intact; do not fail lint on them.
+    "E501",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["vith"]
+
+[tool.ruff.format]
+# Keep the existing mix of single/double quotes instead of rewriting every
+# string in one sweep.
+quote-style = "preserve"

vith-0.9.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vith-0.9.0/tests/test_cd.py

@@ -0,0 +1,18 @@
+import os
+
+from vith.commands.handler import handle_command
+
+
+def test_cd_no_arg_and_expanduser(editor, tmp_path):
+    editor.load_initial_files([None])
+    home = os.path.expanduser('~')
+    # :cd with no argument goes home.
+    handle_command(editor, ':cd')
+    assert os.getcwd() == home
+    # :cd with ~/ path expands.
+    d = tmp_path / 'sub'
+    d.mkdir()
+    handle_command(editor, ':cd %s' % d)
+    assert os.getcwd() == str(d)
+    # restore
+    os.chdir(home)

vith-0.9.0/tests/test_commands_grammar.py

@@ -0,0 +1,14 @@
+from vith.commands.grammar import COMMAND_GRAMMAR
+from vith.commands.handler import handle_command
+
+
+def test_colo_matches_grammar():
+    m = COMMAND_GRAMMAR.match('colo default')
+    assert m is not None
+    assert m.variables().get('command') == 'colo'
+    assert m.variables().get('colorscheme') == 'default'
+
+
+def test_unknown_multiword_command_shows_message(editor):
+    handle_command(editor, ':foo bar')
+    assert editor.message is not None

vith-0.9.0/tests/test_completion.py

@@ -0,0 +1,158 @@
+"""
+Tests for `vith/completion.py` (P3: singleton + line-cached word completer).
+"""
+
+from prompt_toolkit.completion import CompleteEvent
+from prompt_toolkit.document import Document
+
+from vith.completion import DocumentCompleter, DocumentWordsCompleter
+
+
+def _completions(completer, text, cursor):
+    doc = Document(text, cursor)
+    return [c.text for c in completer.get_completions(doc, CompleteEvent())]
+
+
+def test_words_from_other_lines():
+    # 'f' on the cursor line matches 'foo' found in other lines:
+    comps = _completions(DocumentWordsCompleter(), 'foo bar baz\nf', 13)
+    assert 'foo' in comps
+
+
+def test_words_from_current_line():
+    # 'foobar' on the non-cursor lines completes 'fo' typed on the
+    # current line:
+    comps = _completions(DocumentWordsCompleter(), 'foobar\nfo', 9)
+    assert comps == ['foobar']
+
+
+def test_exact_word_before_cursor_not_offered():
+    # The word itself is never offered as its own completion:
+    comps = _completions(DocumentWordsCompleter(), 'foo bar\nfoo', 11)
+    assert comps == []
+
+
+def test_no_word_before_cursor_yields_nothing():
+    comps = _completions(DocumentWordsCompleter(), 'foo bar\n ', 9)
+    assert comps == []
+
+
+def test_cache_key_stable_while_typing_on_current_line():
+    comp = DocumentWordsCompleter()
+    assert comp._cached_key is None
+
+    c1 = _completions(comp, 'alpha beta\nal', 13)
+    assert c1 == ['alpha']
+    key = comp._cached_key
+    assert key is not None
+
+    # Typing on the current line leaves the prefix/suffix around that line
+    # unchanged: the non-cursor word cache must *not* be recomputed.
+    c2 = _completions(comp, 'alpha beta\nalp', 14)
+    assert c2 == ['alpha']
+    assert comp._cached_key == key, 'typing on the current line must not rescan the other lines'
+
+
+def test_cache_invalidated_when_other_lines_change():
+    comp = DocumentWordsCompleter()
+    _completions(comp, 'alpha beta\nal', 13)
+    key_before = comp._cached_key
+
+    # 'alpine' appears on a non-cursor line of the *new* text:
+    c3 = _completions(comp, 'alpha zebra alpine\nal', 21)
+    assert c3 == ['alpha', 'alpine']
+    assert comp._cached_key != key_before, (
+        'changed other lines must invalidate the non-cursor word cache'
+    )
+
+
+def test_document_completer_persists_words_completer(editor, editor_buffer):
+    # P3: `DocumentCompleter` must reuse a single `DocumentWordsCompleter`
+    # across invocations (the cache is only useful if it persists).
+    editor.enable_jedi = False
+    editor_buffer.location = None  # treated as '.txt' -> words completer
+
+    completer = DocumentCompleter(editor, editor_buffer)
+    assert isinstance(completer._words_completer, DocumentWordsCompleter)
+    assert completer._words_completer._cached_key is None
+
+    doc = Document('gamma alpha\ngamm', 16)
+    assert 'gamma' in [c.text for c in completer.get_completions(doc, CompleteEvent())]
+    assert completer._words_completer._cached_key is not None
+
+    words_completer = completer._words_completer
+    list(completer.get_completions(doc, CompleteEvent()))
+    assert completer._words_completer is words_completer, (
+        'the words completer instance must persist across calls'
+    )
+
+
+def test_document_completer_python_uses_jedi(editor, editor_buffer, tmp_path):
+    import pytest
+
+    pytest.importorskip('jedi')
+
+    p = tmp_path / 'mod.py'
+    p.write_text('import os\n')
+    editor.enable_jedi = True
+    editor_buffer.location = str(p)
+
+    completer = DocumentCompleter(editor, editor_buffer)
+    doc = Document('import o', 8)
+    # Iterate: this must exercise the Jedi path (both old `completions()`
+    # and new `complete(line, column)` APIs) and not the words completer.
+    names = [c.text for c in completer.get_completions(doc, CompleteEvent())]
+    assert 'os' in names
+    assert completer._words_completer._cached_key is None, (
+        '.py files with Jedi enabled must not use the words completer'
+    )
+    # The jedi API introspection is computed once per session (docs/bugs/030.md):
+    import vith.completion as _pc
+
+    assert _pc._JEDI_TAKES_COLUMN is False
+
+
+def test_document_completer_falls_back_without_jedi(editor, editor_buffer, monkeypatch):
+    # jedi is optional: when the module is missing (or the probe is forced
+    # off), `.py` buffers must complete with the words completer instead of
+    # raising ImportError on the first Tab press (docs/bugs/003.md).
+    monkeypatch.setattr('vith.completion._jedi_available', lambda: False)
+    editor.enable_jedi = True
+    editor_buffer.location = '/some/project/module.py'
+
+    completer = DocumentCompleter(editor, editor_buffer)
+    doc = Document('gamma alpha\ngamm', 16)
+    names = [c.text for c in completer.get_completions(doc, CompleteEvent())]
+    assert names == ['gamma']
+
+    # And with no word before the cursor the fallback stays silent.
+    doc = Document('import o', 8)
+    assert [c.text for c in completer.get_completions(doc, CompleteEvent())] == []
+
+
+def test_python_completer_missing_module_degrades_to_no_completions(
+    editor, editor_buffer, monkeypatch
+):
+    # Even if selection ever picks `_PythonCompleter`, a missing jedi module
+    # must degrade to "no completions" rather than crash (ImportError guard).
+    import sys
+
+    import vith.completion as completion_module
+
+    monkeypatch.setitem(sys.modules, 'jedi', None)  # `import jedi` -> ImportError
+    monkeypatch.setattr(completion_module, '_jedi_available', lambda: True)
+
+    editor.enable_jedi = True
+    editor_buffer.location = '/some/project/module.py'
+    completer = DocumentCompleter(editor, editor_buffer)
+
+    doc = Document('import o', 8)
+    list(completer.get_completions(doc, CompleteEvent()))  # must not raise
+
+
+def test_thai_words_not_split_at_combining_marks():
+    text = 'ที่ดิน น้ำ ผู้ใหญ่\nที่'
+    comps = _completions(DocumentWordsCompleter(), text, len('ที่ดิน น้ำ ผู้ใหญ่\nที่'))
+    assert 'ที่ดิน' in comps or 'ดิน' not in comps
+    # The corrupted single-base token 'ใหญ' (missing tone mark) must not appear.
+    assert 'ใหญ' not in comps