CLI passthrough (PTY) mode, standalone snippet output by carli2 · Pull Request #256 · pycontribs/ansi2html

carli2 · 2025-09-19T18:11:50Z

CLI passthrough (PTY), standalone snippets, and pager safeguards

Summary

Add command passthrough mode: run a command in a colored PTY and convert its output to HTML.
Introduce --standalone (-S) to emit a minimal inline HTML snippet wrapped in <code>.
Disable auto‑pagers in PTY by default (GIT_PAGER=cat, PAGER=cat) to prevent hangs; users can override.
Refresh --help, README/docs, and man page; add targeted tests.

Why

Capturing realistic colorized output from CLIs (e.g., git) usually requires a TTY. This PR makes it easy to run such commands, capture their ANSI-colored output, and convert it to HTML
reliably—without getting stuck behind pagers.

What’s Changed

PTY passthrough execution with argument parsing and TERM=xterm-256color.
--standalone (-S): like --inline but wrapped in <code style='white-space: pre;'>…</code> for convenient embedding.
Pager safeguards in PTY mode: set GIT_PAGER=cat and PAGER=cat by default to avoid hangs.
Documentation updates and new tests covering passthrough and pager behavior.

Usage

Run a command and convert its colored output:
```
ansi2html git log -p > git-log.html
```
Separate ansi2html options from the child command:

ansi2html --inline -- git log -p > inline-git-log.html
Produce a minimal embeddable snippet:

echo $'\e[31mRED\e[0m' | ansi2html --standalone

short form:

echo $'\e[31mRED\e[0m' | ansi2html -S

Behavior Notes

Argument parsing:
- After --, all args belong to the child command.
- Without --, the first non-option token starts the child command; all following tokens belong to it.
PTY environment:
- Sets TERM=xterm-256color.
- Captures stdout and stderr together for conversion.
Pagers:
- In PTY mode, sets GIT_PAGER=cat and PAGER=cat by default.
- Override explicitly if desired, e.g. GIT_PAGER="less -R".

Docs & Tests

Updated: --help, README, dedicated CLI docs, and the man page.
Tests added/updated to cover passthrough execution and pager disabling.

Backwards Compatibility

Existing pipelines and options continue to work unchanged.
Pager behavior only changes in PTY passthrough mode and can be overridden.

Commits

baa58eb: cli: add --standalone (-S), disable pagers in PTY, refresh help/docs/man, add tests
3d9e750: add passthrough “wrapper” mode to execute commands in a colored, non‑paged TTY

Checklist

…n a non-paged colored tty

…e-space: pre;'> wrapper; disable pagers in PTY (GIT_PAGER/PAGER=cat); refresh --help, docs, and man page; add tests

Thorsrud22

Thanks for this. Running a command inside a PTY is a genuinely useful addition, and the happy path works: ansi2html --partial -- printf '\033[31mRED\033[0m' gives <span class="ansi31">RED</span>. I checked the branch out and exercised it on macOS; here is what I found, roughly in order of severity.

Blocking

import pty at module level breaks import ansi2html on Windows. pty imports tty, which does from termios import *, and termios is Unix-only. Simulating a platform without termios (sys.modules['termios'] = None): main imports fine, this branch raises ImportError. ansi2html is a library with ~2M downloads/month, so an import-time failure hits every consumer on Windows even if they never use the CLI. Fix is easy: import pty, select and subprocess inside the passthrough branch (or a helper function) so stdin mode keeps working everywhere.
The "first non-option token starts the command" heuristic breaks every option that takes a separate value. On this branch, all of these fail with expected one argument while working on main:
```
ansi2html -s solarized --partial < in.txt
ansi2html -t Foo --partial < in.txt
ansi2html -f 12 --partial < in.txt
ansi2html --input-encoding utf-8 --partial < in.txt
```
Only the --scheme=solarized form survives. Rather than re-implementing option parsing, let argparse do it: a command positional with nargs=argparse.REMAINDER (or parse_known_args) handles -- and knows which options consume a value. Alternatively require the explicit -- and drop the heuristic entirely.
The branch conflicts with main (19 commits behind, GitHub reports CONFLICTING). The .pre-commit-config.yaml hunk is already on main and should drop out on rebase.

Should fix

Child exit status is discarded. ansi2html sh -c 'exit 3' exits 0. Propagating proc.returncode via sys.exit would make this usable in scripts.
A child that reads stdin hangs forever. The child's stdin is the PTY slave, and nothing ever writes to the master, so ansi2html cat never returns. stdin=subprocess.DEVNULL seems right for an output-capture tool.
--help now prints a doubled usage block. usage=main.__doc__ renders as usage: \n Usage:\n ansi2html ..., and the examples appear again in epilog. Dropping usage= and keeping the examples only in epilog fixes both.
Non-ASCII hyphen in help text. "pseudo‑terminal" in the description (and README) uses U+2011, which can raise on a non-UTF-8 stdout. A plain - is safer.
LESS=-R is set but not documented anywhere (PR body, --help, man page). Either document it alongside GIT_PAGER/PAGER or drop it.

Tests

tests/helpers.py pops every ansi2html* module from sys.modules and prepends src/ to sys.path. tox already installs the package in develop mode, so this isn't needed, and it can make two different module objects coexist so a patch on one doesn't affect the other. from ansi2html import converter is enough. The script parameter of run_with_fake_pty is also unused.
The fake PTY is an os.pipe, so the actual pty.openpty + select + EIO/EOF loop, which is the risky part and differs between Linux and macOS, is never exercised. One real-PTY test (skipped on non-Unix) would cover it.

Scope suggestion

--standalone/-S and the man-page entries for the existing -W, -L, -s, -t options are independent of PTY passthrough and look ready. Splitting them into a small separate PR would let them land now regardless of how the passthrough discussion goes.

Happy to re-test once it's rebased.

Thorsrud22 · 2026-09-11T16:21:03Z

 import argparse
 import io
+import os
+import pty


pty -> tty -> from termios import *, and termios doesn't exist on Windows, so this makes import ansi2html itself fail there (verified by blocking termios in sys.modules: main imports, this branch raises ImportError). Suggest importing pty, select and subprocess inside the passthrough branch so stdin mode keeps working on every platform.

Thorsrud22 · 2026-09-11T16:21:03Z

+        # Treat the first non-option token as the start of the command
+        split_at = None
+        for i, tok in enumerate(argv):
+            if not tok.startswith("-"):


This treats the value of any option as the start of the command. On this branch ansi2html -s solarized --partial < in.txt fails with argument -s/--scheme: expected one argument (same for -t, -f, --input-encoding); all work on main. Letting argparse own this, e.g. a command positional with nargs=argparse.REMAINDER, avoids re-implementing option parsing and still supports --.

Thorsrud22 · 2026-09-11T16:21:03Z

+            "    to avoid hanging pagers; set them explicitly to override."
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+        usage=main.__doc__,


With usage= set to the docstring, --help now prints usage: followed by a second Usage: heading, and the examples repeat in epilog. Dropping usage= and keeping examples only in epilog gives a clean help page.

Thorsrud22 · 2026-09-11T16:21:03Z

+    parser = argparse.ArgumentParser(
+        description=(
+            "Convert text with ANSI color codes to HTML/LaTeX.\n\n"
+            "Can also run a command inside a PTY (pseudo‑terminal) and convert\n"


The hyphen in "pseudo‑terminal" is U+2011 (non-breaking hyphen), here and in the README. A plain ASCII - avoids encoding errors on a non-UTF-8 stdout.

Thorsrud22 · 2026-09-11T16:21:03Z

+        env.setdefault("GIT_PAGER", "cat")
+        env.setdefault("PAGER", "cat")
+        # Keep color passthrough if a pager is still used for some reason
+        env.setdefault("LESS", "-R")


LESS=-R isn't mentioned in the PR description, --help, or the man page, unlike GIT_PAGER/PAGER. Either document it with the others or drop it.

Thorsrud22 · 2026-09-11T16:21:03Z

+            try:
+                with subprocess.Popen(
+                    cmd_args,
+                    stdin=slave_fd,


With stdin attached to the PTY slave and nothing writing to the master, a child that reads stdin blocks forever: ansi2html cat never returns. stdin=subprocess.DEVNULL seems like the right default for an output-capture tool.

Thorsrud22 · 2026-09-11T16:21:03Z

+            except OSError:
+                pass
+
+        ansi_text = b"".join(chunks).decode(opts.input_encoding, "replace")


The child's exit status is dropped here: ansi2html sh -c 'exit 3' exits 0. Propagating proc.returncode (e.g. sys.exit(proc.returncode) after printing) would make this usable in scripts and CI.

Thorsrud22 · 2026-09-11T16:21:03Z

+from unittest.mock import patch
+
+
+def import_local_converter() -> Any:


tox runs with usedevelop = True, so the installed ansi2html already is src/. Popping modules from sys.modules and re-importing can leave two distinct ansi2html.converter module objects alive, so a patch applied to one won't be seen by code holding the other. A plain from ansi2html import converter should be enough.

Thorsrud22 · 2026-09-11T16:21:03Z

+    return importlib.import_module("ansi2html.converter")
+
+
+def run_with_fake_pty(conv: Any, argv: Iterable[str], script: str) -> None:


script is unused in this helper.

carli2 added 2 commits September 19, 2025 16:53

second call option: wrapper. ansi2html COMMAND will execute COMMAND i…

3d9e750

…n a non-paged colored tty

cli: add --standalone (-S) inline snippet mode with <code style='whit…

baa58eb

…e-space: pre;'> wrapper; disable pagers in PTY (GIT_PAGER/PAGER=cat); refresh --help, docs, and man page; add tests

carli2 requested a review from ssbarnea as a code owner September 19, 2025 18:11

fix docs

8421333

carli2 force-pushed the main branch from de77e5d to 695a7e1 Compare September 19, 2025 19:23

fulfill CI requirements

4211a53

carli2 force-pushed the main branch from 695a7e1 to 4211a53 Compare September 19, 2025 19:25

Thorsrud22 reviewed Sep 11, 2026

View reviewed changes

Thorsrud22 mentioned this pull request Sep 11, 2026

❤️‍🩹 Looking for maintainers! #135

Open

Navigation Menu

Uh oh!

CLI passthrough (PTY) mode, standalone snippet output - #256

CLI passthrough (PTY) mode, standalone snippet output#256
carli2 wants to merge 4 commits into
pycontribs:mainfrom
launix-de:main

carli2 commented Sep 19, 2025 •

edited

Loading

Uh oh!

Thorsrud22 left a comment

Uh oh!

Thorsrud22 Sep 11, 2026

Uh oh!

Thorsrud22 Sep 11, 2026

Uh oh!

Thorsrud22 Sep 11, 2026

Uh oh!

Thorsrud22 Sep 11, 2026

Uh oh!

Thorsrud22 Sep 11, 2026

Uh oh!

Thorsrud22 Sep 11, 2026

Uh oh!

Thorsrud22 Sep 11, 2026

Uh oh!

Thorsrud22 Sep 11, 2026

Uh oh!

Thorsrud22 Sep 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		from unittest.mock import patch


		def import_local_converter() -> Any:

		return importlib.import_module("ansi2html.converter")


		def run_with_fake_pty(conv: Any, argv: Iterable[str], script: str) -> None:

Uh oh!

Conversation

carli2 commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CLI passthrough (PTY), standalone snippets, and pager safeguards

Summary

Why

What’s Changed

Usage

short form:

Behavior Notes

Docs & Tests

Backwards Compatibility

Commits

Checklist

Uh oh!

Thorsrud22 left a comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

carli2 commented Sep 19, 2025 •

edited

Loading