feat(test-programs): add py_checklist py_console_logs py_sudoku_solver

Author: Franz-Fischbach

.agents/codebase-insights.txt

@@ -23,3 +23,4 @@
 - `ct record` now prefers `CODETRACER_PYTHON_INTERPRETER`, `PYTHON_EXECUTABLE`, `PYTHONEXECUTABLE`, or PATH resolution to locate the Python runtime before delegating to the db backend, and `db-backend-record` expects the resolved interpreter via `--python-interpreter` when launching the recorder.
 - `ct record` resolves Python via env vars (`CODETRACER_PYTHON_INTERPRETER`, `PYTHON_EXECUTABLE`, `PYTHONEXECUTABLE`, `PYTHON`) before checking PATH. When falling back to PATH we now call `findExe(..., followSymlinks=false)` so virtualenv launchers keep their original location and `pyvenv.cfg` remains discoverable.
 - `ct record` verifies that `codetracer_python_recorder` is importable before launching the db backend and prints actionable guidance if the module is missing or broken.
+- Sudoku test-program datasets include intentionally invalid boards (e.g., examples #3 and #6) with duplicate digits inside a sub-grid; solvers should detect and report these gracefully.

test-programs/py_checklist/README.md

@@ -0,0 +1,82 @@
+# Python Checklist Test Programs
+
+This suite mirrors the `ruby_checklist` sample by collecting small,
+targeted probes that exercise diverse areas of the Python language and
+standard library. The code is intentionally verbose and heavily
+commented so that engineers working across multiple languages can
+quickly understand what a probe demonstrates and why it matters.
+
+## Goals
+
+- Capture representative call stacks for critical Python features so the
+  debugger and tracer integrations can be validated.
+- Provide ready-made snippets that illustrate specific language
+  behaviors, pitfalls, and idioms for reference during development.
+- Keep each probe independent and side-effect light so they can run in
+  isolation without hidden dependencies.
+
+## Organization
+
+- Minimum Python version: **3.11**. This allows us to cover structural
+  pattern matching, `except*` for exception groups, and other
+  post-3.10 features without fallbacks.
+- Each feature cluster lives in its own module (for example,
+  `basics.py`, `functions_exceptions.py`, …). Modules should export
+  numbered `demo_*` functions that focus on a single behavior.
+- A top-level `run_all()` function inside each module executes its demos
+  sequentially, printing numbered lines so missed events are easy to
+  spot in traces.
+- Inline comments and docstrings must explain **what** the snippet does,
+  **why** someone would use it, and any common gotchas.
+- Helpers that spin up threads or processes must protect their entry
+  points with `if __name__ == "__main__":` to stay portable across
+  platforms (especially Windows).
+
+## Feature Coverage
+
+| Area | Modules / Demos | Notes |
+| --- | --- | --- |
+| Literals, operators, control flow | `basics.run_all()` | Covers literals, slicing, unpacking, match/case, loop `else`. |
+| Functions, decorators, exceptions | `functions_exceptions.run_all()` | Demonstrates call signatures, mutable defaults, closures, decorator stacking, caching, chained exceptions, `ExceptionGroup`. |
+| Context managers & iterators | `contexts_iterators.run_all()` | Custom `__enter__/__exit__`, `contextlib`, iterator protocol, generators with `send`/`throw`/`close`. |
+| Async & concurrency | `async_concurrency.run_all()` | Async context/iter, `create_task`, contextvars, threading/TLS, `ThreadPoolExecutor`, guarded multiprocessing. |
+| Data model & classes | `data_model.run_all()` | `__repr__`, formatting, rich ops, properties with `__slots__`, attribute hooks, descriptors, subclass hooks, metaclass lifecycle. |
+| Collections & dataclasses | `collections_dataclasses.run_all()` | Dataclasses with slots/order, enums and flags, namedtuple/deque/defaultdict/Counter, mapping proxy, pattern matching with `__match_args__`. |
+| System utilities | `system_utils.run_all()` | `subprocess.run` with env overrides, tz-aware datetime math, `Decimal`/`Fraction`, deterministic random, regex capture groups. |
+| Introspection & dynamic code | `introspection.run_all()` | `inspect.signature`, dynamic attributes, globals/locals snapshots, `eval`/`exec`/`compile`, AST parse/dump (with security notes in comments). |
+| Import system | `imports_demo.run_all()` | Runtime module creation via `types.ModuleType`, adjusting `sys.path`, `importlib.import_module`, `__all__`, module caching notes. |
+| Logging, warnings, GC, typing | `advanced_runtime.run_all()` | Scoped logging config, forced warnings, GC cycle collection with weakrefs/finalizers, runtime protocol checks, generics. |
+| Miscellaneous constructs | `miscellaneous.run_all()` | `iter(callable, sentinel)`, `del`, custom mapping protocol, context manager without suppression. |
+
+> **Planned additions:** Remaining entries from the original checklist
+> (I/O & serialization, subprocess variants, JSON/pickle, etc.) can be
+> layered in by following the same pattern—add `<topic>.py`, expose
+> `run_all()`, then register it in `__main__.py`.
+
+## Running The Suite
+
+Once all modules are implemented, you will be able to run the entire
+checklist from the project root:
+
+```bash
+python -m test-programs.python_checklist
+```
+
+During early development, it is fine to run individual modules directly
+with `python test-programs/python_checklist/<module>.py` to iterate on a
+specific feature cluster.
+
+## Contribution Guidelines
+
+- Follow the numbering scheme diligently so console output gaps surface
+  immediately.
+- Prefer deterministic behavior (avoid randomness unless the purpose is
+  to exercise the random module).
+- Clean up temporary files, subprocesses, and other resources within the
+  probe itself. Each demo should leave the environment in the same state
+  it found it.
+- If a snippet showcases risky behavior (e.g., `eval`), highlight the
+  security implications in comments.
+
+This structure keeps the checklist maintainable and allows future
+contributors to plug in additional probes without surprising teammates.

test-programs/py_checklist/__main__.py

@@ -0,0 +1,50 @@
+"""Entry point for the Python checklist test suite.
+
+Running ``python -m test-programs.py_checklist`` executes every module's
+``run_all`` function in a stable order. Each module prints numbered lines, so
+missing console events are immediately obvious when reviewing traces.
+
+To add a new probe:
+1. Create ``<topic>.py`` with numbered ``demo_*`` functions and a ``run_all``.
+2. Import ``run_all`` here and append it to ``MODULES``.
+3. Ensure any platform-specific code (e.g., multiprocessing) stays guarded by
+   ``if __name__ == "__main__"`` inside the module itself.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Callable
+
+
+MODULES: list[tuple[str, Callable[[], None]]] = []
+
+def register(module_name: str) -> None:
+    module = import_module(f"test-programs.py_checklist.{module_name}")
+    MODULES.append((module_name, module.run_all))
+
+
+for name in [
+    "basics",
+    "functions_exceptions",
+    "contexts_iterators",
+    "async_concurrency",
+    "data_model",
+    "collections_dataclasses",
+    "system_utils",
+    "introspection",
+    "imports_demo",
+    "advanced_runtime",
+    "miscellaneous",
+]:
+    register(name)
+
+
+def main() -> None:
+    for name, runner in MODULES:
+        print(f"== Running {name} ==")
+        runner()
+
+
+if __name__ == "__main__":
+    main()

test-programs/py_checklist/advanced_runtime.py

@@ -0,0 +1,108 @@
+"""Runtime-related probes: logging, warnings, GC, weakrefs, typing."""
+
+from __future__ import annotations
+
+import gc
+import logging
+import warnings
+import weakref
+from typing import Generic, Literal, Protocol, TypeAlias, TypedDict, TypeVar, runtime_checkable
+
+
+def demo_1_logging_warnings() -> None:
+    """Configure a module-scoped logger and emit a warning.
+
+    Logging is often customized per subsystem, so we avoid modifying the
+    global root logger. Warnings are promoted so that traces capture them.
+    """
+
+    logger = logging.getLogger("python_checklist.advanced")
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("LOG:%(levelname)s:%(message)s"))
+        logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+    logger.propagate = False
+
+    logger.info("1a. logging info message")
+
+    warnings.simplefilter("always", ResourceWarning)
+    warnings.warn("1b. sample resource warning", ResourceWarning)
+
+    print("1. logging/warnings: configured")
+
+
+def demo_2_gc_weakrefs() -> None:
+    """Show garbage collection handling cycles and weak references."""
+
+    class Node:
+        def __init__(self, name: str) -> None:
+            self.name = name
+            self.ref: "Node | None" = None
+
+        def __repr__(self) -> str:
+            return f"Node({self.name})"
+
+    node_a = Node("A")
+    node_b = Node("B")
+    node_a.ref = node_b
+    node_b.ref = node_a  # create a reference cycle.
+
+    weak_a = weakref.ref(node_a)
+    finalizer = weakref.finalize(
+        node_b,
+        lambda name=node_b.name: print(f"2b. finalize called for Node {name}"),
+    )
+
+    del node_a
+    del node_b
+    collected = gc.collect()
+    weak_alive = weak_a() is not None
+
+    print(
+        "2. gc/weakref:",
+        {"collected": collected, "weak_alive": weak_alive, "finalizer_alive": finalizer.alive},
+    )
+
+
+def demo_3_typing_runtime() -> None:
+    """Runtime checks for typing constructs; useful for validation."""
+
+    UserId: TypeAlias = int
+    Mode = Literal["r", "w"]
+
+    class User(TypedDict):
+        id: UserId
+        name: str
+
+    @runtime_checkable
+    class Greeter(Protocol):
+        def greet(self) -> str:
+            ...
+
+    class Impl:
+        def greet(self) -> str:
+            return "hello"
+
+    T = TypeVar("T")
+
+    class Box(Generic[T]):
+        def __init__(self, value: T, mode: Mode = "r") -> None:
+            self.value = value
+            self.mode = mode
+
+    user: User = {"id": 7, "name": "Ada"}
+    greeter_ok = isinstance(Impl(), Greeter)
+    boxed = Box(user, mode="w")
+    print("3. typing:", user, greeter_ok, boxed.mode)
+
+
+def run_all() -> None:
+    """Execute advanced runtime demonstrations."""
+    demo_1_logging_warnings()
+    demo_2_gc_weakrefs()
+    demo_3_typing_runtime()
+
+
+if __name__ == "__main__":
+    run_all()

test-programs/py_checklist/async_concurrency.py

@@ -0,0 +1,123 @@
+"""Asyncio, threading, futures, and multiprocessing probes."""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import multiprocessing as mp
+import os
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, List
+
+
+async def demo_1_async_primitives() -> None:
+    """Exercise async context managers, async iterators, and tasks."""
+
+    class AsyncContext:
+        async def __aenter__(self) -> "AsyncContext":
+            print("1. async-context: enter")
+            return self
+
+        async def __aexit__(self, exc_type, exc, tb) -> bool:
+            print("1. async-context: exit", exc_type.__name__ if exc_type else None)
+            return False  # do not suppress errors.
+
+    class AsyncIter:
+        def __init__(self) -> None:
+            self.n = 0
+
+        def __aiter__(self) -> "AsyncIter":
+            return self
+
+        async def __anext__(self) -> int:
+            await asyncio.sleep(0)
+            if self.n >= 2:
+                raise StopAsyncIteration
+            self.n += 1
+            return self.n
+
+    async with AsyncContext():
+        async for value in AsyncIter():
+            print("1a. async-iter:", value)
+
+    async def compute() -> int:
+        await asyncio.sleep(0)
+        return 42
+
+    task = asyncio.create_task(compute())
+    print("1b. task result:", await task)
+
+
+def demo_2_contextvars() -> None:
+    """Context variables isolate async task state."""
+    var = contextvars.ContextVar("counter", default=0)
+
+    def bump() -> int:
+        var.set(var.get() + 1)
+        return var.get()
+
+    values = [bump(), bump()]
+    print("2. contextvars:", values)
+
+
+def demo_3_threads() -> None:
+    """Threads with locks and thread-local storage."""
+    lock = threading.Lock()
+    counter = 0
+    tls = threading.local()
+
+    def worker(name: str) -> None:
+        nonlocal counter
+        tls.calls = getattr(tls, "calls", 0) + 1
+        for _ in range(100):
+            with lock:
+                counter += 1
+        print(f"3. thread {name}: tls.calls={tls.calls}")
+
+    threads = [threading.Thread(target=worker, args=(f"t{i}",)) for i in range(2)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+    print("3b. threads counter:", counter)
+
+
+def demo_4_thread_pool() -> None:
+    """Use concurrent.futures ThreadPoolExecutor."""
+    with ThreadPoolExecutor(max_workers=2) as executor:
+        future = executor.submit(sum, [1, 2, 3])
+        print("4. thread-pool result:", future.result())
+
+
+def child_process(queue: mp.Queue) -> None:
+    """Child process used by demo_5_multiprocessing."""
+    queue.put(("pid", os.getpid()))
+
+
+def demo_5_multiprocessing() -> None:
+    """Start a process; guard with __name__ check for Windows safety."""
+    queue: mp.Queue[Any] = mp.Queue()
+    process = mp.Process(target=child_process, args=(queue,))
+    process.start()
+    message = queue.get()
+    process.join()
+    print("5. multiprocessing:", message)
+
+
+def run_all() -> None:
+    """Run all async/concurrency demos; skip multiprocessing if imported."""
+    asyncio.run(demo_1_async_primitives())
+    demo_2_contextvars()
+    demo_3_threads()
+    demo_4_thread_pool()
+    if __name__ == "__main__":
+        # On Windows, the spawn start method re-imports modules, so we only
+        # launch child processes when the module is the main entry point.
+        demo_5_multiprocessing()
+    else:
+        print("5. multiprocessing: skipped (imported module)")
+
+
+if __name__ == "__main__":
+    run_all()