{"record":{"id":"54ef6941cf580951","repo":"pola-rs/polars","slug":"expected-type-int-str-got-qualified-type-name-item-r","errorCode":null,"errorMessage":"expected type 'int | str', got {qualified_type_name(item)!r}","messagePattern":"expected type 'int \\| str', got (.+?)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/series/struct.py","lineNumber":44,"sourceCode":"\n\n@expr_dispatch\nclass StructNameSpace(_NamespaceSuggestMixin):\n    \"\"\"Series.struct namespace.\"\"\"\n\n    _accessor = \"struct\"\n\n    def __init__(self, series: Series) -> None:\n        self._s: PySeries = series._s\n\n    def __getitem__(self, item: int | str) -> Series:\n        if isinstance(item, int):\n            return self.field(self.fields[item])\n        elif isinstance(item, str):\n            return self.field(item)\n        else:\n            msg = f\"expected type 'int | str', got {qualified_type_name(item)!r}\"\n            raise TypeError(msg)\n\n    def _ipython_key_completions_(self) -> list[str]:\n        return self.fields\n\n    @property\n    def fields(self) -> list[str]:\n        \"\"\"\n        Get the names of the fields.\n\n        Examples\n        --------\n        >>> s = pl.Series([{\"a\": 1, \"b\": 2}, {\"a\": 3, \"b\": 4}])\n        >>> s.struct.fields\n        ['a', 'b']\n        \"\"\"\n        if getattr(self, \"_s\", None) is None:\n            return []\n        return self._s.struct_fields()","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/series/struct.py#L26-L62","documentation":"Subscript type-guard on the struct namespace: indexing a Struct series is only meaningful by integer position (resolved via self.fields[item]) or by field name (resolved via self.field(item)). Any other key type reaches the final else branch and is rejected with the qualified name of the offending item.","triggerScenarios":"Indexing a struct Series with e.g. s_struct[0.0], s_struct[None], a tuple, or a boolean; typing the wrong index variable in a loop over fields.","commonSituations":"Reusing generic dict-style access code (`s[key]`) where key came from JSON parsing as a non-str; iterating with enumerate and passing the (index, value) tuple by mistake.","solutions":["Pass the field name as a str: s_struct[\"field_name\"].","Pass the positional index as an int: s_struct[0].","Convert/coerce the key first (int(key) or str(key)) once its real type is known."],"exampleFix":"// before\nfield = s_struct[1.0]  # TypeError\n\n// after\nfield = s_struct[int(1.0)]  # or s_struct[\"field_name\"]","handlingStrategy":"type-guard","validationCode":"if not isinstance(key, (int, str)):\n    raise TypeError(f\"struct field key must be int|str, got {type(key).__name__}\")","typeGuard":"def is_struct_key(key) -> bool:\n    return isinstance(key, (int, str)) and not isinstance(key, bool)","tryCatchPattern":"try:\n    field = s_struct[key]\nexcept TypeError:\n    field = s_struct[str(key)]","preventionTips":["Normalize keys to str before indexing struct series","Avoid reusing dict-style access code with arbitrary key types","Use s_struct.schema.keys to iterate field names explicitly"],"tags":["polars","struct","typeerror","indexing"],"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"}