pola-rs/polars · error

unrecognised deprecation type

Error message

unrecognised deprecation type {tp!r}.
Expected one (or more) of {repr(sorted(valid_types))[1:-1]}

What it means

`identify_deprecations` is a polars developer utility that scans the package for deprecation markers. It raises this ValueError when an element of the `types` argument is not one of the valid DeprecationType values.

Solutions

1. Pass only types from the valid DeprecationType set (listed in the error message)
2. Check the DeprecationType type alias in deprecation.py for the exact valid values
3. Fix typos in the types argument

Example fix

// before
identify_deprecations(types=["removed_params"])
// after
identify_deprecations(types=["parameter", "function"])

from polars._utils.deprecation import identify_deprecations, DeprecationType
import typing
valid = set(typing.get_args(DeprecationType))
assert set(types) <= valid, f"bad types: {set(types) - valid}"

def is_deprecation_type(t: object) -> TypeGuard[str]:
    import typing
    from polars._utils.deprecation import DeprecationType
    return t in set(typing.get_args(DeprecationType))

try:
    results = identify_deprecations(types=types)
except ValueError as e:
    print(e)  # lists valid types
    results = identify_deprecations(types=[t for t in types if is_deprecation_type(t)])

When it happens

Trigger: Running `polars._utils.deprecation.identify_deprecations(types=[...])` with an unrecognized type string, e.g. `types=['renamed_arg']` when valid types are things like 'function', 'parameter', 'method', 'attribute', 'classmethod', etc.

Common situations: Maintainer tooling invocations with a mistyped or newly-invented deprecation category; automated scripts written against an older list of valid types.

Understand the failure class

Background: "invalid argument", "unknown mode", "not supported": invalid enum-like argument errors explained — this error's family across 19 libraries.

Related errors

• schema_mode='overwrite' requires mode='overwrite'
• `time_unit` must be one of
• unrecognised deprecation type
• accessing ` ` from the top-level `polars` module was…
• altair>=5.4.0 is required for `.plot`

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

Appendix: source

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

            - "function"
            - "renamed_parameter"
            - "nonkeyword_arguments"
            - "parameter_as_multi_positional"

    Examples
    --------
    >>> from polars._utils.deprecation import identify_deprecations
    >>> identify_deprecations("nonkeyword_arguments")  # doctest: +IGNORE_RESULT
    {'nonkeyword_arguments': ['functions.business.business_day_count']}
    """
    valid_types = set(get_args(DeprecationType))
    for tp in types:
        if tp not in valid_types:
            msg = (
                f"unrecognised deprecation type {tp!r}.\n"
                f"Expected one (or more) of {repr(sorted(valid_types))[1:-1]}"
            )
            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)

View on GitHub (pinned to fe841f959e)