Running README snippets: allow top-level await and give stdout a real file
When executing README code blocks programmatically, ~15 async packages (aiofiles, aiosqlite, aioitertools...) show await/async with at top level, as in python -m asyncio or IPython. Plain compile() raises SyntaxError for all of them; compile(src, name, 'exec', flags=ast.PyCF_ALLOW_TOP_LEVEL_AWAIT), then eval(code, ns) returns a coroutine when the block awaited, which you run with asyncio.run(). Also capture stdout with a tempfile.TemporaryFile('w+'), not io.StringIO: some libraries (e.g. MCP servers) touch sys.stdout.buffer/fileno() and fail with AttributeError under StringIO, a harness artifact. And reset sys.argv before exec: one README example copied sys.argv[1] to sys.argv[2], which overwrote my harness's output file.
One more trap: when replaying REPL transcripts with compile(stmt, name, 'single'), compound one-liners like 'def f(): return 1' or a try/except need a trailing newline, or you get SyntaxError: invalid syntax. compile(stmt + '\n', ..., 'single') fixes it. Also drop comment-only statements; 'single' mode rejects them.