{"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":"validation","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/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/io/csv/_utils.py#L4-L39","documentation":"Polars requires CSV delimiter-like arguments (separator, quote_char, etc.) to be exactly one byte, or — only when `can_be_empty=True` — an empty string. `_check_arg_is_1byte` measures the UTF-8 byte length of the argument and raises this ValueError when an empty-allowed argument is longer than one byte. This guards against multi-byte characters passed to the Rust CSV parser, which operates on single-byte tokens.","triggerScenarios":"Calling `read_csv`, `scan_csv`, `write_csv`, or `sink_csv` with an argument validated with `can_be_empty=True` (e.g. `quote_char`) that encodes to more than 1 byte — e.g. `quote_char=\"''\"` (two chars) or a multi-byte Unicode character like `\"«\"`.","commonSituations":"Copy-pasting a typographic quote or full-width character as a separator; accidentally passing a two-character string like \"\\t\\t\" or \"||\"; confusion between a Python str of one character and one byte for non-ASCII input.","solutions":["Inspect the argument's byte length: `len(arg.encode(\"utf-8\"))` — it must be 1 (or 0 for empty-allowed args).","Replace multi-character values with the intended single ASCII byte, e.g. `quote_char='\"'` or `separator=\",\"`.","For tab separators use the actual tab character `\"\\t\"` (one byte), not a literal \"tab\" string or two spaces.","If you intended no quote handling, pass an empty string `\"\"` (allowed for `quote_char`)."],"exampleFix":"// before\npl.read_csv(\"data.csv\", separator=\"||\")\n# after\npl.read_csv(\"data.csv\", separator=\"|\")","handlingStrategy":"validation","validationCode":"def check_byte_arg(arg: str, allow_empty: bool = False) -> str:\n    n = len(arg.encode(\"utf-8\"))\n    if allow_empty and n > 1:\n        raise ValueError(f\"{arg!r} must be 0 or 1 bytes, got {n}\")\n    if not allow_empty and n != 1:\n        raise ValueError(f\"{arg!r} must be exactly 1 byte, got {n}\")\n    return arg\n\nsep = check_byte_arg(sep, allow_empty=True)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use plain ASCII characters for separators and quote chars.","Prefer omitting optional args to use library defaults instead of passing empty/multi-char values.","Sanitize user-supplied delimiter config: accept only single ASCII chars."],"tags":["python","csv","validation","arguments"],"backgroundTag":"invalid-argument-value","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}