Contact CSV Notes: preserve line breaks before counting records

Start with the main Google Contacts preparation guide [current article] for that product’s template and preflight. This supplemental case uses a generic six-field schema, not product-mapped headings. Phone strings are fictional and must not be dialed. Its question is whether a local preprocessing step preserved the contact’s Notes text—not whether an import succeeded.

Keep the original text before parsing

Python’s csv documentation, Reader Objects and newline footnote distinguishes source lines from returned records. Use explicit encoding, dialect and newline-preserving input. RFC 4180, section 2 items 6–7 describes quoted line breaks and escaped quotes; it is informational, not a universal importer contract.

Our baseline has three contacts across six physical lines. Parsing the unchanged text through io.StringIO(text, newline="") preserved all eighteen fields. Passing text.splitlines() to the same parser still returned three contacts, but changed Zoë’s Notes from First line, quoted\r\nSecond line to First line, quotedSecond line, and René’s from Alpha\r\nBeta to AlphaBeta. The comma, Unicode and other strings survived. A correct contact count therefore missed actual text loss.

Keep the original file unchanged. Count parsed records after the declared header, then compare every intended field against its declared source value. A mismatch means inspect the preprocessing and retain the original—not erase the line break to make a check pass. Unknown original values cannot be reconstructed by this fixture. Resolve the destination’s documented schema separately before any later authorized import.

Reproduce the exact local comparison

In a new empty directory, save the four named input/code fences as UTF-8 without BOM, LF endings and one final LF. With CPython 3.12.3, run:

python3 make_fixture.py
python3 check.py

The generator creates contacts.csv; the checker creates observed.json. Repeating replaces those two local files. Neither script uses a network or a contact product. Delete the isolated directory for local cleanup.

The 301-byte baseline has SHA-256 b55fa9a28a7b19e1ea0790a00dcac9151c7719b3d78ea9f348e3e068beb4ab56. The declared baseline and fifteen case outcomes matched on 2026-10-05T13:32:17.345699Z, exit 0. The exact eighteen baseline strings, changed Notes and per-case results are in author-run.json below. On replay, your observation timestamp changes; compare fields/outcomes and baseline bytes, not that timestamp.

The checks also exercise preserving splitlines(keepends=True), LF input, an ordinary single-line control and escaped quotes; changed Notes, lost postal zeroes, a renamed heading, surplus field, missing record, invalid UTF-8, BOM and unfinished quote fail this case’s expectations. Some rejected changes remain parseable CSV. These are fixture-specific checks, not universal CSV validation or product acceptance tests.

Evidence and limits

The code, fictional data and measured outputs are original local evidence, separate from source-derived API/format guidance. Source pages checked 2026-10-05T13:32:18Z; the Python page is documentation 3.12.15 (updated October 1, 2026, 15:25 UTC), distinct from the executed 3.12.3 runtime. RFC 4180 is dated October 2005. No real contacts, spreadsheet save, account, import/export, duplicate retry, synchronization or external action was tested. A distinct checker under the same operator read the sources at 2026-10-05T13:34:12Z, independently replayed the exact public files on CPython 3.12.3 at 2026-10-05T13:39:32.678064Z, and checked nine additional executable cases and sixteen reader decisions by 2026-10-05T13:40:56Z. These internal checks supply no independent formal coverage. Recheck before adaptation or changed runtime/dialect/source, on reported mismatch, and by 2026-11-05T00:00:00Z. Feedback should name the exact revision and affected field without private contact values. Format: contact portability standard [current article].

Exact case profile

{
  "schema": "contact-import-case-v1",
  "tags": [
    "contacts",
    "csv",
    "portability"
  ],
  "source_format": "Generic six-field fictional CSV; not a Google/Outlook template or actual product export",
  "target_product": "Local CSV preservation check; target contact product unspecified and untested",
  "target_client_version": "CPython 3.12.3; product client/version unknown",
  "official_template_url": null,
  "template_checked_at": null,
  "header_row": [
    "Name",
    "PrimaryEmail",
    "AlternateEmail",
    "Phone",
    "Postal",
    "Notes"
  ],
  "encoding": "UTF-8 without BOM",
  "delimiter": ",",
  "newline_style": "Baseline record endings and embedded Notes breaks are CRLF; separate LF variant exercised",
  "fixture": {
    "locator": "Complete fixture.json and generator below",
    "files": [
      {
        "filename": "fixture.json",
        "representation": "UTF-8 without BOM; LF and one final LF",
        "bytes": 574,
        "sha256": "37ea2a3f88d5952f959c006f7dde73f9cb3aef1fb7b69ae60f6d6048a765bdfd",
        "locator": "Complete named fence below"
      },
      {
        "filename": "make_fixture.py",
        "representation": "UTF-8 without BOM; LF and one final LF",
        "bytes": 641,
        "sha256": "8cf6bcf665a27f9776daac63009d83536de640243e02fe93ee94764564f94a1e",
        "locator": "Complete named fence below"
      },
      {
        "filename": "expected.json",
        "representation": "UTF-8 without BOM; LF and one final LF",
        "bytes": 816,
        "sha256": "d68a1c9ac01f25838071f4df6a1c3b2f893f227f63c9fa7d0026af2ce51feb90",
        "locator": "Complete named fence below"
      },
      {
        "filename": "check.py",
        "representation": "UTF-8 without BOM; LF and one final LF",
        "bytes": 5644,
        "sha256": "85c9b2d8ed0525589777dd82cf8b71b485d13c6459980c8acbdacd8157db1a26",
        "locator": "Complete named fence below"
      },
      {
        "filename": "contacts.csv",
        "representation": "Generated UTF-8 without BOM; comma; minimal double-quote quoting; CRLF including final CRLF and embedded Notes CRLF",
        "bytes": 301,
        "sha256": "b55fa9a28a7b19e1ea0790a00dcac9151c7719b3d78ea9f348e3e068beb4ab56",
        "locator": "Generated by complete make_fixture.py and fixture.json"
      },
      {
        "filename": "author-run.json",
        "representation": "UTF-8 without BOM; indented JSON; LF and final LF; frozen author observation, distinct from newly generated observed.json",
        "bytes": 6686,
        "sha256": "675651d71af3f6c05b67a9ba2f20aa1c934358473d0e862a736ca173dcd50c06",
        "locator": "Complete frozen author-run.json fence below"
      }
    ],
    "commands": [
      "python3 make_fixture.py",
      "python3 check.py"
    ],
    "side_effects": "Creates/replaces contacts.csv and observed.json in the selected empty local directory; no network or accounts"
  },
  "field_mapping": {
    "Name": {
      "local_position": 0,
      "desired_value": "Exact string in fixture.json rows",
      "product_mapping": "unknown; no product schema or importer tested"
    },
    "PrimaryEmail": {
      "local_position": 1,
      "desired_value": "Exact string in fixture.json rows",
      "product_mapping": "unknown; no product schema or importer tested"
    },
    "AlternateEmail": {
      "local_position": 2,
      "desired_value": "Exact string in fixture.json rows",
      "product_mapping": "unknown; no product schema or importer tested"
    },
    "Phone": {
      "local_position": 3,
      "desired_value": "Exact string in fixture.json rows",
      "product_mapping": "unknown; no product schema or importer tested"
    },
    "Postal": {
      "local_position": 4,
      "desired_value": "Exact string in fixture.json rows",
      "product_mapping": "unknown; no product schema or importer tested"
    },
    "Notes": {
      "local_position": 5,
      "desired_value": "Exact string in fixture.json rows",
      "product_mapping": "unknown; no product schema or importer tested"
    }
  },
  "expected_record_count": 3,
  "expected_fields": {
    "locator": "Every value in complete fixture.json rows; expected.json separately declares baseline/count and 15 variant outcomes",
    "status": "Declared expectation, not independently measured product fields"
  },
  "observed_fields": {
    "locator": "All18 baseline fields and all 18 splitlines fields in complete author-run.json below",
    "baseline_all_fields_match": true,
    "splitlines_notes_mismatch": true,
    "fixture_sha256": "b55fa9a28a7b19e1ea0790a00dcac9151c7719b3d78ea9f348e3e068beb4ab56",
    "records": 3,
    "physical_lines_consumed": 6,
    "actual_run_utc": "2026-10-05T13:32:17.345699Z",
    "runtime": "CPython 3.12.3",
    "exit_code": 0
  },
  "duplicates_and_retry_behavior": {
    "local": "No deduplication, identity matching or merge; exact declared three-row profile",
    "target": "Unknown; no account import/retry"
  },
  "test_status": "parser-reproduced",
  "rollback": "Delete only the separate fictional reproduction directory. No product/account changes to undo.",
  "limitations": [
    "Generic headings do not establish Google or Outlook field mapping.",
    "A successful count/parse does not establish complete field preservation.",
    "Specific expected values are required to detect silent valid-CSV changes; arbitrary original values cannot be inferred.",
    "No spreadsheet rendering/save, product import/export, sync, duplicate/retry or lossless migration result.",
    "Strict/profile rejection here is not a product importer rejection.",
    "LF variant is a Python observation, not universal RFC or product compatibility."
  ],
  "refresh_policy": "Recheck before adaptation, changed runtime/dialect/template or reported mismatch; refresh by 2026-11-05T00:00:00Z",
  "primary_source_checks": {
    "checked_at": "2026-10-05T13:32:18Z",
    "python_documentation": "3.12.15 documentation; published update October 1, 2026 15:25UTC; runtime distinct 3.12.3",
    "rfc4180": "Informational October 2005, not universal Internet standard"
  }
}

fixture.json

{
  "header": [
    "Name",
    "PrimaryEmail",
    "AlternateEmail",
    "Phone",
    "Postal",
    "Notes"
  ],
  "rows": [
    [
      "Zoë Example",
      "zoe@example.org",
      "zoe.alt@example.org",
      "0000000001",
      "00123",
      "First line, quoted\r\nSecond line"
    ],
    [
      "René Example",
      "rene@example.org",
      "",
      "0000000002",
      "00007",
      "Alpha\r\nBeta"
    ],
    [
      "Maya Example",
      "maya@example.org",
      "maya.alt@example.org",
      "0000000003",
      "01234",
      "Ordinary note"
    ]
  ]
}

make_fixture.py

"""Generate one public fictional CSV; no network or contact-product calls."""
import csv
import io
import json
from pathlib import Path


def encode(header, rows, ending="\r\n"):
    stream = io.StringIO(newline="")
    csv.writer(stream, dialect="excel", delimiter=",", quotechar='"',
               doublequote=True, quoting=csv.QUOTE_MINIMAL,
               lineterminator=ending).writerows([header, *rows])
    return stream.getvalue().encode("utf-8")


if __name__ == "__main__":
    fixture = json.loads(Path("fixture.json").read_text(encoding="utf-8"))
    Path("contacts.csv").write_bytes(encode(fixture["header"], fixture["rows"]))

expected.json

{
  "baseline": {
    "bytes": 301,
    "sha256": "b55fa9a28a7b19e1ea0790a00dcac9151c7719b3d78ea9f348e3e068beb4ab56",
    "records": 3,
    "physical_lines": 6,
    "split_records": 3,
    "split_physical_lines": 6,
    "split_notes": [
      "First line, quotedSecond line",
      "AlphaBeta",
      "Ordinary note"
    ],
    "roundtrip_equal": true
  },
  "cases": {
    "baseline-preserved": true,
    "splitlines-loss": false,
    "splitlines-keepends": true,
    "lf-preserved": true,
    "lf-splitlines-loss": false,
    "ordinary-split-control": true,
    "escaped-quote-comma": true,
    "changed-note": false,
    "lost-postal-zero": false,
    "renamed-header": false,
    "extra-field": false,
    "missing-record": false,
    "invalid-utf8": false,
    "bom": false,
    "unfinished-quote": false
  }
}

check.py

"""Bounded local CSV case: compare declared fields, not a product importer."""
import csv
import datetime
import hashlib
import io
import json
import platform
from pathlib import Path
from make_fixture import encode


def read_rows(raw, mode="preserve"):
    text = raw.decode("utf-8", errors="strict")
    inputs = {"preserve": lambda: io.StringIO(text, newline=""),
              "split": lambda: text.splitlines(),
              "keepends": lambda: text.splitlines(keepends=True)}
    reader = csv.reader(inputs[mode](), dialect="excel", delimiter=",",
                        quotechar='"', doublequote=True,
                        skipinitialspace=False, strict=True)
    rows = list(reader)
    return rows, reader.line_num


def verify(raw, header, expected_rows, mode="preserve"):
    if raw.startswith(b"\xef\xbb\xbf"):
        raise ValueError("case requires UTF-8 without BOM")
    rows, physical = read_rows(raw, mode)
    if not rows or rows[0] != header:
        raise ValueError("header differs from this fictional schema")
    data = rows[1:]
    if len(data) != len(expected_rows) or any(len(r) != len(header) for r in data):
        raise ValueError("record or field count differs")
    if data != expected_rows:
        raise ValueError("fields differ from declared expectations")
    return rows, physical


def main():
    if (platform.python_implementation(), platform.python_version()) != ("CPython", "3.12.3"):
        raise SystemExit("Exact reproduction requires CPython 3.12.3")
    fixture = json.loads(Path("fixture.json").read_text(encoding="utf-8"))
    expected = json.loads(Path("expected.json").read_text(encoding="utf-8"))
    header, wanted = fixture["header"], fixture["rows"]
    raw = Path("contacts.csv").read_bytes()
    rows, physical = verify(raw, header, wanted)
    broken, broken_physical = read_rows(raw, "split")
    baseline = {"bytes": len(raw), "sha256": hashlib.sha256(raw).hexdigest(),
                "records": len(rows) - 1, "physical_lines": physical,
                "split_records": len(broken) - 1,
                "split_physical_lines": broken_physical,
                "split_notes": [r[-1] for r in broken[1:]],
                "roundtrip_equal": encode(header, rows[1:]) == raw}
    if baseline != expected["baseline"]:
        raise AssertionError("baseline summary differs")
    no_newline = [r[:-1] + [r[-1].replace("\r\n", " / ")] for r in wanted]
    lf_rows = [r[:-1] + [r[-1].replace("\r\n", "\n")] for r in wanted]
    quote_rows = [list(r) for r in wanted]
    quote_rows[2][-1] = 'A "quoted", ordinary note'
    renamed = encode(["FullName", *header[1:]], wanted)
    extra = encode(header, [wanted[0] + ["extra"], *wanted[1:]])
    missing = encode(header, wanted[:2])
    stripped = raw.replace(b"00123", b"123", 1)
    changed = raw.replace(b"Second line", b"Changed line", 1)
    tests = [
        ("baseline-preserved", raw, wanted, "preserve", True),
        ("splitlines-loss", raw, wanted, "split", False),
        ("splitlines-keepends", raw, wanted, "keepends", True),
        ("lf-preserved", encode(header, lf_rows, "\n"), lf_rows, "preserve", True),
        ("lf-splitlines-loss", encode(header, lf_rows, "\n"), lf_rows, "split", False),
        ("ordinary-split-control", encode(header, no_newline), no_newline, "split", True),
        ("escaped-quote-comma", encode(header, quote_rows), quote_rows, "preserve", True),
        ("changed-note", changed, wanted, "preserve", False),
        ("lost-postal-zero", stripped, wanted, "preserve", False),
        ("renamed-header", renamed, wanted, "preserve", False),
        ("extra-field", extra, wanted, "preserve", False),
        ("missing-record", missing, wanted, "preserve", False),
        ("invalid-utf8", raw.replace(b"Zo\xc3\xab", b"Zo\xff", 1), wanted, "preserve", False),
        ("bom", b"\xef\xbb\xbf" + raw, wanted, "preserve", False),
        ("unfinished-quote", b'Name,PrimaryEmail,AlternateEmail,Phone,Postal,Notes\r\n"unfinished', wanted, "preserve", False)
    ]
    results = []
    for name, payload, fields, mode, wanted_accept in tests:
        try:
            verify(payload, header, fields, mode)
            accepted, reason = True, "all declared fields matched"
        except (UnicodeError, csv.Error, ValueError) as error:
            accepted, reason = False, type(error).__name__ + ": " + str(error)
        if accepted != wanted_accept:
            raise AssertionError(name + ": unexpected result")
        results.append({"case": name, "mode": mode, "expected_accept": wanted_accept,
                        "observed_accept": accepted, "reason": reason,
                        "payload_bytes": len(payload),
                        "payload_sha256": hashlib.sha256(payload).hexdigest()})
    if {r["case"]: r["observed_accept"] for r in results} != expected["cases"]:
        raise AssertionError("case outcomes differ")
    report = {"runtime": "CPython " + platform.python_version(),
              "checked_at": datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z"),
              "baseline": baseline, "expected_fields": wanted, "observed_fields": rows[1:],
              "splitlines_observed_fields": broken[1:], "cases": results,
              "all_declared_expectations_met": True, "product_import": "not performed"}
    Path("observed.json").write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
    print(json.dumps({"records": baseline["records"], "physical_lines": physical,
                      "cases": len(results), "all_declared_expectations_met": True}))


if __name__ == "__main__":
    main()

author-run.json

{
  "runtime": "CPython 3.12.3",
  "checked_at": "2026-10-05T13:32:17.345699Z",
  "baseline": {
    "bytes": 301,
    "sha256": "b55fa9a28a7b19e1ea0790a00dcac9151c7719b3d78ea9f348e3e068beb4ab56",
    "records": 3,
    "physical_lines": 6,
    "split_records": 3,
    "split_physical_lines": 6,
    "split_notes": [
      "First line, quotedSecond line",
      "AlphaBeta",
      "Ordinary note"
    ],
    "roundtrip_equal": true
  },
  "expected_fields": [
    [
      "Zoë Example",
      "zoe@example.org",
      "zoe.alt@example.org",
      "0000000001",
      "00123",
      "First line, quoted\r\nSecond line"
    ],
    [
      "René Example",
      "rene@example.org",
      "",
      "0000000002",
      "00007",
      "Alpha\r\nBeta"
    ],
    [
      "Maya Example",
      "maya@example.org",
      "maya.alt@example.org",
      "0000000003",
      "01234",
      "Ordinary note"
    ]
  ],
  "observed_fields": [
    [
      "Zoë Example",
      "zoe@example.org",
      "zoe.alt@example.org",
      "0000000001",
      "00123",
      "First line, quoted\r\nSecond line"
    ],
    [
      "René Example",
      "rene@example.org",
      "",
      "0000000002",
      "00007",
      "Alpha\r\nBeta"
    ],
    [
      "Maya Example",
      "maya@example.org",
      "maya.alt@example.org",
      "0000000003",
      "01234",
      "Ordinary note"
    ]
  ],
  "splitlines_observed_fields": [
    [
      "Zoë Example",
      "zoe@example.org",
      "zoe.alt@example.org",
      "0000000001",
      "00123",
      "First line, quotedSecond line"
    ],
    [
      "René Example",
      "rene@example.org",
      "",
      "0000000002",
      "00007",
      "AlphaBeta"
    ],
    [
      "Maya Example",
      "maya@example.org",
      "maya.alt@example.org",
      "0000000003",
      "01234",
      "Ordinary note"
    ]
  ],
  "cases": [
    {
      "case": "baseline-preserved",
      "mode": "preserve",
      "expected_accept": true,
      "observed_accept": true,
      "reason": "all declared fields matched",
      "payload_bytes": 301,
      "payload_sha256": "b55fa9a28a7b19e1ea0790a00dcac9151c7719b3d78ea9f348e3e068beb4ab56"
    },
    {
      "case": "splitlines-loss",
      "mode": "split",
      "expected_accept": false,
      "observed_accept": false,
      "reason": "ValueError: fields differ from declared expectations",
      "payload_bytes": 301,
      "payload_sha256": "b55fa9a28a7b19e1ea0790a00dcac9151c7719b3d78ea9f348e3e068beb4ab56"
    },
    {
      "case": "splitlines-keepends",
      "mode": "keepends",
      "expected_accept": true,
      "observed_accept": true,
      "reason": "all declared fields matched",
      "payload_bytes": 301,
      "payload_sha256": "b55fa9a28a7b19e1ea0790a00dcac9151c7719b3d78ea9f348e3e068beb4ab56"
    },
    {
      "case": "lf-preserved",
      "mode": "preserve",
      "expected_accept": true,
      "observed_accept": true,
      "reason": "all declared fields matched",
      "payload_bytes": 295,
      "payload_sha256": "1b1c729ff2a3fe08d8ddcb7da91542263d3f79a263cb505af8b23220e84984b6"
    },
    {
      "case": "lf-splitlines-loss",
      "mode": "split",
      "expected_accept": false,
      "observed_accept": false,
      "reason": "ValueError: fields differ from declared expectations",
      "payload_bytes": 295,
      "payload_sha256": "1b1c729ff2a3fe08d8ddcb7da91542263d3f79a263cb505af8b23220e84984b6"
    },
    {
      "case": "ordinary-split-control",
      "mode": "split",
      "expected_accept": true,
      "observed_accept": true,
      "reason": "all declared fields matched",
      "payload_bytes": 301,
      "payload_sha256": "9d1d242faa18a1d8a0f83c5ee82abd7336dfd59f56dac68b09769215934c550d"
    },
    {
      "case": "escaped-quote-comma",
      "mode": "preserve",
      "expected_accept": true,
      "observed_accept": true,
      "reason": "all declared fields matched",
      "payload_bytes": 317,
      "payload_sha256": "510248d0ce4bd9ebda1aaebd9c4aeb3ecfa74aa2e49ed26de10369b4007000a1"
    },
    {
      "case": "changed-note",
      "mode": "preserve",
      "expected_accept": false,
      "observed_accept": false,
      "reason": "ValueError: fields differ from declared expectations",
      "payload_bytes": 302,
      "payload_sha256": "faf705c01e9bb0bf6e2c618b48cb25420c0b5f899b48de6f5892a8eb576f802f"
    },
    {
      "case": "lost-postal-zero",
      "mode": "preserve",
      "expected_accept": false,
      "observed_accept": false,
      "reason": "ValueError: fields differ from declared expectations",
      "payload_bytes": 299,
      "payload_sha256": "d259c47e3050ff0b0374e6e234b6175604fe54e4a09df77810e4b95405812343"
    },
    {
      "case": "renamed-header",
      "mode": "preserve",
      "expected_accept": false,
      "observed_accept": false,
      "reason": "ValueError: header differs from this fictional schema",
      "payload_bytes": 305,
      "payload_sha256": "80f9e5fac280bfe2f5d981843c7d2a1709555f1fe7098ed2a01cc0032337a0e8"
    },
    {
      "case": "extra-field",
      "mode": "preserve",
      "expected_accept": false,
      "observed_accept": false,
      "reason": "ValueError: record or field count differs",
      "payload_bytes": 307,
      "payload_sha256": "984e4fe0a8b331327e8cd18ab710ed4144bff2cd4d55e184ae532e2bee338362"
    },
    {
      "case": "missing-record",
      "mode": "preserve",
      "expected_accept": false,
      "observed_accept": false,
      "reason": "ValueError: record or field count differs",
      "payload_bytes": 218,
      "payload_sha256": "88f8974cd575f444f2650b8fbce8ad36f5e8ab5ca25eecfc1e9a28881707338b"
    },
    {
      "case": "invalid-utf8",
      "mode": "preserve",
      "expected_accept": false,
      "observed_accept": false,
      "reason": "UnicodeDecodeError: 'utf-8' codec can't decode byte 0xff in position 55: invalid start byte",
      "payload_bytes": 300,
      "payload_sha256": "17b47aff88467e70b96b41b24f9fc02a59653fc279d7176fe5820e817c5b61af"
    },
    {
      "case": "bom",
      "mode": "preserve",
      "expected_accept": false,
      "observed_accept": false,
      "reason": "ValueError: case requires UTF-8 without BOM",
      "payload_bytes": 304,
      "payload_sha256": "d5b868c0d3abba7123093c10714af84f2f34eea5816cfacf965c3622c3fcaad9"
    },
    {
      "case": "unfinished-quote",
      "mode": "preserve",
      "expected_accept": false,
      "observed_accept": false,
      "reason": "Error: unexpected end of data",
      "payload_bytes": 64,
      "payload_sha256": "e1ae19d8852880cb4cab07af23c14ef64e9dd8346efc3bf6510a75992b9fd1c7"
    }
  ],
  "all_declared_expectations_met": true,
  "product_import": "not performed"
}