pola-rs/polars · error · AttributeError

cannot override ` . ` with custom namespace

Error message

cannot override `{cls.__name__}.{name}` with custom namespace {ns_class.__name__!r}

What it means

When registering a custom namespace, Polars raises AttributeError if the target class already has an attribute with that name that is a function, a property, or starts with an underscore. This prevents custom namespaces from shadowing real methods or private attributes of DataFrame/LazyFrame/Series. Distinct from the reserved-namespace error: this covers any existing method/property, not just built-in namespaces.

Solutions

Rename the namespace to something that does not clash with an existing method (e.g. prefix it)
If a prior custom registration is being replaced, use a different module load path; overriding is only allowed for previously-registered custom namespaces (which emits a warning, not this error)

Example fix

// before
@pl.api.register_dataframe_namespace("columns")
class ColumnsNS: ...
// after
@pl.api.register_dataframe_namespace("my_columns")
class ColumnsNS: ...

Defensive patterns

Strategy: validation

Validate before calling

existing = getattr(pl.DataFrame, ns_name, None)
assert existing is None or (not callable(existing) and not isinstance(existing, property) and not ns_name.startswith('_'))

Type guard

def is_free_namespace_name(cls: type, name: str) -> bool:
    attr = getattr(cls, name, None)
    return attr is None or not (callable(attr) or isinstance(attr, property) or name.startswith('_'))

Try / catch

try:
    pl.api.register_dataframe_namespace("head")(MyNS)
except AttributeError as e:
    if "cannot override" in str(e):
        pl.api.register_dataframe_namespace("my_head")(MyNS)
    else:
        raise

Prevention

Avoid namespace names that match DataFrame/LazyFrame/Series methods or start with '_'
Keep registrations idempotent and centralized to detect collisions at import time
Re-run registration tests after polars upgrades (new methods may collide)

When it happens

Trigger: `@pl.api.register_lazyframe_namespace("filter")` or any name matching an existing method/property/underscore-prefixed attribute on the target class.

Common situations: Naming a custom namespace after a common DataFrame method like 'head', 'columns', or 'group_by'; re-running module registration code that now collides after a Polars upgrade added a new method with that name.

Related errors

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/6f2368439211a113. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/api.py:60

        ns_instance = self._ns(instance)  # type: ignore[call-arg]
        setattr(instance, self._accessor, ns_instance)
        return ns_instance


def _create_namespace(
    name: str, cls: type[Expr | DataFrame | LazyFrame | Series]
) -> Callable[[type[NS]], type[NS]]:
    """Register custom namespace against the underlying Polars class."""

    def namespace(ns_class: type[NS]) -> type[NS]:
        if name in _reserved_namespaces:
            msg = f"cannot override reserved namespace {name!r}"
            raise AttributeError(msg)
        elif (attr := getattr(cls, name, None)) is not None:
            if isfunction(attr) or isinstance(attr, property) or name.startswith("_"):
                msg = f"cannot override `{cls.__name__}.{name}` with custom namespace {ns_class.__name__!r}"
                raise AttributeError(msg)
            warn(
                f"overriding existing custom namespace {name!r} (on {cls.__name__})",
                UserWarning,
                stacklevel=find_stacklevel(),
            )

        setattr(cls, name, NameSpace(name, ns_class))
        cls._accessors.add(name)
        return ns_class

    return namespace


def register_expr_namespace(name: str) -> Callable[[type[NS]], type[NS]]:
    """
    Decorator for registering custom functionality with a Polars Expr.

    Parameters

View on GitHub (pinned to fe841f959e)