Make python module accept io-capture args

README.md: 
codetracer-python-recorder/codetracer_python_recorder/cli.py: 
codetracer-python-recorder/tests/python/unit/test_cli.py: 
examples/README.md: 
examples/io_capture.py: 
examples/stdin_capture.py: 

Signed-off-by: Tzanko Matev <[email protected]>

Author: tzanko-matev

README.md

@@ -48,6 +48,14 @@ All subclasses carry the same attributes, so existing handlers can migrate by ca
 
 Pass `--codetracer-json-errors` (or set the policy via `configure_policy(json_errors=True)`) to stream a one-line JSON trailer on stderr. The payload includes `run_id`, `trace_id`, `error_code`, `error_kind`, `message`, and the `context` map so downstream tooling can log failures without scraping text.
 
+### IO capture configuration
+
+Line-aware stdout/stderr capture proxies are now enabled by default. Control them through the policy layer:
+
+- CLI: `python -m codetracer_python_recorder --io-capture=off script.py` disables capture, while `--io-capture=proxies+fd` also mirrors raw file-descriptor writes.
+- Python: `configure_policy(io_capture_line_proxies=False)` toggles proxies, and `configure_policy(io_capture_fd_fallback=True)` enables the FD fallback.
+- Environment: set `CODETRACER_CAPTURE_IO=off`, `proxies`, or `proxies,fd` to match the CLI and Python helpers.
+
 ### Migration checklist for downstream tools
 
 - Catch `RecorderError` (or a subclass) instead of `RuntimeError`.

codetracer-python-recorder/codetracer_python_recorder/cli.py

@@ -97,6 +97,15 @@ def _parse_args(argv: Sequence[str]) -> RecorderCLIConfig:
         action="store_true",
         help="Emit JSON error trailers on stderr.",
     )
+    parser.add_argument(
+        "--io-capture",
+        choices=["off", "proxies", "proxies+fd"],
+        help=(
+            "Control stdout/stderr capture. Without this flag, line-aware proxies stay enabled. "
+            "'off' disables capture, 'proxies' forces proxies without FD mirroring, "
+            "'proxies+fd' also mirrors raw file-descriptor writes."
+        ),
+    )
 
     known, remainder = parser.parse_known_args(argv)
     pending: list[str] = list(remainder)
@@ -145,6 +154,19 @@ def _parse_args(argv: Sequence[str]) -> RecorderCLIConfig:
         policy["log_file"] = Path(known.log_file).expanduser().resolve()
     if known.json_errors:
         policy["json_errors"] = True
+    if known.io_capture:
+        match known.io_capture:
+            case "off":
+                policy["io_capture_line_proxies"] = False
+                policy["io_capture_fd_fallback"] = False
+            case "proxies":
+                policy["io_capture_line_proxies"] = True
+                policy["io_capture_fd_fallback"] = False
+            case "proxies+fd":
+                policy["io_capture_line_proxies"] = True
+                policy["io_capture_fd_fallback"] = True
+            case other:  # pragma: no cover - argparse choices block this
+                parser.error(f"unsupported io-capture mode '{other}'")
 
     return RecorderCLIConfig(
         trace_dir=trace_dir,

codetracer-python-recorder/tests/python/unit/test_cli.py

@@ -96,3 +96,39 @@ def test_parse_args_collects_policy_overrides(tmp_path: Path) -> None:
         "log_file": (tmp_path / "logs" / "recorder.log").resolve(),
         "json_errors": True,
     }
+
+
+def test_parse_args_controls_io_capture(tmp_path: Path) -> None:
+    script = tmp_path / "entry.py"
+    _write_script(script)
+
+    config = _parse_args(
+        [
+            "--io-capture",
+            "off",
+            str(script),
+        ]
+    )
+
+    assert config.policy_overrides == {
+        "io_capture_line_proxies": False,
+        "io_capture_fd_fallback": False,
+    }
+
+
+def test_parse_args_enables_io_capture_fd_mirroring(tmp_path: Path) -> None:
+    script = tmp_path / "entry.py"
+    _write_script(script)
+
+    config = _parse_args(
+        [
+            "--io-capture",
+            "proxies+fd",
+            str(script),
+        ]
+    )
+
+    assert config.policy_overrides == {
+        "io_capture_line_proxies": True,
+        "io_capture_fd_fallback": True,
+    }

examples/README.md

@@ -13,7 +13,9 @@ Scripts
 - generators_async.py: A generator, async function, and async generator.
 - context_and_closures.py: A context manager and a nested closure.
 - threading.py: Two threads invoking traced functions and joining.
-- imports_side_effects.py: Module‑level side effects vs main guard.
+- imports_side_effects.py: Module-level side effects vs main guard.
 - kwargs_nested.py: Nested kwargs structure to validate structured encoding.
+- io_capture.py: Mix of print/write/os.write to validate IO capture proxies.
+- stdin_capture.py: Reads piped stdin via input(), readline(), read().
 
 All scripts are deterministic and print minimal output.

examples/io_capture.py

@@ -0,0 +1,30 @@
+"""Exercise IO capture proxies with mixed stdout/stderr writes."""
+from __future__ import annotations
+
+import os
+import sys
+
+
+def emit_high_level() -> None:
+    print("stdout via print()", flush=True)
+    sys.stdout.write("stdout via sys.stdout.write()\n")
+    sys.stdout.flush()
+
+    sys.stderr.write("stderr via sys.stderr.write()\n")
+    sys.stderr.flush()
+
+
+def emit_low_level() -> None:
+    os.write(1, b"stdout via os.write()\n")
+    os.write(2, b"stderr via os.write()\n")
+
+
+def main() -> None:
+    print("Demonstrating Codetracer IO capture behaviour")
+    emit_high_level()
+    emit_low_level()
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()

examples/stdin_capture.py

@@ -0,0 +1,43 @@
+"""Exercise stdin capture with sequential reads."""
+from __future__ import annotations
+
+import sys
+
+
+def _describe(label: str, value: str | None) -> None:
+    if value is None:
+        print(f"{label}: <EOF>")
+    elif value == "":
+        print(f"{label}: <empty string>")
+    else:
+        print(f"{label}: {value!r}")
+
+
+def main() -> None:
+    if sys.stdin.isatty():
+        print("stdin is attached to a TTY; pipe data to exercise capture.")
+        print(
+            "Example: printf 'first\\nsecond\\nthird' | "
+            "python -m codetracer_python_recorder examples/stdin_capture.py"
+        )
+        return
+
+    print("Inspecting stdin via input()/readline()/read()")
+
+    try:
+        first = input()
+    except EOFError:
+        first = None
+    _describe("input()", first)
+
+    second = sys.stdin.readline()
+    _describe("sys.stdin.readline()", second if second else None)
+
+    remaining = sys.stdin.read()
+    _describe("sys.stdin.read()", remaining if remaining else None)
+
+    print("Done reading from stdin.")
+
+
+if __name__ == "__main__":
+    main()