def lit(
value: None |
(float | int | str | date | datetime | pli.Series | np.ndarray | Any),
dtype: type[DataType] | None = None,
) -> pli.Expr:
"""
A literal value.
Parameters
----------
value
Value that should be used as a `literal`.
dtype
Optionally define a dtype.
Examples
--------
Literal integer:
>>> pl.lit(1) # doctest: +IGNORE_RESULT
Literal str:
>>> pl.lit("foo") # doctest: +IGNORE_RESULT
Literal datetime:
>>> from datetime import datetime
>>> pl.lit(datetime(2021, 1, 20)) # doctest: +IGNORE_RESULT
Literal Null:
>>> pl.lit(None) # doctest: +IGNORE_RESULT
Literal eager Series:
>>> pl.lit(pl.Series("a", [1, 2, 3])) # doctest: +IGNORE_RESULT
"""
if isinstance(value, datetime):
if in_nanoseconds_window(value):
tu = "ns"
else:
tu = "ms"
return (lit(_datetime_to_pl_timestamp(
value, tu)).cast(Datetime).dt.and_time_unit(tu))
if isinstance(value, timedelta):
if timedelta_in_nanoseconds_window(value):
tu = "ns"
else:
tu = "ms"
return (lit(_timedelta_to_pl_timedelta(
value, tu)).cast(Duration).dt.and_time_unit(tu, dtype=Duration))
if isinstance(value, date):
return lit(datetime(value.year, value.month, value.day)).cast(Date)
if isinstance(value, pli.Series):
name = value.name
value = value._s
e = pli.wrap_expr(pylit(value))
if name == "":
return e
return e.alias(name)
if _NUMPY_AVAILABLE and isinstance(value, np.ndarray):
return lit(pli.Series("", value))
if dtype:
return pli.wrap_expr(pylit(value)).cast(dtype)
# numpy literals like np.float32(0)
# have an item
if hasattr(value, "item"):
value = value.item() # type: ignore[union-attr]
return pli.wrap_expr(pylit(value))
def lit(
value: Optional[Union[float, int, str, date, datetime, "pli.Series"]],
dtype: Optional[Type[DataType]] = None,
) -> "pli.Expr":
"""
A literal value.
Parameters
----------
value
Value that should be used as a `literal`.
dtype
Optionally define a dtype.
Examples
--------
Literal integer:
>>> pl.lit(1) # doctest: +IGNORE_RESULT
Literal str:
>>> pl.lit("foo") # doctest: +IGNORE_RESULT
Literal datetime:
>>> from datetime import datetime
>>> pl.lit(datetime(2021, 1, 20)) # doctest: +IGNORE_RESULT
Literal Null:
>>> pl.lit(None) # doctest: +IGNORE_RESULT
Literal eager Series:
>>> pl.lit(pl.Series("a", [1, 2, 3])) # doctest: +IGNORE_RESULT
"""
if isinstance(value, datetime):
if in_nanoseconds_window(value):
tu = "ns"
else:
tu = "ms"
return (lit(_datetime_to_pl_timestamp(
value, tu)).cast(Datetime).dt.and_time_unit(tu))
if isinstance(value, timedelta):
if timedelta_in_nanoseconds_window(value):
tu = "ns"
else:
tu = "ms"
return (lit(_timedelta_to_pl_timedelta(
value, tu)).cast(Duration).dt.and_time_unit(tu, dtype=Duration))
if isinstance(value, date):
return lit(datetime(value.year, value.month, value.day)).cast(Date)
if isinstance(value, pli.Series):
name = value.name
value = value._s
return pli.wrap_expr(pylit(value)).alias(name)
if isinstance(value, np.ndarray):
return lit(pli.Series("", value))
if dtype:
return pli.wrap_expr(pylit(value)).cast(dtype)
return pli.wrap_expr(pylit(value))