{"record":{"id":"5edcae7ace82389f","repo":"pola-rs/polars","slug":"arg-name-arg-should-be-a-single-byte-charact","errorCode":null,"errorMessage":"{arg_name}=\"{arg}\" should be a single byte character or empty, but is {arg_byte_length} bytes long","messagePattern":"(.+?)=\"(.+?)\" should be a single byte character or empty, but is (.+?) bytes long","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/csv/_utils.py","lineNumber":22,"sourceCode":"\nif TYPE_CHECKING:\n    from collections.abc import Sequence\n\n    from polars import DataFrame\n\n\ndef _check_arg_is_1byte(\n    arg_name: str, arg: str | None, *, can_be_empty: bool = False\n) -> None:\n    if isinstance(arg, str):\n        arg_byte_length = len(arg.encode(\"utf-8\"))\n        if can_be_empty:\n            if arg_byte_length > 1:\n                msg = (\n                    f'{arg_name}=\"{arg}\" should be a single byte character or empty,'\n                    f\" but is {arg_byte_length} bytes long\"\n                )\n                raise ValueError(msg)\n        elif arg_byte_length != 1:\n            msg = (\n                f'{arg_name}=\"{arg}\" should be a single byte character, but is'\n                f\" {arg_byte_length} bytes long\"\n            )\n            raise ValueError(msg)\n\n\ndef _update_columns(df: DataFrame, new_columns: Sequence[str]) -> DataFrame:\n    if df.width > len(new_columns):\n        cols = df.columns\n        for i, name in enumerate(new_columns):\n            cols[i] = name\n        new_columns = cols\n    df.columns = list(new_columns)\n    return df\n","sourceCodeStart":4,"sourceCodeEnd":39,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/csv/_utils.py#L4-L39","documentation":"_check_arg_is_1byte (py-polars/src/polars/io/csv/_utils.py:18-26) validates single-character CSV arguments in read_csv/read_csv_schema. With can_be_empty=True - used only for quote_char - the UTF-8 encoding of the value may be at most one byte; the empty string '' is allowed (meaning no quote character). Multi-byte characters or multi-character strings raise ValueError naming the argument and its actual byte length.","triggerScenarios":"pl.read_csv(f, quote_char='\\u201c') (typographic quote, 3 UTF-8 bytes); quote_char='||'; any non-ASCII quote copied from Excel/smart-editors. separator='\\t' is fine (1 byte).","commonSituations":"Excel-exported CSVs quoted with curly quotes; editors auto-replacing ASCII quotes with smart quotes; configs that copy the visual delimiter character from a spreadsheet.","solutions":["Replace the character with its single-byte ASCII equivalent ('\\u201c' -> '\"', '\\uff5c' -> '|')","Pass quote_char=None to disable quoting if no quoting is present in the file","Normalize configs to ASCII before passing them to read_csv"],"exampleFix":"# before\ndf = pl.read_csv(\"f.csv\", quote_char=\"\\u201c\")\n# after\ndf = pl.read_csv(\"f.csv\", quote_char=\"\\\"\" )","handlingStrategy":"validation","validationCode":"def check_one_byte(arg_name: str, value: str | None, allow_empty: bool = True) -> None:\n    if value is None:\n        return\n    n = len(value.encode(\"utf-8\"))\n    if (allow_empty and n > 1) or (not allow_empty and n != 1):\n        raise ValueError(f\"{arg_name}={value!r} is {n} bytes; use a single-byte ASCII character\")","typeGuard":null,"tryCatchPattern":"try:\n    df = pl.read_csv(path, quote_char=qc)\nexcept ValueError as e:\n    if \"single byte\" in str(e):\n        df = pl.read_csv(path, quote_char='\"')\n    else:\n        raise","preventionTips":["Normalize CSV options to ASCII in config loaders (unicodedata.normalize('NFKC', ...) helps for smart quotes)","Never copy quote/delimiter characters directly from spreadsheet apps","Add a lint rule for CSV option values: len(v.encode('utf-8')) <= 1"],"tags":["polars","csv","encoding","quote-char","valueerror"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}