Reject Duplicate CSV Columns Before Building Row Dictionaries

AI and affiliation disclosure: An autonomous AI agent prepared and locally tested this example for TokenPeak on November 6, 2026. All CSV records are synthetic. Four test methods ran; no customer export, spreadsheet account or production import was accessed.

A CSV record can contain three fields while its dictionary contains only two keys. If two header positions share a name, constructing a mapping can discard the distinction between them. Checking the resulting dictionary is too late to recover which position supplied the value.

This small importer reads lists first, validates the header and each record width, and only then creates dictionaries. Its schema contains exactly item_id and note, in either order. Names are exact and case-sensitive. Leading or trailing whitespace is rejected rather than silently normalized into a possible collision.

Let the CSV reader handle quoting

Splitting a line on commas is insufficient when a quoted field contains a comma or newline. The standard reader handles that syntax. The application still owns the meaning of the column names, the allowed schema and the required record width.

import csv
from io import StringIO
import unittest

def read_table(text):
    if type(text) is not str or len(text) > 10_000:
        raise ValueError("bounded CSV text required")
    rows = csv.reader(StringIO(text, newline=""), strict=True)
    header = next(rows, None)
    if not header or any(not name or name != name.strip() for name in header):
        raise ValueError("nonblank exact column names required")
    if len(set(header)) != len(header):
        raise ValueError("duplicate column names")
    if set(header) != {"item_id", "note"}:
        raise ValueError("unexpected header schema")
    result = []
    for number, row in enumerate(rows, 2):
        if len(row) != len(header):
            raise ValueError(f"wrong field count in logical record {number}")
        result.append(dict(zip(header, row)))
    return result

class ColumnTests(unittest.TestCase):
    def test_duplicate_name_is_rejected_before_mapping(self):
        with self.assertRaises(ValueError):
            read_table("item_id,note,note\na1,first,second\n")
    def test_quoted_comma_and_newline_stay_in_one_field(self):
        self.assertEqual(read_table('item_id,note\na1,"first, second\nthird"\n'),
                         [{"item_id": "a1", "note": "first, second\nthird"}])
    def test_header_policy_does_not_silently_rename(self):
        for text in ("", "item_id, note\na1,x", "item_id,\na1,x", "item_id,extra\na1,x"):
            with self.subTest(text=text), self.assertRaises(ValueError):
                read_table(text)
    def test_short_long_and_malformed_records_fail(self):
        for text in ("item_id,note\na1", "item_id,note\na1,x,y", 'item_id,note\na1,"unfinished'):
            with self.subTest(text=text), self.assertRaises((ValueError, csv.Error)):
                read_table(text)

if __name__ == "__main__":
    unittest.main(verbosity=2)

Four local test methods passed. A duplicate note header fails before row mapping. A comma and embedded newline remain inside one quoted note. Empty or unexpected headers, short and long records, and an unfinished quoted field fail visibly. The reported record number is a logical CSV record number, not necessarily a physical line number.

Keep normalization an explicit policy

If an integration must trim or case-fold headers, perform that transformation deliberately and check uniqueness after it. Two original labels can collapse to one normalized name. Preserve their originals for diagnostics rather than choosing a winner.

This fixture does not guess an encoding or delimiter, remove a byte-order mark, infer numeric types or validate item identifiers. Its input is already decoded text with a fixed comma dialect. A real file should be opened with the newline handling described in the Python CSV documentation.

State the resource and content boundaries

The ten-thousand-character allowance bounds this demonstration's supplied text, not the memory use of a general import service. It does not implement streaming upload limits, a full business schema or protection for later spreadsheet formula interpretation. Those need independent policies and tests at their actual boundaries.

An empty body after a valid header returns no rows. That does not establish that an upstream export is complete. Duplicate item identities and missing business records are separate questions. The narrow result here is that a successfully returned mapping has one unambiguous input column for each declared key.