{"record":{"id":"4814e66354e3e9a1","repo":"pola-rs/polars","slug":"cannot-override-reserved-namespace-name-r","errorCode":null,"errorMessage":"cannot override reserved namespace {name!r}","messagePattern":"cannot override reserved namespace (.+?)","errorType":"exception","errorClass":"AttributeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/api.py","lineNumber":56,"sourceCode":"\n    def __get__(self, instance: NS | None, cls: type[NS]) -> NS | type[NS]:\n        if instance is None:\n            return self._ns\n\n        ns_instance = self._ns(instance)  # type: ignore[call-arg]\n        setattr(instance, self._accessor, ns_instance)\n        return ns_instance\n\n\ndef _create_namespace(\n    name: str, cls: type[Expr | DataFrame | LazyFrame | Series]\n) -> Callable[[type[NS]], type[NS]]:\n    \"\"\"Register custom namespace against the underlying Polars class.\"\"\"\n\n    def namespace(ns_class: type[NS]) -> type[NS]:\n        if name in _reserved_namespaces:\n            msg = f\"cannot override reserved namespace {name!r}\"\n            raise AttributeError(msg)\n        elif (attr := getattr(cls, name, None)) is not None:\n            if isfunction(attr) or isinstance(attr, property) or name.startswith(\"_\"):\n                msg = f\"cannot override `{cls.__name__}.{name}` with custom namespace {ns_class.__name__!r}\"\n                raise AttributeError(msg)\n            warn(\n                f\"overriding existing custom namespace {name!r} (on {cls.__name__})\",\n                UserWarning,\n                stacklevel=find_stacklevel(),\n            )\n\n        setattr(cls, name, NameSpace(name, ns_class))\n        cls._accessors.add(name)\n        return ns_class\n\n    return namespace\n\n\ndef register_expr_namespace(name: str) -> Callable[[type[NS]], type[NS]]:","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/api.py#L38-L74","documentation":"The `pl.api.register_dataframe_namespace`-style `namespace()` decorator raises AttributeError if the chosen namespace name collides with one of Polars' reserved built-in namespaces (such as 'str', 'dt', 'cat', 'name', 'bin'). Reserved namespaces are core functionality and cannot be shadowed by user extensions. The check happens at decoration time, before any instances are created.","triggerScenarios":" Decorating a custom namespace class whose `name` argument equals a reserved namespace, e.g. `@pl.api.register_dataframe_namespace(\"str\")`, then applying it.","commonSituations":"Choosing a generic short name for a custom namespace that happens to match a built-in; copying example code and renaming the namespace to something already taken.","solutions":["Pick a non-reserved namespace name (e.g. \"mystr\", \"custom_str\") and re-run the registration","Check `polars.api` docs / `_reserved_namespaces` for the list of taken names"],"exampleFix":"// before\n@pl.api.register_dataframe_namespace(\"str\")\nclass MyStrNamespace: ...\n// after\n@pl.api.register_dataframe_namespace(\"my_str\")\nclass MyStrNamespace: ...","handlingStrategy":"validation","validationCode":"RESERVED = {'str','dt','cat','name','bin'}\nassert ns_name not in RESERVED, f\"{ns_name!r} is a reserved polars namespace\"","typeGuard":null,"tryCatchPattern":"try:\n    pl.api.register_dataframe_namespace(\"str\")(MyNS)\nexcept AttributeError as e:\n    if \"reserved namespace\" in str(e):\n        ns_name = \"my_str\"\n        pl.api.register_dataframe_namespace(ns_name)(MyNS)\n    else:\n        raise","preventionTips":["Prefix custom namespace names (e.g. 'my_', your project name)","Check the polars docs for built-in namespaces before choosing a name","Register namespaces in one module so collisions surface early"],"tags":["python","namespace","api-misuse"],"backgroundTag":"invalid-identifier","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"}