polars-runtime-compat 1.34.0b3__cp39-abi3-win_amd64.whl → 1.34.0b4__cp39-abi3-win_amd64.whl

polars/functions/range/linear_space.py

@@ -1,311 +0,0 @@
-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

@@ -1,287 +0,0 @@
-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