polars-runtime-compat 1.34.0b2__cp39-abi3-win_arm64.whl

polars/functions/range/linear_space.py

@@ -0,0 +1,311 @@
+from __future__ import annotations
+
+import contextlib
+from typing import TYPE_CHECKING, overload
+
+from polars import functions as F
+from polars._utils.parse import parse_into_expression
+from polars._utils.unstable import unstable
+from polars._utils.wrap import wrap_expr
+
+with contextlib.suppress(ImportError):  # Module not available when building docs
+    import polars._plr as plr
+
+from typing import Literal
+
+if TYPE_CHECKING:
+    from polars import Expr, Series
+    from polars._typing import (
+        ClosedInterval,
+        IntoExpr,
+        IntoExprColumn,
+        NumericLiteral,
+        TemporalLiteral,
+    )
+
+
+@overload
+def linear_space(
+    start: NumericLiteral | TemporalLiteral | IntoExpr,
+    end: NumericLiteral | TemporalLiteral | IntoExpr,
+    num_samples: int | IntoExpr,
+    *,
+    closed: ClosedInterval = ...,
+    eager: Literal[False] = ...,
+) -> Expr: ...
+
+
+@overload
+def linear_space(
+    start: NumericLiteral | TemporalLiteral | IntoExpr,
+    end: NumericLiteral | TemporalLiteral | IntoExpr,
+    num_samples: int | IntoExpr,
+    *,
+    closed: ClosedInterval = ...,
+    eager: Literal[True],
+) -> Series: ...
+
+
+@overload
+def linear_space(
+    start: NumericLiteral | TemporalLiteral | IntoExpr,
+    end: NumericLiteral | TemporalLiteral | IntoExpr,
+    num_samples: int | IntoExpr,
+    *,
+    closed: ClosedInterval = ...,
+    eager: bool,
+) -> Expr | Series: ...
+
+
+@unstable()
+def linear_space(
+    start: NumericLiteral | TemporalLiteral | IntoExpr,
+    end: NumericLiteral | TemporalLiteral | IntoExpr,
+    num_samples: int | IntoExpr,
+    *,
+    closed: ClosedInterval = "both",
+    eager: bool = False,
+) -> Expr | Series:
+    """
+    Create sequence of evenly-spaced points.
+
+    Parameters
+    ----------
+    start
+        Lower bound of the range.
+    end
+        Upper bound of the range.
+    num_samples
+        Number of samples in the output sequence.
+    closed : {'both', 'left', 'right', 'none'}
+        Define which sides of the interval are closed (inclusive).
+    eager
+        Evaluate immediately and return a `Series`.
+        If set to `False` (default), return an expression instead.
+
+    .. warning::
+        This functionality is experimental. It may be changed at any point without it
+        being considered a breaking change.
+
+    Notes
+    -----
+    `linear_space` works with numeric and temporal dtypes. When the `start` and `end`
+    parameters are `Date` dtypes, the output sequence consists of equally-spaced
+    `Datetime` elements with millisecond precision.
+
+    Returns
+    -------
+    Expr or Series
+        Column of data type `:class:Time`.
+
+    Examples
+    --------
+    >>> pl.linear_space(start=0, end=1, num_samples=3, eager=True)
+    shape: (3,)
+    Series: 'literal' [f64]
+    [
+            0.0
+            0.5
+            1.0
+    ]
+    >>> pl.linear_space(start=0, end=1, num_samples=3, closed="left", eager=True)
+    shape: (3,)
+    Series: 'literal' [f64]
+    [
+            0.0
+            0.333333
+            0.666667
+    ]
+    >>> pl.linear_space(start=0, end=1, num_samples=3, closed="right", eager=True)
+    shape: (3,)
+    Series: 'literal' [f64]
+    [
+            0.333333
+            0.666667
+            1.0
+    ]
+    >>> pl.linear_space(start=0, end=1, num_samples=3, closed="none", eager=True)
+    shape: (3,)
+    Series: 'literal' [f64]
+    [
+            0.25
+            0.5
+            0.75
+    ]
+    >>> from datetime import time
+    >>> pl.linear_space(
+    ...     start=time(hour=1), end=time(hour=12), num_samples=3, eager=True
+    ... )
+    shape: (3,)
+    Series: 'literal' [time]
+    [
+            01:00:00
+            06:30:00
+            12:00:00
+    ]
+
+    `Date` endpoints generate a sequence of `Datetime` values:
+
+    >>> from datetime import date
+    >>> pl.linear_space(
+    ...     start=date(2025, 1, 1),
+    ...     end=date(2025, 2, 1),
+    ...     num_samples=3,
+    ...     closed="right",
+    ...     eager=True,
+    ... )
+    shape: (3,)
+    Series: 'literal' [datetime[μs]]
+    [
+            2025-01-11 08:00:00
+            2025-01-21 16:00:00
+            2025-02-01 00:00:00
+    ]
+
+    When `eager=False` (default), an expression is produced. You can generate a sequence
+    using the length of the dataframe:
+
+    >>> df = pl.DataFrame({"a": [1, 2, 3, 4, 5]})
+    >>> df.with_columns(pl.linear_space(0, 1, pl.len()).alias("ls"))
+    shape: (5, 2)
+    ┌─────┬──────┐
+    │ a   ┆ ls   │
+    │ --- ┆ ---  │
+    │ i64 ┆ f64  │
+    ╞═════╪══════╡
+    │ 1   ┆ 0.0  │
+    │ 2   ┆ 0.25 │
+    │ 3   ┆ 0.5  │
+    │ 4   ┆ 0.75 │
+    │ 5   ┆ 1.0  │
+    └─────┴──────┘
+    """
+    start_pyexpr = parse_into_expression(start)
+    end_pyexpr = parse_into_expression(end)
+    num_samples_pyexpr = parse_into_expression(num_samples)
+    result = wrap_expr(
+        plr.linear_space(start_pyexpr, end_pyexpr, num_samples_pyexpr, closed)
+    )
+
+    if eager:
+        return F.select(result).to_series()
+
+    return result
+
+
+@overload
+def linear_spaces(
+    start: NumericLiteral | TemporalLiteral | IntoExprColumn,
+    end: NumericLiteral | TemporalLiteral | IntoExprColumn,
+    num_samples: int | IntoExprColumn,
+    *,
+    closed: ClosedInterval = ...,
+    as_array: bool = ...,
+    eager: Literal[False] = ...,
+) -> Expr: ...
+
+
+@overload
+def linear_spaces(
+    start: NumericLiteral | TemporalLiteral | IntoExprColumn,
+    end: NumericLiteral | TemporalLiteral | IntoExprColumn,
+    num_samples: int | IntoExprColumn,
+    *,
+    closed: ClosedInterval = ...,
+    as_array: bool = ...,
+    eager: Literal[True],
+) -> Series: ...
+
+
+@overload
+def linear_spaces(
+    start: NumericLiteral | TemporalLiteral | IntoExprColumn,
+    end: NumericLiteral | TemporalLiteral | IntoExprColumn,
+    num_samples: int | IntoExprColumn,
+    *,
+    closed: ClosedInterval = ...,
+    as_array: bool = ...,
+    eager: bool,
+) -> Expr | Series: ...
+
+
+def linear_spaces(
+    start: NumericLiteral | TemporalLiteral | IntoExprColumn,
+    end: NumericLiteral | TemporalLiteral | IntoExprColumn,
+    num_samples: int | IntoExprColumn,
+    *,
+    closed: ClosedInterval = "both",
+    as_array: bool = False,
+    eager: bool = False,
+) -> Expr | Series:
+    """
+    Generate a sequence of evenly-spaced values for each row between `start` and `end`.
+
+    The number of values in each sequence is determined by `num_samples`.
+
+    Parameters
+    ----------
+    start
+        Lower bound of the range.
+    end
+        Upper bound of the range.
+    num_samples
+        Number of samples in the output sequence.
+    closed : {'both', 'left', 'right', 'none'}
+        Define which sides of the interval are closed (inclusive).
+    as_array
+        Return result as a fixed-length `Array`. `num_samples` must be a constant.
+    eager
+        Evaluate immediately and return a `Series`.
+        If set to `False` (default), return an expression instead.
+
+    .. warning::
+        This functionality is experimental. It may be changed at any point without it
+        being considered a breaking change.
+
+    Returns
+    -------
+    Expr or Series
+        Column of data type `List(dtype)`.
+
+    See Also
+    --------
+    linear_space : Generate a single sequence of linearly-spaced values.
+
+    Examples
+    --------
+    >>> df = pl.DataFrame({"start": [1, -1], "end": [3, 2], "num_samples": [4, 5]})
+    >>> df.with_columns(ls=pl.linear_spaces("start", "end", "num_samples"))
+    shape: (2, 4)
+    ┌───────┬─────┬─────────────┬────────────────────────┐
+    │ start ┆ end ┆ num_samples ┆ ls                     │
+    │ ---   ┆ --- ┆ ---         ┆ ---                    │
+    │ i64   ┆ i64 ┆ i64         ┆ list[f64]              │
+    ╞═══════╪═════╪═════════════╪════════════════════════╡
+    │ 1     ┆ 3   ┆ 4           ┆ [1.0, 1.666667, … 3.0] │
+    │ -1    ┆ 2   ┆ 5           ┆ [-1.0, -0.25, … 2.0]   │
+    └───────┴─────┴─────────────┴────────────────────────┘
+    >>> df.with_columns(ls=pl.linear_spaces("start", "end", 3, as_array=True))
+    shape: (2, 4)
+    ┌───────┬─────┬─────────────┬──────────────────┐
+    │ start ┆ end ┆ num_samples ┆ ls               │
+    │ ---   ┆ --- ┆ ---         ┆ ---              │
+    │ i64   ┆ i64 ┆ i64         ┆ array[f64, 3]    │
+    ╞═══════╪═════╪═════════════╪══════════════════╡
+    │ 1     ┆ 3   ┆ 4           ┆ [1.0, 2.0, 3.0]  │
+    │ -1    ┆ 2   ┆ 5           ┆ [-1.0, 0.5, 2.0] │
+    └───────┴─────┴─────────────┴──────────────────┘
+    """
+    start_pyexpr = parse_into_expression(start)
+    end_pyexpr = parse_into_expression(end)
+    num_samples_pyexpr = parse_into_expression(num_samples)
+    result = wrap_expr(
+        plr.linear_spaces(
+            start_pyexpr, end_pyexpr, num_samples_pyexpr, closed, as_array
+        )
+    )
+
+    if eager:
+        return F.select(result).to_series()
+
+    return result

polars/functions/range/time_range.py

@@ -0,0 +1,287 @@
+from __future__ import annotations
+
+import contextlib
+from datetime import time
+from typing import TYPE_CHECKING, overload
+
+from polars import functions as F
+from polars._utils.parse import parse_into_expression
+from polars._utils.wrap import wrap_expr
+from polars.functions.range._utils import parse_interval_argument
+
+with contextlib.suppress(ImportError):  # Module not available when building docs
+    import polars._plr as plr
+
+if TYPE_CHECKING:
+    from datetime import timedelta
+    from typing import Literal
+
+    from polars import Expr, Series
+    from polars._typing import ClosedInterval, IntoExprColumn
+
+
+@overload
+def time_range(
+    start: time | IntoExprColumn | None = ...,
+    end: time | IntoExprColumn | None = ...,
+    interval: str | timedelta = ...,
+    *,
+    closed: ClosedInterval = ...,
+    eager: Literal[False] = ...,
+) -> Expr: ...
+
+
+@overload
+def time_range(
+    start: time | IntoExprColumn | None = ...,
+    end: time | IntoExprColumn | None = ...,
+    interval: str | timedelta = ...,
+    *,
+    closed: ClosedInterval = ...,
+    eager: Literal[True],
+) -> Series: ...
+
+
+@overload
+def time_range(
+    start: time | IntoExprColumn | None = ...,
+    end: time | IntoExprColumn | None = ...,
+    interval: str | timedelta = ...,
+    *,
+    closed: ClosedInterval = ...,
+    eager: bool,
+) -> Series | Expr: ...
+
+
+def time_range(
+    start: time | IntoExprColumn | None = None,
+    end: time | IntoExprColumn | None = None,
+    interval: str | timedelta = "1h",
+    *,
+    closed: ClosedInterval = "both",
+    eager: bool = False,
+) -> Series | Expr:
+    """
+    Generate a time range.
+
+    Parameters
+    ----------
+    start
+        Lower bound of the time range.
+        If omitted, defaults to `time(0,0,0,0)`.
+    end
+        Upper bound of the time range.
+        If omitted, defaults to `time(23,59,59,999999)`.
+    interval
+        Interval of the range periods, specified as a Python `timedelta` object
+        or using the Polars duration string language (see "Notes" section below).
+    closed : {'both', 'left', 'right', 'none'}
+        Define which sides of the range are closed (inclusive).
+    eager
+        Evaluate immediately and return a `Series`.
+        If set to `False` (default), return an expression instead.
+
+    Returns
+    -------
+    Expr or Series
+        Column of data type `:class:Time`.
+
+    Notes
+    -----
+    `interval` is created according to the following string language:
+
+    - 1ns   (1 nanosecond)
+    - 1us   (1 microsecond)
+    - 1ms   (1 millisecond)
+    - 1s    (1 second)
+    - 1m    (1 minute)
+    - 1h    (1 hour)
+    - 1d    (1 calendar day)
+    - 1w    (1 calendar week)
+    - 1mo   (1 calendar month)
+    - 1q    (1 calendar quarter)
+    - 1y    (1 calendar year)
+
+    Or combine them:
+    "3d12h4m25s" # 3 days, 12 hours, 4 minutes, and 25 seconds
+
+    By "calendar day", we mean the corresponding time on the next day (which may
+    not be 24 hours, due to daylight savings). Similarly for "calendar week",
+    "calendar month", "calendar quarter", and "calendar year".
+
+    See Also
+    --------
+    time_ranges : Create a column of time ranges.
+
+    Examples
+    --------
+    >>> from datetime import time, timedelta
+    >>> pl.time_range(
+    ...     start=time(14, 0),
+    ...     interval=timedelta(hours=3, minutes=15),
+    ...     eager=True,
+    ... ).alias("time")
+    shape: (4,)
+    Series: 'time' [time]
+    [
+        14:00:00
+        17:15:00
+        20:30:00
+        23:45:00
+    ]
+    """
+    interval = parse_interval_argument(interval)
+    for unit in ("y", "mo", "w", "d"):
+        if unit in interval:
+            msg = f"invalid interval unit for time_range: found {unit!r}"
+            raise ValueError(msg)
+
+    if start is None:
+        start = time(0, 0, 0)
+    if end is None:
+        end = time(23, 59, 59, 999999)
+
+    start_pyexpr = parse_into_expression(start)
+    end_pyexpr = parse_into_expression(end)
+
+    result = wrap_expr(plr.time_range(start_pyexpr, end_pyexpr, interval, closed))
+
+    if eager:
+        return F.select(result).to_series()
+
+    return result
+
+
+@overload
+def time_ranges(
+    start: time | IntoExprColumn | None = ...,
+    end: time | IntoExprColumn | None = ...,
+    interval: str | timedelta = ...,
+    *,
+    closed: ClosedInterval = ...,
+    eager: Literal[False] = ...,
+) -> Expr: ...
+
+
+@overload
+def time_ranges(
+    start: time | IntoExprColumn | None = ...,
+    end: time | IntoExprColumn | None = ...,
+    interval: str | timedelta = ...,
+    *,
+    closed: ClosedInterval = ...,
+    eager: Literal[True],
+) -> Series: ...
+
+
+@overload
+def time_ranges(
+    start: time | IntoExprColumn | None = ...,
+    end: time | IntoExprColumn | None = ...,
+    interval: str | timedelta = ...,
+    *,
+    closed: ClosedInterval = ...,
+    eager: bool,
+) -> Series | Expr: ...
+
+
+def time_ranges(
+    start: time | IntoExprColumn | None = None,
+    end: time | IntoExprColumn | None = None,
+    interval: str | timedelta = "1h",
+    *,
+    closed: ClosedInterval = "both",
+    eager: bool = False,
+) -> Series | Expr:
+    """
+    Create a column of time ranges.
+
+    Parameters
+    ----------
+    start
+        Lower bound of the time range.
+        If omitted, defaults to `time(0, 0, 0, 0)`.
+    end
+        Upper bound of the time range.
+        If omitted, defaults to `time(23, 59, 59, 999999)`.
+    interval
+        Interval of the range periods, specified as a Python `timedelta` object
+        or using the Polars duration string language (see "Notes" section below).
+    closed : {'both', 'left', 'right', 'none'}
+        Define which sides of the range are closed (inclusive).
+    eager
+        Evaluate immediately and return a `Series`.
+        If set to `False` (default), return an expression instead.
+
+    Returns
+    -------
+    Expr or Series
+        Column of data type `List(Time)`.
+
+    Notes
+    -----
+    `interval` is created according to the following string language:
+
+    - 1ns   (1 nanosecond)
+    - 1us   (1 microsecond)
+    - 1ms   (1 millisecond)
+    - 1s    (1 second)
+    - 1m    (1 minute)
+    - 1h    (1 hour)
+    - 1d    (1 calendar day)
+    - 1w    (1 calendar week)
+    - 1mo   (1 calendar month)
+    - 1q    (1 calendar quarter)
+    - 1y    (1 calendar year)
+
+    Or combine them:
+    "3d12h4m25s" # 3 days, 12 hours, 4 minutes, and 25 seconds
+
+    By "calendar day", we mean the corresponding time on the next day (which may
+    not be 24 hours, due to daylight savings). Similarly for "calendar week",
+    "calendar month", "calendar quarter", and "calendar year".
+
+    See Also
+    --------
+    time_range : Generate a single time range.
+
+    Examples
+    --------
+    >>> from datetime import time
+    >>> df = pl.DataFrame(
+    ...     {
+    ...         "start": [time(9, 0), time(10, 0)],
+    ...         "end": time(11, 0),
+    ...     }
+    ... )
+    >>> df.with_columns(time_range=pl.time_ranges("start", "end"))
+    shape: (2, 3)
+    ┌──────────┬──────────┬────────────────────────────────┐
+    │ start    ┆ end      ┆ time_range                     │
+    │ ---      ┆ ---      ┆ ---                            │
+    │ time     ┆ time     ┆ list[time]                     │
+    ╞══════════╪══════════╪════════════════════════════════╡
+    │ 09:00:00 ┆ 11:00:00 ┆ [09:00:00, 10:00:00, 11:00:00] │
+    │ 10:00:00 ┆ 11:00:00 ┆ [10:00:00, 11:00:00]           │
+    └──────────┴──────────┴────────────────────────────────┘
+    """
+    interval = parse_interval_argument(interval)
+    for unit in ("y", "mo", "w", "d"):
+        if unit in interval:
+            msg = f"invalid interval unit for time_range: found {unit!r}"
+            raise ValueError(msg)
+
+    if start is None:
+        start = time(0, 0, 0)
+    if end is None:
+        end = time(23, 59, 59, 999999)
+
+    start_pyexpr = parse_into_expression(start)
+    end_pyexpr = parse_into_expression(end)
+
+    result = wrap_expr(plr.time_ranges(start_pyexpr, end_pyexpr, interval, closed))
+
+    if eager:
+        return F.select(result).to_series()
+
+    return result