CONVERSION REFERENCE

File I/O and C ABI

The active converter includes one closed, synchronous profile for bounded whole-file UTF-8 reads and exact UTF-8 writes.

Exact context form

with open(path, 'r', encoding='utf-8', newline='') as handle:
    ...

Each session is one direct, one-item with statement inside a top-level function. open is the unshadowed built-in and the handle is a fresh direct name. Mode is literal 'r' or 'w', encoding is exactly literal 'utf-8', and newline is exactly literal ''. Multiple sessions may occur sequentially when each has a closed one-operation lifecycle and request limits permit them.

Whole-file read

def load(path: str) -> str:
    with open(path, 'r', encoding='utf-8', newline='') as handle:
        return handle.read()

Alternatively, assign zero-argument read() to one fresh direct local, leave the context, and immediately return that value:

def load_named(path: str) -> str:
    with open(path, 'r', encoding='utf-8', newline='') as handle:
        content = handle.read()
    return content

• Default maximum: 1,048,576 bytes (1 MiB). Trusted hard ceiling: 16,777,216 bytes (16 MiB).
• The complete byte stream must be RFC 3629 UTF-8 and contain no embedded NUL.
• The helper closes exactly once and transfers the unique allocation only after a successful close.
• The assigned-read local cannot rebind a parameter or earlier local, be aliased, be observed before transfer, or escape another way.

Exact write

def save(path: str, text: str) -> int:
    with open(path, 'w', encoding='utf-8', newline='') as handle:
        handle.write(text)
    return 0

The operand is one already-proved direct string name or a NUL-free string literal. The Python character-count result is deliberately discarded. Generated C writes the exact UTF-8 byte count, borrows the text, closes exactly once, and reports write or close failure.

Composed and sequential sessions

def save_two(first: str, second: str, text: str) -> int:
    with open(first, 'w', encoding='utf-8', newline='') as left:
        left.write(text)
    with open(second, 'w', encoding='utf-8', newline='') as right:
        right.write(text)
    return 0

Closed file sessions compose with ordinary supported control flow before or after them. A file with statement itself remains a direct function-body statement; it is not nested under a conditional or loop.

Rejected file shapes

• Append, update, binary, or implicit modes and options; missing or different encoding/newline; multiple context items.
• Two operations in one session, partial or sized reads, readline, seeking, handle iteration, or general file-object behavior.
• A call or other effectful write operand. Compute it in an earlier statement and write its proved direct string name.
• Handle aliasing, rebinding, escape, explicit close(), return, post-region use, or a nested-control-flow session.
• Using the read value outside the exact transfer forms, or calling a source-defined file-effect function from transpiled Python.

Generated-C status ABI

Every generated file-effect entry point receives one additional final int64_t *pycf_status parameter. It is hidden from Python, required, non-null, writable, and points to storage owned by the external C caller. The entry null-guards it, initializes it to 0 before source-controlled work, and helpers overwrite it on failure.

The registered helper identities are pycf.file.read_all_utf8_bounded@1.0.0 and pycf.file.write_utf8_exact@1.0.0. Generated symbols are pycf_file_read_all_utf8_bounded_v1 and pycf_file_write_utf8_exact_v1.

External C caller contract

• Pass a non-null, NUL-terminated, valid UTF-8 path C string.
• Write text is borrowed, non-null, NUL-terminated valid UTF-8 with no embedded NUL.
• On read success, returned char * is a unique malloc-owned buffer. The caller releases it exactly once with free.
• On failure, the helper retains or frees any allocation and publishes status.