{"record":{"id":"0d04e1e6ba5621a3","repo":"pola-rs/polars","slug":"cannot-pass-a-dictionary-as-a-single-positional-ar","errorCode":null,"errorMessage":"Cannot pass a dictionary as a single positional argument.\\nIf you merely want the *keys*, use:\\n  • df.method(*your_dict.keys())\\nIf you need the key value pairs, use one of:\\n  • unpack as keywords:    df.method(**your_dict)\\n  • build expressions:     df.method(expr.alias(k) for k, expr in your_dict.items())","messagePattern":"Cannot pass a dictionary as a single positional argument\\.\\\\nIf you merely want the \\*keys\\*, use:\\\\n  • df\\.method\\(\\*your_dict\\.keys\\(\\)\\)\\\\nIf you need the key value pairs, use one of:\\\\n  • unpack as keywords:    df\\.method\\(\\*\\*your_dict\\)\\\\n  • build expressions:     df\\.method\\(expr\\.alias\\(k\\) for k, expr in your_dict\\.items\\(\\)\\)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_utils/parse/expr.py","lineNumber":244,"sourceCode":"\n\ndef _parse_inputs_as_iterable(\n    inputs: tuple[Any, ...] | tuple[Iterable[Any]],\n) -> Iterable[Any]:\n    if not inputs:\n        return []\n\n    # Ensures that the outermost element cannot be a Dictionary (as an iterable)\n    if len(inputs) == 1 and isinstance(inputs[0], Mapping):\n        msg = (\n            \"Cannot pass a dictionary as a single positional argument.\\n\"\n            \"If you merely want the *keys*, use:\\n\"\n            \"  • df.method(*your_dict.keys())\\n\"\n            \"If you need the key value pairs, use one of:\\n\"\n            \"  • unpack as keywords:    df.method(**your_dict)\\n\"\n            \"  • build expressions:     df.method(expr.alias(k) for k, expr in your_dict.items())\"\n        )\n        raise TypeError(msg)\n\n    # Treat elements of a single iterable as separate inputs\n    if len(inputs) == 1 and _is_iterable(inputs[0]):\n        return inputs[0]\n\n    return inputs\n\n\ndef _is_iterable(input: Any) -> bool:\n    return isinstance(input, Iterable) and not isinstance(\n        input, (str, bytes, pl.Series)\n    )\n\n\ndef _parse_named_inputs(\n    named_inputs: dict[str, IntoExpr], *, structify: bool = False\n) -> Iterable[PyExpr]:\n    for name, input in named_inputs.items():","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/_utils/parse/expr.py#L226-L262","documentation":"polars methods such as select/with_columns accept *exprs and **named_exprs. A dict passed as the single positional argument would be silently iterated as its keys by Python, which is almost never intended, so _parse_inputs_as_iterable (parse/expr.py:244) detects a lone Mapping and raises this TypeError listing the three correct spellings.","triggerScenarios":"df.select({'a': pl.col('b')}); df.with_columns({'x': pl.col('a') + 1}); dynamically built expr maps forwarded as f(dict) instead of f(**dict).","commonSituations":"Refactoring dict-based configuration into select; copying pandas assign({...}) style; helper code that forwards a kwargs dict positionally.","solutions":["Unpack as keywords: df.with_columns(**expr_map)","Build aliased expressions: df.select(expr.alias(name) for name, expr in expr_map.items())","If only the keys are wanted: df.select(*expr_map.keys())"],"exampleFix":"# before\ndf.select({\"a\": pl.col(\"b\")})\n\n# after\ndf.select(pl.col(\"b\").alias(\"a\"))  # or df.select(**{\"a\": pl.col(\"b\")})","handlingStrategy":"validation","validationCode":"from collections.abc import Mapping\n\nif len(inputs) == 1 and isinstance(inputs[0], Mapping):\n    raise TypeError(\"dict must be unpacked: use **expr_map or aliased expressions\")\ndf.select(*inputs)","typeGuard":"from collections.abc import Mapping\n\ndef is_bare_dict_arg(args: tuple) -> bool:\n    return len(args) == 1 and isinstance(args[0], Mapping)","tryCatchPattern":null,"preventionTips":["Unpack mapping kwargs with ** instead of passing the dict positionally","Build aliased expressions via a generator when renaming","Lint for f(**d) vs f(d) in code that forwards expression maps"],"tags":["python","polars","select","dict","expression","typeerror"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}