stata-cli 0.2.0__py3-none-any.whl

stata_cli/main.py

@@ -0,0 +1,343 @@
+"""Stata CLI - run Stata commands from the terminal."""
+
+import json
+import os
+import sys
+
+import click
+
+from . import __version__
+from .engine import StataEngine, Result
+from .output_filter import apply_compact_filter, check_token_limit, clean_log_wrapper
+from .utils import detect_stata_path
+
+
+# Exit codes
+EXIT_OK = 0
+EXIT_STATA_ERROR = 1
+EXIT_USAGE_ERROR = 2
+EXIT_INIT_FAILURE = 3
+
+
+def _exit(code: int) -> None:
+    """Exit bypassing atexit hooks — PyStata registers one that resets the exit code to 0."""
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os._exit(code)
+
+
+@click.group()
+@click.version_option(__version__, prog_name="stata-cli")
+@click.option("--stata-path", envvar="STATA_PATH", default=None, help="Path to Stata installation directory.")
+@click.option("--edition", type=click.Choice(["mp", "se", "be"], case_sensitive=False), default="mp", help="Stata edition.")
+@click.option("--compact", is_flag=True, default=False, help="Apply compact output filter (strip verbose noise).")
+@click.option("--json", "use_json", is_flag=True, default=False, help="Output results as JSON (for agent consumption).")
+@click.option("--timeout", type=float, default=600.0, help="Execution timeout in seconds.")
+@click.option("--max-tokens", type=int, default=0, help="Max output tokens (0=unlimited). Saves full output to file when exceeded.")
+@click.option("--no-daemon", is_flag=True, default=False, help="Force direct execution, skip daemon.")
+@click.option("--graphs-dir", envvar="STATA_CLI_GRAPHS_DIR", default=None, help="Graph export directory.")
+@click.pass_context
+def cli(ctx, stata_path, edition, compact, use_json, timeout, max_tokens, no_daemon, graphs_dir):
+    """Command-line interface for Stata."""
+    ctx.ensure_object(dict)
+    ctx.obj["stata_path"] = stata_path
+    ctx.obj["edition"] = edition
+    ctx.obj["compact"] = compact
+    ctx.obj["json"] = use_json
+    ctx.obj["timeout"] = timeout
+    ctx.obj["max_tokens"] = max_tokens
+    ctx.obj["no_daemon"] = no_daemon
+    ctx.obj["graphs_dir"] = graphs_dir
+
+
+def _get_engine(ctx) -> StataEngine:
+    stata_path = ctx.obj["stata_path"] or detect_stata_path()
+    if not stata_path:
+        click.echo("Error: Stata installation not found.", err=True)
+        click.echo("Set --stata-path or the STATA_PATH environment variable.", err=True)
+        _exit(EXIT_INIT_FAILURE)
+    try:
+        engine = StataEngine(stata_path, ctx.obj["edition"], graphs_dir=ctx.obj.get("graphs_dir"))
+        return engine
+    except Exception as exc:
+        click.echo(f"Error initializing Stata: {exc}", err=True)
+        _exit(EXIT_INIT_FAILURE)
+
+
+def _try_daemon(ctx, cmd_type: str, payload: dict) -> Result | None:
+    """Try to route through daemon. Returns None if daemon unavailable."""
+    if ctx.obj.get("no_daemon"):
+        return None
+    try:
+        from .daemon import DaemonClient
+        client = DaemonClient()
+        if not client.is_running():
+            return None
+        if not client.connect():
+            return None
+        resp = client.send(cmd_type, payload)
+        client.close()
+        return Result(
+            success=resp.get("success", resp.get("status") == "success"),
+            output=resp.get("output", ""),
+            error=resp.get("error", ""),
+            execution_time=resp.get("execution_time", 0.0),
+            return_code=resp.get("return_code", 0),
+            extra=resp.get("extra", {}),
+        )
+    except Exception:
+        return None
+
+
+def _print_result(result, compact: bool, use_json: bool = False, max_tokens: int = 0, filter_echo: bool = False) -> None:
+    output = result.output
+    if output:
+        output = clean_log_wrapper(output)
+        if compact:
+            output = apply_compact_filter(output, filter_command_echo=filter_echo)
+        if max_tokens > 0:
+            output, _ = check_token_limit(output, max_tokens)
+        result.output = output
+
+    graphs = result.extra.get("graphs", []) if result.extra else []
+
+    if use_json:
+        click.echo(result.to_json())
+        if not result.success:
+            _exit(EXIT_STATA_ERROR)
+        return
+
+    if output and output.strip():
+        click.echo(output)
+    if graphs:
+        for g in graphs:
+            click.echo(f"[graph] {g.get('name', 'graph')}: {g.get('path', '')}")
+    if not result.success:
+        if result.error:
+            click.echo(result.error, err=True)
+        _exit(EXIT_STATA_ERROR)
+
+
+# ── Commands ─────────────────────────────────────────────────────────────
+
+@cli.command()
+@click.argument("code")
+@click.pass_context
+def run(ctx, code):
+    """Execute a Stata code string.
+
+    Use '-' to read code from stdin (for piping).
+
+    \b
+    Examples:
+      stata-cli run "sysuse auto, clear"
+      stata-cli run "display 1+1"
+      echo "summarize price" | stata-cli run -
+    """
+    if code == "-":
+        code = sys.stdin.read()
+    if not code.strip():
+        click.echo("Error: empty code.", err=True)
+        _exit(EXIT_USAGE_ERROR)
+
+    result = _try_daemon(ctx, "execute", {"code": code, "timeout": ctx.obj["timeout"]})
+    if result is None:
+        engine = _get_engine(ctx)
+        result = engine.run(code, timeout=ctx.obj["timeout"])
+    _print_result(result, ctx.obj["compact"], use_json=ctx.obj["json"], max_tokens=ctx.obj["max_tokens"])
+
+
+@cli.command("do")
+@click.argument("path", type=click.Path(exists=True))
+@click.pass_context
+def do_file(ctx, path):
+    """Execute a Stata .do file.
+
+    \b
+    Examples:
+      stata-cli do analysis.do
+      stata-cli --compact do long_script.do
+    """
+    result = _try_daemon(ctx, "execute_file", {"path": os.path.abspath(path), "timeout": ctx.obj["timeout"]})
+    if result is None:
+        engine = _get_engine(ctx)
+        result = engine.run_file(path, timeout=ctx.obj["timeout"])
+    _print_result(result, ctx.obj["compact"], use_json=ctx.obj["json"], max_tokens=ctx.obj["max_tokens"], filter_echo=True)
+
+
+@cli.command()
+@click.pass_context
+def detect(ctx):
+    """Print the auto-detected Stata installation path."""
+    stata_path = ctx.obj["stata_path"] or detect_stata_path()
+    if stata_path:
+        click.echo(stata_path)
+    else:
+        click.echo("Stata installation not found.", err=True)
+        _exit(EXIT_INIT_FAILURE)
+
+
+@cli.command("data")
+@click.option("--if", "if_condition", default=None, help="Stata if condition for filtering.")
+@click.option("--rows", type=int, default=10000, help="Maximum rows to return.")
+@click.pass_context
+def data_cmd(ctx, if_condition, rows):
+    """View the current dataset as JSON.
+
+    \b
+    Examples:
+      stata-cli data
+      stata-cli data --if "price>5000" --rows 50
+    """
+    # Try daemon first
+    try:
+        from .daemon import DaemonClient
+        client = DaemonClient()
+        if not ctx.obj.get("no_daemon") and client.is_running() and client.connect():
+            resp = client.send("get_data", {"if_condition": if_condition, "max_rows": rows})
+            client.close()
+            click.echo(json.dumps(resp, ensure_ascii=False, indent=2))
+            return
+    except Exception:
+        pass
+
+    engine = _get_engine(ctx)
+    resp = engine.get_data(if_condition=if_condition, max_rows=rows)
+    click.echo(json.dumps(resp, ensure_ascii=False, indent=2))
+
+
+@cli.command("help")
+@click.argument("topic")
+@click.pass_context
+def help_cmd(ctx, topic):
+    """Display Stata help for a topic.
+
+    \b
+    Examples:
+      stata-cli help regress
+      stata-cli help summarize
+    """
+    result = _try_daemon(ctx, "help", {"topic": topic})
+    if result is None:
+        engine = _get_engine(ctx)
+        result = engine.help(topic)
+    if ctx.obj["json"]:
+        click.echo(result.to_json())
+    elif result.output and result.output.strip():
+        click.echo(result.output)
+    else:
+        click.echo(f"No help found for: {topic}", err=True)
+        _exit(EXIT_STATA_ERROR)
+
+
+@cli.command("stop")
+@click.pass_context
+def stop_cmd(ctx):
+    """Interrupt a running Stata command (daemon mode)."""
+    try:
+        from .daemon import DaemonClient
+        client = DaemonClient()
+        if client.is_running() and client.connect():
+            resp = client.send("stop")
+            client.close()
+            click.echo(f"Stop signal: {resp.get('status', 'unknown')}")
+            return
+    except Exception:
+        pass
+    click.echo("Daemon not running.", err=True)
+    _exit(EXIT_USAGE_ERROR)
+
+
+# ── Daemon subcommands ───────────────────────────────────────────────────
+
+@cli.group()
+def daemon():
+    """Manage the Stata daemon process."""
+
+
+@daemon.command("start")
+@click.option("--idle-timeout", type=int, default=3600, help="Auto-shutdown after N seconds idle.")
+@click.pass_context
+def daemon_start(ctx, idle_timeout):
+    """Start the Stata daemon (keeps PyStata alive for fast execution)."""
+    stata_path = ctx.obj["stata_path"] or detect_stata_path()
+    if not stata_path:
+        click.echo("Error: Stata installation not found.", err=True)
+        _exit(EXIT_INIT_FAILURE)
+
+    from .daemon import start_daemon, DaemonClient
+    client = DaemonClient()
+    if client.is_running():
+        click.echo("Daemon already running.")
+        return
+
+    click.echo("Starting daemon...")
+    ok = start_daemon(stata_path, ctx.obj["edition"], graphs_dir=ctx.obj.get("graphs_dir"), idle_timeout=idle_timeout)
+    if ok:
+        click.echo("Daemon started.")
+    else:
+        click.echo("Failed to start daemon.", err=True)
+        _exit(EXIT_INIT_FAILURE)
+
+
+@daemon.command("stop")
+def daemon_stop():
+    """Stop the Stata daemon."""
+    from .daemon import stop_daemon, DaemonClient
+    client = DaemonClient()
+    if not client.is_running():
+        click.echo("Daemon not running.")
+        return
+    click.echo("Stopping daemon...")
+    stop_daemon()
+    click.echo("Daemon stopped.")
+
+
+@daemon.command("status")
+def daemon_status_cmd():
+    """Show daemon status."""
+    from .daemon import daemon_status
+    info = daemon_status()
+    if not info:
+        click.echo("Daemon not running.")
+        return
+    uptime = info.get("uptime", 0)
+    idle = info.get("idle", 0)
+    click.echo(f"Daemon running (PID {info.get('pid', '?')})")
+    click.echo(f"  Stata: {info.get('stata_path', '?')} ({info.get('edition', '?')})")
+    click.echo(f"  Uptime: {int(uptime)}s")
+    click.echo(f"  Idle: {int(idle)}s")
+
+
+@daemon.command("restart")
+@click.option("--idle-timeout", type=int, default=3600, help="Auto-shutdown after N seconds idle.")
+@click.pass_context
+def daemon_restart(ctx, idle_timeout):
+    """Restart the Stata daemon."""
+    from .daemon import stop_daemon, start_daemon, DaemonClient
+    client = DaemonClient()
+    if client.is_running():
+        click.echo("Stopping daemon...")
+        stop_daemon()
+
+    stata_path = ctx.obj["stata_path"] or detect_stata_path()
+    if not stata_path:
+        click.echo("Error: Stata installation not found.", err=True)
+        _exit(EXIT_INIT_FAILURE)
+
+    click.echo("Starting daemon...")
+    ok = start_daemon(stata_path, ctx.obj["edition"], graphs_dir=ctx.obj.get("graphs_dir"), idle_timeout=idle_timeout)
+    if ok:
+        click.echo("Daemon restarted.")
+    else:
+        click.echo("Failed to restart daemon.", err=True)
+        _exit(EXIT_INIT_FAILURE)
+
+
+# Allow running as `python -m stata_cli`
+def main():
+    cli()
+
+
+if __name__ == "__main__":
+    main()

stata_cli/output_filter.py

@@ -0,0 +1,239 @@
+"""Output filtering for Stata CLI.
+
+Provides compact-mode filtering (strips verbose/redundant output) and
+cleanup of the log-file wrapper lines injected by the engine.
+"""
+
+import os
+import re
+import time
+import tempfile
+
+
+_BANNER_END_RE = re.compile(r"^-{40,}$")
+_LOG_SCAFFOLD_PATTERNS = [
+    re.compile(r"^\s*\.?\s*capture\s+log\s+close", re.IGNORECASE),
+    re.compile(r"^\s*\.?\s*log\s+using\s+", re.IGNORECASE),
+    re.compile(r"^\s*(name|log|log type|opened on|closed on):", re.IGNORECASE),
+    # Continuation of a long log-using path that wraps to the next line
+    re.compile(r"^>\s.*\.log"),
+]
+
+
+def clean_log_wrapper(output: str) -> str:
+    """Remove Stata banner and ``log using`` / ``log close`` scaffolding."""
+    if not output:
+        return output
+
+    lines = output.split("\n")
+
+    # 1. Strip the startup banner (everything up to and including the "---…" separator)
+    start = 0
+    for i, line in enumerate(lines):
+        if _BANNER_END_RE.match(line.strip()):
+            start = i + 1
+            break
+
+    cleaned: list[str] = []
+    for line in lines[start:]:
+        if any(pat.match(line.strip()) for pat in _LOG_SCAFFOLD_PATTERNS):
+            continue
+        cleaned.append(line)
+
+    while cleaned and not cleaned[0].strip():
+        cleaned.pop(0)
+    while cleaned and not cleaned[-1].strip():
+        cleaned.pop()
+    return "\n".join(cleaned)
+
+
+def apply_compact_filter(output: str, filter_command_echo: bool = False) -> str:
+    """Strip verbose/redundant output to reduce noise.
+
+    Always filters:
+    - Program definition blocks
+    - Mata blocks
+    - Loop code echoes (keeps actual output)
+    - SMCL formatting tags
+    - Verbose messages like "(N real changes made)"
+
+    When *filter_command_echo* is True (e.g. for ``do`` files):
+    - Command echo lines (``". "`` prefix)
+    - Line continuations (``"> "``)
+    """
+    if not output:
+        return output
+
+    output = output.replace("\r\n", "\n").replace("\r", "\n")
+    lines = output.split("\n")
+    filtered: list[str] = []
+
+    command_echo_pat = re.compile(r"^\.\s*$|^\.\s+\S")
+    numbered_line_pat = re.compile(r"^\s*\d+\.\s")
+    continuation_pat = re.compile(r"^>\s")
+
+    program_drop_pat = re.compile(
+        r"^\s*\.?\s*(capture\s+program\s+drop|cap\s+program\s+drop|cap\s+prog\s+drop)\s+\w+",
+        re.IGNORECASE,
+    )
+    program_define_pat = re.compile(
+        r"^\s*\.?\s*program\s+(define\s+)?(?!version|dir|drop|list|describe)\w+",
+        re.IGNORECASE,
+    )
+    mata_start_pat = re.compile(
+        r"^\s*(\d+\.)?\s*\.?\s*mata\s*:?\s*$|^-+\s*mata\s*\(",
+        re.IGNORECASE,
+    )
+    end_pat = re.compile(r"^\s*(\d+\.)?\s*[.:]*\s*end\s*$", re.IGNORECASE)
+    mata_sep_pat = re.compile(r"^-{20,}$")
+
+    loop_start_pat = re.compile(
+        r"^(\s*\d+\.)?\s*\.?\s*(foreach|forvalues|while)\s+.*\{\s*$",
+        re.IGNORECASE,
+    )
+    loop_end_pat = re.compile(r"^\s*\d+\.\s*\}\s*$")
+
+    real_changes_pat = re.compile(r"^\s*\([\d,]+\s+real\s+changes?\s+made\)\s*$", re.IGNORECASE)
+    missing_values_pat = re.compile(r"^\s*\([\d,]+\s+missing\s+values?\s+generated\)\s*$", re.IGNORECASE)
+    smcl_pat = re.compile(
+        r"\{(txt|res|err|inp|com|bf|it|sf|hline|c\s+\||\-+|break|col\s+\d+|right|center|ul|/ul)\}"
+    )
+
+    in_program = False
+    in_mata = False
+    in_loop = False
+    program_end_depth = 0
+    loop_brace_depth = 0
+
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+
+        if in_program:
+            if mata_start_pat.match(line):
+                program_end_depth += 1
+            if end_pat.match(line):
+                if program_end_depth > 0:
+                    program_end_depth -= 1
+                else:
+                    in_program = False
+            i += 1
+            continue
+
+        if in_mata:
+            if end_pat.match(line):
+                in_mata = False
+                if i + 1 < len(lines) and mata_sep_pat.match(lines[i + 1]):
+                    i += 1
+            i += 1
+            continue
+
+        if in_loop:
+            if loop_start_pat.match(line):
+                loop_brace_depth += 1
+                i += 1
+                continue
+            if loop_end_pat.match(line):
+                if loop_brace_depth > 0:
+                    loop_brace_depth -= 1
+                else:
+                    in_loop = False
+                i += 1
+                continue
+            if command_echo_pat.match(line) or numbered_line_pat.match(line) or continuation_pat.match(line):
+                i += 1
+                continue
+            if real_changes_pat.match(line) or missing_values_pat.match(line):
+                i += 1
+                continue
+            line = smcl_pat.sub("", line)
+            if line.strip():
+                filtered.append(line)
+            i += 1
+            continue
+
+        if loop_start_pat.match(line):
+            in_loop = True
+            loop_brace_depth = 0
+            i += 1
+            continue
+
+        if program_drop_pat.match(line):
+            i += 1
+            continue
+        if program_define_pat.match(line):
+            in_program = True
+            program_end_depth = 0
+            i += 1
+            continue
+        if mata_start_pat.match(line):
+            in_mata = True
+            i += 1
+            continue
+
+        if real_changes_pat.match(line) or missing_values_pat.match(line):
+            i += 1
+            continue
+
+        if filter_command_echo:
+            if command_echo_pat.match(line) or numbered_line_pat.match(line) or continuation_pat.match(line):
+                i += 1
+                continue
+
+        line = smcl_pat.sub("", line)
+        filtered.append(line)
+        i += 1
+
+    # Collapse consecutive blank lines
+    result: list[str] = []
+    prev_blank = False
+    for line in filtered:
+        is_blank = not line.strip()
+        if is_blank:
+            if not prev_blank:
+                result.append(line)
+            prev_blank = True
+        else:
+            result.append(line)
+            prev_blank = False
+
+    while result and not result[-1].strip():
+        result.pop()
+
+    return "\n".join(result)
+
+
+def check_token_limit(output: str, max_tokens: int) -> tuple[str, bool]:
+    """Truncate output exceeding *max_tokens* (~4 chars/token).
+
+    Returns ``(output, was_truncated)``.  When truncated the full output is
+    saved to a temp file and a summary with the file path is returned.
+    """
+    if max_tokens <= 0 or not output:
+        return output, False
+
+    estimated_tokens = len(output) / 4
+    if estimated_tokens <= max_tokens:
+        return output, False
+
+    logs_dir = os.path.join(tempfile.gettempdir(), "stata_cli_logs")
+    os.makedirs(logs_dir, exist_ok=True)
+    timestamp = time.strftime("%Y%m%d_%H%M%S")
+    log_path = os.path.join(logs_dir, f"stata_output_{timestamp}.log")
+
+    try:
+        with open(log_path, "w", encoding="utf-8") as fh:
+            fh.write(output)
+    except OSError:
+        max_chars = max_tokens * 4
+        return output[:max_chars] + f"\n\n... [Output truncated at {max_tokens} tokens]", True
+
+    preview = output[:1000]
+    if len(output) > 1000:
+        preview += "\n... [truncated]"
+    msg = (
+        f"Output exceeded token limit ({int(estimated_tokens)} tokens > {max_tokens} max).\n"
+        f"Full output saved to: {log_path}\n\n"
+        f"--- Preview ---\n{preview}"
+    )
+    return msg, True

stata_cli/smcl_parser.py

@@ -0,0 +1,93 @@
+"""Simplified SMCL-to-plain-text converter for Stata help files."""
+
+import re
+
+_CHAR_CODES = {
+    "S|": "$", "'g": "`", "-(": "{", ")-": "}",
+    "-": "─", "|": "│", "+": "┼",
+    "TT": "┬", "BT": "┴", "LT": "├", "RT": "┤",
+    "TLC": "┌", "TRC": "┐", "BRC": "┘", "BLC": "└",
+    "a'": "á", "e'": "é", "i'": "í", "o'": "ó", "u'": "ú",
+    "n~": "ñ", "ss": "ß", "c,": "ç",
+}
+
+
+def _resolve_char(code: str) -> str:
+    code = code.strip()
+    if code in _CHAR_CODES:
+        return _CHAR_CODES[code]
+    if code.startswith("0x") or code.startswith("0X"):
+        try:
+            return chr(int(code[2:], 16))
+        except (ValueError, OverflowError):
+            return code
+    try:
+        n = int(code)
+        if 1 <= n <= 0x10FFFF:
+            return chr(n)
+    except (ValueError, OverflowError):
+        pass
+    return code
+
+
+# Tags that are simply stripped (content kept)
+_STRIP_TAGS = re.compile(
+    r"\{/?(?:txt|res|err|inp|com|bf|it|sf|ul|smcl|s6hlp|"
+    r"p_end|pstd|phang|pmore|pin|p2colset[^}]*|p2col[^}]*|"
+    r"marker[^}]*|dlgtab[^}]*|synoptset[^}]*|syntab[^}]*|"
+    r"synopt[^}]*|synopthdr[^}]*|"
+    r"col\s+\d+|right|center|break|reset|"
+    r"bind\s+[^}]*)\}"
+)
+
+# {hline} or {hline N} -> dashes
+_HLINE_RE = re.compile(r"\{hline(?:\s+(\d+))?\}")
+
+# {help topic}, {help topic:text}, {manhelp topic section}
+_HELP_RE = re.compile(r"\{(?:help|manhelp)\s+([^}:]+?)(?::([^}]+))?\}")
+
+# {browse "url":text} or {browse "url"}
+_BROWSE_RE = re.compile(r'\{browse\s+"([^"]*)"(?::([^}]+))?\}')
+
+# {cmd:text}, {opt:text}, {hi:text}, {title:text}, {it:text}, {bf:text}
+_STYLED_RE = re.compile(r"\{(?:cmd|opt|hi|title|input|stata)\s*:\s*([^}]*)\}")
+_STYLED2_RE = re.compile(r"\{(?:it|bf|ul)\s*:\s*([^}]*)\}")
+
+# {c CODE}
+_CHAR_RE = re.compile(r"\{c\s+([^}]+)\}")
+
+# {space N}
+_SPACE_RE = re.compile(r"\{space\s+(\d+)\}")
+
+# Catch-all: any remaining {tag ...} or {tag:...}
+_CATCHALL_RE = re.compile(r"\{[a-zA-Z_][^}]*\}")
+
+# SMCL header line
+_SMCL_HEADER_RE = re.compile(r"^\{smcl\}\s*$", re.MULTILINE)
+
+# Star-bang lines in starbang output
+_STARBANG_RE = re.compile(r"^\*!\s?", re.MULTILINE)
+
+# INCLUDE directives (Stata-internal cross-references)
+_INCLUDE_RE = re.compile(r"^INCLUDE\s+help\s+\S+.*$", re.MULTILINE)
+
+
+def smcl_to_text(raw: str) -> str:
+    """Convert SMCL markup to readable plain text."""
+    text = _SMCL_HEADER_RE.sub("", raw)
+    text = _STARBANG_RE.sub("", text)
+    text = _INCLUDE_RE.sub("", text)
+
+    text = _HLINE_RE.sub(lambda m: "-" * int(m.group(1) or 78), text)
+    text = _HELP_RE.sub(lambda m: m.group(2) or m.group(1), text)
+    text = _BROWSE_RE.sub(lambda m: m.group(2) or m.group(1), text)
+    text = _STYLED_RE.sub(r"\1", text)
+    text = _STYLED2_RE.sub(r"\1", text)
+    text = _CHAR_RE.sub(lambda m: _resolve_char(m.group(1)), text)
+    text = _SPACE_RE.sub(lambda m: " " * int(m.group(1)), text)
+    text = _STRIP_TAGS.sub("", text)
+    text = _CATCHALL_RE.sub("", text)
+
+    # Collapse runs of >2 blank lines
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip() + "\n"