pola-rs/polars · error

unrecognised deprecation type

Error message

unrecognised deprecation type {tp!r}.

What it means

During its scan, `identify_deprecations` discovers deprecation functions found in source files; if a found function's deprecation_type is not in `valid_types`, it raises this ValueError. It indicates a new deprecation helper was added without updating the DeprecationType alias.

Solutions

1. Add the new deprecation type to the DeprecationType type alias in deprecation.py
2. Or update the new helper to emit an already-registered deprecation type
3. Re-run identify_deprecations to confirm the scan passes

Example fix

// before
DeprecationType = Literal["function", "parameter"]
// after
DeprecationType = Literal["function", "parameter", "sibling"]

try:
    results = identify_deprecations(types=valid_types)
except ValueError as e:
    raise RuntimeError("new deprecation function must be added to DeprecationType") from e

When it happens

Trigger: Running `identify_deprecations` after a contributor added a new deprecation-emitting function (e.g. a new warning helper) that is not covered by the DeprecationType type alias.

Common situations: Polars maintenance/CI work: a PR introduces a new deprecation mechanism but forgets to extend the type alias, so the self-check fails.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Unexpected parameter type
• unrecognised deprecation type
• accessing ` ` from the top-level `polars` module was…
• altair>=5.4.0 is required for `.plot`
• `arctan2` expected a `str` or `Expr` got a

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

Appendix: source

Thrown at py-polars/src/polars/_utils/deprecation.py:356

            )
            raise ValueError(msg)

    package_path = Path(sys.modules["polars"].__file__).parent  # type: ignore[arg-type]
    results = defaultdict(list)

    for py_file in package_path.rglob("*.py"):
        rel_path = py_file.relative_to(package_path)
        module_path = ".".join(rel_path.parts).removesuffix(".py")
        with py_file.open("r", encoding="utf-8") as src:
            for deprecation_type, func_names in _find_deprecated_functions(
                source=src.read(),
                module_path=module_path,
            ).items():
                if deprecation_type not in valid_types:
                    # note: raising here implies we have a new deprecation function
                    # that should be added to the DeprecationType type alias
                    msg = f"unrecognised deprecation type {tp!r}.\n"
                    raise ValueError(msg)

                results[deprecation_type].extend(func_names)

    return {
        dep: sorted(results[dep])
        for dep in sorted(results)
        if not types or dep in types
    }


__all__ = [
    "deprecate_nonkeyword_arguments",
    "deprecate_parameter_as_multi_positional",
    "deprecate_renamed_parameter",
    "deprecated",
    "identify_deprecations",
]

View on GitHub (pinned to fe841f959e)