{"record":{"id":"291ac54e42b07aab","repo":"pola-rs/polars","slug":"conversion-of-polars-data-type-dtype-r-to-python","errorCode":null,"errorMessage":"conversion of polars data type {dtype!r} to Python type not implemented","messagePattern":"conversion of polars data type (.+?) to Python type not implemented","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/datatypes/convert.py","lineNumber":270,"sourceCode":"\ndef dtype_to_ffiname(dtype: PolarsDataType) -> str:\n    \"\"\"Return FFI function name associated with the given Polars dtype.\"\"\"\n    try:\n        dtype = dtype.base_type()\n        return DataTypeMappings.DTYPE_TO_FFINAME[dtype]\n    except KeyError:  # pragma: no cover\n        msg = f\"conversion of polars data type {dtype!r} to FFI not implemented\"\n        raise NotImplementedError(msg) from None\n\n\ndef dtype_to_py_type(dtype: PolarsDataType) -> PythonDataType:\n    \"\"\"Convert a Polars dtype to a Python dtype.\"\"\"\n    try:\n        dtype = dtype.base_type()\n        return DataTypeMappings.DTYPE_TO_PY_TYPE[dtype]\n    except KeyError:  # pragma: no cover\n        msg = f\"conversion of polars data type {dtype!r} to Python type not implemented\"\n        raise NotImplementedError(msg) from None\n\n\ndef py_type_to_arrow_type(dtype: PythonDataType) -> pa.DataType:\n    \"\"\"Convert a Python dtype to an Arrow dtype.\"\"\"\n    try:\n        return DataTypeMappings.PY_TYPE_TO_ARROW_TYPE[dtype]\n    except KeyError:  # pragma: no cover\n        msg = f\"cannot parse Python data type {dtype!r} into Arrow data type\"\n        raise ValueError(msg) from None\n\n\ndef dtype_short_repr_to_dtype(dtype_string: str | None) -> PolarsDataType | None:\n    \"\"\"Map a PolarsDataType short repr (eg: 'i64', 'list[str]') back into a dtype.\"\"\"\n    if dtype_string is None:\n        return None\n\n    m = re.match(r\"^(\\w+)(?:\\[(.+)\\])?$\", dtype_string)\n    if m is None:","sourceCodeStart":252,"sourceCodeEnd":288,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/datatypes/convert.py#L252-L288","documentation":"dtype_to_py_type converts a polars dtype to the corresponding Python scalar type, but the mapping only covers primitive dtypes. Nested types (List, Array, Struct) have no single Python equivalent, so lookup raises NotImplementedError. Usually hit indirectly through generic code that assumes every dtype maps to one Python type.","triggerScenarios":"Calling polars.datatypes.convert.dtype_to_py_type (directly or via maybe_cast-style item conversion) with pl.List(pl.Int64), pl.Array(pl.String, 3), pl.Struct([...]), or another dtype whose base_type() is absent from DTYPE_TO_PY_TYPE.","commonSituations":"Serialising polars schemas to Python type hints; generic dtype-walking utilities over DataFrames that contain list/struct columns; item conversion helpers reaching nested columns.","solutions":["Handle nested dtypes explicitly: branch on isinstance(dtype, (pl.List, pl.Array, pl.Struct)) and recurse into inner types instead of calling dtype_to_py_type","Upgrade polars — dtype mappings gain coverage across releases","If you cannot avoid the call, catch NotImplementedError and fall back to object-level handling for that column"],"exampleFix":"# before\npy_type = dtype_to_py_type(pl.List(pl.Int64))  # NotImplementedError\n\n# after\nif isinstance(dtype, (pl.List, pl.Array, pl.Struct)):\n    py_type = object  # handle inner types yourself\nelse:\n    py_type = dtype_to_py_type(dtype)","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"import polars as pl\n\ndef is_nested_dtype(dtype: pl.DataType) -> bool:\n    return isinstance(dtype, (pl.List, pl.Array, pl.Struct))\n\n# guard before scalar conversion\nif not is_nested_dtype(dtype):\n    py_type = dtype_to_py_type(dtype)","tryCatchPattern":"from polars.datatypes.convert import dtype_to_py_type\n\ntry:\n    py_type = dtype_to_py_type(dtype)\nexcept NotImplementedError:\n    py_type = object  # nested dtype: handle inner fields explicitly","preventionTips":["Branch on List/Array/Struct before calling dtype_to_py_type in schema-walking code","Resolve Struct fields and List/Array inner types recursively instead of expecting one scalar type"],"tags":["dtype","conversion","nested-types","not-implemented"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}