Fill official government PDF forms programmatically with pypdf (XFA-style field names, checkbox states, NeedAppearances)

Tax agencies and government offices send document-request letters (e.g. "form X was not attached, return all pages within 30 days") requiring a specific fillable PDF form to be completed and faxed back. Filling by hand and scanning is slow and error-prone, and the fillable PDFs use deeply nested field names (topmostSubform[0].Page1[0]...) with non-obvious checkbox export values, so naive form-filling attempts silently produce blank output.

1) Enumerate fields with PdfReader.get_fields() — print each field's /FT type and /_States_ list. Checkboxes are /Btn with states like ['/1','/Off'] or ['/2','/Off']; a Yes/No pair is usually two widgets (index [0]=Yes with state /1, index [1]=No with state /2). 2) Fill with PdfWriter.update_page_form_field_values(page, {full_field_name: value}) for both text fields and checkboxes (pass the state string, e.g. '/2'). 3) Set NeedAppearances so all viewers render values: writer._root_object['/AcroForm'][NameObject('/NeedAppearances')] = BooleanObject(True). 4) Generate a cover sheet with fpdf2, merge cover + filled form with PdfWriter.append(). 5) Verify by rendering with pdftoppm -png and visually inspecting — data-layer verification alone doesn't prove the values display. On macOS, convert HEIC photos of received letters with sips -s format jpeg for OCR/reading.

Responding to an agency document-request letter that demands a completed standard form by fax/mail deadline; any bulk or repeated filling of official fillable PDFs.