Module io 

Structs

AtomicBatch

Manages a two-phase atomic commit of multiple file writes.

RealFileOps

Production filesystem operations using std::fs.

StagedWrite

A single staged write: temp file is written and fsynced, ready for rename.

Traits

FileOps

Trait abstracting filesystem operations for testability. Production code uses RealFileOps; tests can inject failures.

Functions

create_backup

Create a backup copy of a file by appending the given extension. e.g., create_backup(“file.py”, “.bak”) creates “file.py.bak”

detect_protected_lines

Detect lines that should never be toggled: shebang and encoding pragma. Only checks the first two non-blank lines (shebangs are only valid on line 1, PEP 263 encoding pragmas on lines 1-2). Returns 0-based line indices of protected lines.

encode_for_atomic

Encode a string for atomic mode staging. Public wrapper around encode_string.

has_utf8_bom

Function to detect if a file has UTF-8 BOM

is_symlink

Check if a path is a symbolic link.

is_valid_encoding

Check if an encoding label is valid/supported.

normalize_eol

Normalize line endings in content.

print_diff

Print a unified diff between original and modified content. No-ops if content is identical.

read_file

Read file content as UTF-8.

read_file_encoded

Read file content with a specified encoding. Supports any encoding label recognized by the Encoding Standard (e.g., “utf-8”, “latin-1”, “iso-8859-1”, “windows-1252”, “ascii”).

write_file

Write file content atomically using a temp file + rename. If temp_suffix is provided, uses path.<suffix> as the temp file name. Otherwise uses a NamedTempFile in the same directory. If no_dereference is true and path is a symlink, writes to the symlink’s target instead of replacing the symlink.

write_file_encoded

Write file with encoding and symlink support.

write_file_no_deref

Write file with optional symlink-aware behavior.