pola-rs/polars · error · NotImplementedError

TODO: 'frame' map-function parsing

Error message

TODO: 'frame' map-function parsing

What it means

warn_on_inefficient_map analyzes map-family calls to warn about inefficient Python UDFs, but parsing a 'frame' map target (DataFrame.map) is explicitly unimplemented and raises NotImplementedError('TODO: 'frame' map-function parsing'). It is a guard against analyzing a case the parser never learned to handle.

Solutions

1. Don't use DataFrame.map with Python functions; express the transformation with native expressions or Expr.map_elements.
2. Wrap the call site so frame-level maps bypass the parser, or upgrade polars where this path may have changed.
3. Report upstream if you need frame-map efficiency analysis.

Example fix

// before
df.map(row_fn)
// after
df.with_columns((pl.col('a') + pl.col('b')).alias('c'))

# guard at the call site
if map_target == 'frame':
    raise SkipAnalysis('frame-level map parsing not supported')

def is_parseable_map_target(t) -> bool:
    return t in ('expr', 'series')

try:
    warn_on_inefficient_map(fn, columns=cols, map_target='frame')
except NotImplementedError:
    pass  # skip efficiency analysis for frame maps

When it happens

Trigger: Calling map_elements / the warning hook with map_target == "frame" — i.e. a DataFrame-level map function — which immediately raises before any analysis.

Common situations: Applying df.map(...) with a Python function and hitting the analysis path; library code paths that route frame-level maps into the UDF warning machinery in a newer/older polars version.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• require dict mapping
• TODO: map_target =
• TODO: map target not yet supported.
• 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/9d991041d72e7db8. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/_utils/udfs.py:1237

def warn_on_inefficient_map(
    function: Callable[[Any], Any], columns: list[str], map_target: MapTarget
) -> None:
    """
    Generate `PolarsInefficientMapWarning` on poor usage of a `map` function.

    Parameters
    ----------
    function
        The function passed to `map`.
    columns
        The column name(s) of the original object; in the case of an `Expr` this
        will be a list of length 1, containing the expression's root name.
    map_target
        The target of the `map` call. One of `"expr"`, `"frame"`, or `"series"`.
    """
    if map_target == "frame":
        msg = "TODO: 'frame' map-function parsing"
        raise NotImplementedError(msg)

    # note: we only consider simple functions with a single col/param
    col: str = columns and columns[0]  # type: ignore[assignment]
    if not col and col != "":
        return None

    # the parser introspects function bytecode to determine if we can
    # rewrite as a (much) more optimal native polars expression instead
    if (parser := _BYTECODE_PARSER_CACHE_.get(key := (function, map_target))) is None:
        parser = BytecodeParser(function, map_target)
        _BYTECODE_PARSER_CACHE_[key] = parser

    if parser.can_attempt_rewrite():
        parser.warn(col)
    else:
        # handle bare numpy/json functions
        module, suggestion = _raw_function_meta(function)
        if module and suggestion:

View on GitHub (pinned to fe841f959e)