polars.format#

polars.format(f_string: str, *args: IntoExpr) → Expr[source]#

Format expressions as a string.

Parameters:

f_string

A string with placeholders of the form {}, {index} or {name}.

A placeholder can be empty, in which case it consumes the next argument to pl.format. It can also be an index in which case it addresses the nth argument to pl.format. Finally a placeholder can also be an ASCII identifier, in which case it directly refers to a column name.

If you wish to use the characters {} literally you must escape them by doubling, e.g. '{{"json": 42}}'.

args

Expression(s) that fill the placeholders

Notes

If any input expression evaluates to null for a row, the output of pl.format is null for that row.

Examples

>>> df = pl.DataFrame(
...     {
...         "a": ["a", "b", "c"],
...         "b": [1, 2, 3],
...     }
... )
>>> df.select(
...     [
...         pl.format("foo_{}_bar_{}", pl.col("a"), "b").alias("fmt"),
...     ]
... )
shape: (3, 1)
┌─────────────┐
│ fmt         │
│ ---         │
│ str         │
╞═════════════╡
│ foo_a_bar_1 │
│ foo_b_bar_2 │
│ foo_c_bar_3 │
└─────────────┘
>>> df = pl.DataFrame({"a": [1, 2, 3], "b": [4, None, 6]})
>>> df.select(pl.format("{}_{}", "a", "b").alias("fmt"))
shape: (3, 1)
┌──────┐
│ fmt  │
│ ---  │
│ str  │
╞══════╡
│ 1_4  │
│ null │
│ 3_6  │
└──────┘