{"record":{"id":"9f82f5a17fd618a8","repo":"pola-rs/polars","slug":"new-argument-is-required-if-old-argument-is-no","errorCode":null,"errorMessage":"`new` argument is required if `old` argument is not a Mapping type","messagePattern":"`new` argument is required if `old` argument is not a Mapping type","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/expr/expr.py","lineNumber":12268,"sourceCode":"                \" Use `replace_strict` instead to set a return data type while replacing values.\",\n                version=\"1.0.0\",\n            )\n        if default is not NO_DEFAULT:\n            issue_deprecation_warning(\n                \"the `default` parameter for `replace` is deprecated.\"\n                \" Use `replace_strict` instead to set a default while replacing values.\",\n                version=\"1.0.0\",\n            )\n            return self.replace_strict(\n                old, new, default=default, return_dtype=return_dtype\n            )\n\n        if new is NO_DEFAULT:\n            if not isinstance(old, Mapping):\n                msg = (\n                    \"`new` argument is required if `old` argument is not a Mapping type\"\n                )\n                raise TypeError(msg)\n            new = list(old.values())\n            old = list(old.keys())\n        else:\n            if isinstance(old, Sequence) and not isinstance(old, (str, pl.Series)):\n                old = pl.Series(old)\n            if isinstance(new, Sequence) and not isinstance(new, (str, pl.Series)):\n                new = pl.Series(new)\n\n        old_pyexpr = parse_into_expression(old, str_as_lit=True)  # type: ignore[arg-type]\n        new_pyexpr = parse_into_expression(new, str_as_lit=True)\n\n        result = wrap_expr(self._pyexpr.replace(old_pyexpr, new_pyexpr))\n\n        if return_dtype is not None:\n            result = result.cast(return_dtype)\n\n        return result\n","sourceCodeStart":12250,"sourceCodeEnd":12286,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/expr/expr.py#L12250-L12286","documentation":"Expr.replace(old, new) raises TypeError when `new` is omitted and `old` is not a Mapping. The two supported call shapes are replace(mapping) (dict of old->new) or replace(old, new) with both positional arguments; a bare scalar/list old with no new is meaningless. Note the check uses the NO_DEFAULT sentinel, so new=None does not satisfy it either.","triggerScenarios":"pl.col('a').replace(2), pl.col('a').replace([1, 2]) without new, or replace(old=2, new=None) via optional parameters that default to None.","commonSituations":"Wrapping replace in a helper where new is optional (default None instead of NO_DEFAULT); assuming old alone is a no-op filter; upgrading code where a default value used to be positional.","solutions":["Pass both arguments: pl.col('a').replace(2, 10).","Or pass a dict: pl.col('a').replace({2: 10, 3: 30}).","In wrapper functions, use a sentinel (NO_DEFAULT-style object), not None, to detect 'not provided'."],"exampleFix":"# before\npl.col('a').replace(2)\n\n# after\npl.col('a').replace(2, 10)\n# or\npl.col('a').replace({2: 10})","handlingStrategy":"type-guard","validationCode":"from collections.abc import Mapping\nif new is None and not isinstance(old, Mapping):\n    raise TypeError('replace needs `new` unless `old` is a mapping')","typeGuard":"from collections.abc import Mapping\n\ndef has_full_replace_args(old, new) -> bool:\n    return isinstance(old, Mapping) or new is not None","tryCatchPattern":null,"preventionTips":["Default wrapper parameters to a sentinel object, never None, for arguments where None is not a valid value.","Prefer the dict form replace({...}) for multi-value mappings."],"tags":["validation","polars","expression","replace","type-error"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}