pola-rs/polars · error · TypeError

`arctan2` expected a `str` or `Expr` got a `{qualified_type_

Error message

`arctan2` expected a `str` or `Expr` got a `{qualified_type_name(x)}`

What it means

pl.arctan2(y, x) accepts only column names (str, converted to pl.col) or Expr for both arguments; validation duck-types on the _pyexpr attribute. A numeric literal, Series, or None in the x position fails the check and raises TypeError with its qualified type name. Constants must be wrapped in pl.lit.

Source

Thrown at py-polars/src/polars/functions/lazy.py:1760

    shape: (4, 3)
    ┌───────────┬───────────┬───────────┐
    │ y         ┆ x         ┆ atan2     │
    │ ---       ┆ ---       ┆ ---       │
    │ f64       ┆ f64       ┆ f64       │
    ╞═══════════╪═══════════╪═══════════╡
    │ 0.707107  ┆ 0.707107  ┆ 0.785398  │
    │ -0.707107 ┆ 0.707107  ┆ -0.785398 │
    │ 0.707107  ┆ -0.707107 ┆ 2.356194  │
    │ -0.707107 ┆ -0.707107 ┆ -2.356194 │
    └───────────┴───────────┴───────────┘
    """
    if isinstance(y, str):
        y = F.col(y)
    if isinstance(x, str):
        x = F.col(x)
    if not hasattr(x, "_pyexpr"):
        msg = f"`arctan2` expected a `str` or `Expr` got a `{qualified_type_name(x)}`"
        raise TypeError(msg)
    if not hasattr(y, "_pyexpr"):
        msg = f"`arctan2` expected a `str` or `Expr` got a `{qualified_type_name(y)}`"
        raise TypeError(msg)

    return wrap_expr(plr.arctan2(y._pyexpr, x._pyexpr))


@deprecated("`arctan2d` is deprecated; use `arctan2` followed by `.degrees()` instead.")
def arctan2d(y: str | Expr, x: str | Expr) -> Expr:
    """
    Compute two argument arctan in degrees.

    .. deprecated:: 1.0.0
        Use `arctan2` followed by :meth:`Expr.degrees` instead.

    Returns the angle (in degrees) in the plane between the positive x-axis
    and the ray from the origin to (x,y).

View on GitHub (pinned to df599052da)

Solutions

Wrap constants: pl.arctan2(pl.col('y'), pl.lit(2.0))
Column names may stay as str; anything else must already be an Expr
For Series input, put the data in a frame and reference it by column name inside select

Example fix

# before
pl.arctan2(pl.col('y'), 2.0)  # TypeError on x

# after
pl.arctan2(pl.col('y'), pl.lit(2.0))

Defensive patterns

Strategy: validation

Validate before calling

def to_operand(v):
    if isinstance(v, str):
        return pl.col(v)
    if not hasattr(v, '_pyexpr'):
        return pl.lit(v)
    return v

expr = pl.arctan2(to_operand(y), to_operand(x))

Type guard

def is_expr_or_str(v) -> bool:
    return isinstance(v, (str, pl.Expr))

Prevention

In expression APIs every operand is an Expr — wrap constants with pl.lit
Type helper signatures as (y: str | Expr, x: str | Expr) and keep the (y, x) order explicit

When it happens

Trigger: pl.arctan2(pl.col('y'), 2.0); pl.arctan2('y', some_series); pl.arctan2('y', None). Note the argument order is (y, x), so the x check fires second.

Common situations: Porting numpy arctan2(vec, 1.0) half-angle idioms; passing precomputed Series instead of columns; typos in the argument order causing the wrong operand to be the literal.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/21b3d29f55ef5d40. Report an issue: GitHub.