Polars utils module

def datetime_to_isoweek(series: ExprOrSeries, offset: OffsetType = timedelta(days=0)) -> ExprOrSeries:
    """Converts `date(time)` `series/expr` to `str` values representing ISO Week format YYYY-WNN.

    Arguments:
        series: series or expr of `date` or `datetime` values
        offset: offset in days or `timedelta`. It represents how many days to add to the date before converting to ISO
            Week, it can be negative

    Returns:
        Series or Expr with converted ISO Week values (in format YYYY-WNN)

    Raises:
        TypeError: If any of the following condition is met:

            * `series` is not of type `pl.Series` or `pl.Expr`
            * `offset` is not of type `timedelta` or `int`

    Examples:
        >>> from datetime import date, timedelta
        >>> import polars as pl
        >>> from iso_week_date.polars_utils import datetime_to_isoweek
        >>>
        >>> s = pl.date_range(date(2023, 1, 1), date(2023, 1, 5), interval="1d", eager=True)
        >>> datetime_to_isoweek(s, offset=timedelta(days=1))  # doctest: +NORMALIZE_WHITESPACE
        shape: (5,)
        Series: 'literal' [str]
        [
           "2022-W52"
           "2022-W52"
           "2023-W01"
           "2023-W01"
           "2023-W01"
        ]
        >>> df = pl.DataFrame({"date": s})
        >>> df.select(datetime_to_isoweek(pl.col("date"), offset=1))
        shape: (5, 1)
        ┌──────────┐
        │ date     │
        │ ---      │
        │ str      │
        ╞══════════╡
        │ 2022-W52 │
        │ 2022-W52 │
        │ 2023-W01 │
        │ 2023-W01 │
        │ 2023-W01 │
        └──────────┘
    """
    return _datetime_to_format(series, offset, ISOWEEK__DATE_FORMAT)

def datetime_to_isoweekdate(series: ExprOrSeries, offset: OffsetType = timedelta(days=0)) -> ExprOrSeries:
    """Converts `date(time)` `series/expr`  to `str` values representing ISO Week date format YYYY-WNN-D.

    Arguments:
        series: series or expr of `date` or `datetime` values
        offset: offset in days or `timedelta`. It represents how many days to add to the date before converting to ISO
            Week, it can be negative

    Returns:
        Series or Expr with converted ISO Week values (in format YYYY-WNN-D)

    Raises:
        TypeError: If any of the following condition is met:

            * `series` is not of type `pl.Series` or `pl.Expr`
            * `offset` is not of type `timedelta` or `int`

    Examples:
        >>> from datetime import date, timedelta
        >>> import polars as pl
        >>> from iso_week_date.polars_utils import datetime_to_isoweekdate
        >>>
        >>> s = pl.date_range(date(2023, 1, 1), date(2023, 1, 5), interval="1d", eager=True)
        >>> datetime_to_isoweekdate(s, offset=timedelta(days=1))  # doctest: +NORMALIZE_WHITESPACE
        shape: (5,)
        Series: 'literal' [str]
        [
           "2022-W52-6"
           "2022-W52-7"
           "2023-W01-1"
           "2023-W01-2"
           "2023-W01-3"
        ]
        >>> df = pl.DataFrame({"date": s})
        >>> df.select(datetime_to_isoweekdate(pl.col("date"), offset=1))
        shape: (5, 1)
        ┌────────────┐
        │ date       │
        │ ---        │
        │ str        │
        ╞════════════╡
        │ 2022-W52-6 │
        │ 2022-W52-7 │
        │ 2023-W01-1 │
        │ 2023-W01-2 │
        │ 2023-W01-3 │
        └────────────┘
    """
    return _datetime_to_format(series, offset, ISOWEEKDATE__DATE_FORMAT)

def isoweek_to_datetime(
    series: ExprOrSeries,
    offset: OffsetType = timedelta(days=0),
    weekday: int = 1,
    *,
    strict: bool = True,
) -> ExprOrSeries:
    """Converts series or expr of `str` values in ISO Week format YYYY-WNN to a series or expr of `pl.Date` values.

    `offset` represents how many days to add to the date before converting to `pl.Date`, and it can be negative.

    `weekday` represents the weekday to use for conversion in ISO Week format (1-7), where 1 is the first day of the
    week, 7 is the last one.

    Arguments:
        series: Series or Expr of `str` values in ISO Week format.
        offset: Offset in days or `timedelta`. It represents how many days to add to the date before converting to
            IsoWeek, it can be negative.
        weekday: Weekday to use for conversion (1-7)
        strict: Raise an error if the values cannot be converted to datetime. Otherwise mask out with a null value.

    Returns:
        Series or Expr of converted date values

    Raises:
        TypeError: If any of the following condition is met:

            * `series` is not of type `pl.Series` or `pl.Expr`
            * `offset` is not of type `timedelta` or `int`
            * `weekday` is not of type `int` (`bool` is not accepted)
        ValueError: If `weekday` is not an integer between 1 and 7

    Examples:
        >>> from datetime import timedelta
        >>> import polars as pl
        >>> from iso_week_date.polars_utils import isoweek_to_datetime
        >>>
        >>> s = pl.Series(["2022-W52", "2023-W01", "2023-W02"])
        >>> isoweek_to_datetime(series=s, offset=timedelta(days=1))  # doctest: +NORMALIZE_WHITESPACE
        shape: (3,)
        Series: '' [date]
        [
            2022-12-27
            2023-01-03
            2023-01-10
        ]
    """
    if not isinstance(offset, (timedelta, int)):
        msg = f"`offset` must be of type `timedelta` or `int`, found {type(offset)}"
        raise TypeError(msg)

    # `bool` is excluded explicitly: `isinstance(True, int)` and `True in range(1, 8)` both hold, so
    # a bare range check would interpolate the literal string "True" into the value being parsed.
    if not isinstance(weekday, int) or isinstance(weekday, bool):
        msg = f"`weekday` must be an integer between 1 and 7, found {type(weekday)}"
        raise TypeError(msg)

    if weekday not in range(1, 8):
        msg = f"`weekday` value must be an integer between 1 and 7, found {weekday}"
        raise ValueError(msg)

    _offset = timedelta(days=offset) if isinstance(offset, int) else offset

    return (series + f"-{weekday}").str.strptime(pl.Date, ISOWEEKDATE__DATE_FORMAT, strict=strict) + _offset

def isoweekdate_to_datetime(
    series: ExprOrSeries,
    offset: OffsetType = timedelta(days=0),
    *,
    strict: bool = True,
) -> ExprOrSeries:
    """Converts `series/expr` of values in ISO Week date format YYYY-WNN-D to a series or expr of `pl.Date` values.

    `offset` represents how many days to add to the date before converting to `pl.Date`, and it can be negative.

    Arguments:
        series: Series or Expr of `str` values in ISO Week date format
        offset: Offset in days or `timedelta`. It represents how many days to add to the date before converting to
            IsoWeek, it can be negative
        strict: Raise an error if the values cannot be converted to datetime. Otherwise mask out with a null value.

    Returns:
        Series or Expr of converted date values

    Raises:
        TypeError: If any of the following condition is met:

            * `series` is not of type `pl.Series` or `pl.Expr`
            * `offset` is not of type `timedelta` or `int`

    Examples:
        >>> from datetime import timedelta
        >>> import polars as pl
        >>> from iso_week_date.polars_utils import isoweekdate_to_datetime
        >>>
        >>> s = pl.Series(["2022-W52-7", "2023-W01-1", "2023-W02-1"])
        >>> isoweekdate_to_datetime(series=s, offset=timedelta(days=1))  # doctest: +NORMALIZE_WHITESPACE
        shape: (3,)
        Series: '' [date]
        [
            2023-01-02
            2023-01-03
            2023-01-10
        ]
    """
    if not isinstance(offset, (timedelta, int)):
        msg = f"`offset` must be of type `timedelta` or `int`, found {type(offset)}"
        raise TypeError(msg)

    _offset = timedelta(days=offset) if isinstance(offset, int) else offset

    return series.str.strptime(pl.Date, ISOWEEKDATE__DATE_FORMAT, strict=strict) + _offset

def is_isoweek_series(series: pl.Series | pl.Expr) -> bool | pl.Expr:
    """Checks if a series or expr contains only values in ISO Week format.

    Arguments:
        series: series or expr of `str` values to check against "YYYY-WNN" pattern

    Returns:
        For a `pl.Series`, `True` if all values match ISO Week format and `False` otherwise. For a
            `pl.Expr`, a boolean `Expr` computing the same answer, to be used inside `select` /
            `filter`. An `Expr` is not a `bool`, so `if is_isoweek_series(expr):` raises on its
            ambiguous truth value.

    Raises:
        TypeError: If `series` is not of type `pl.Series` or `pl.Expr`

    Examples:
        >>> import polars as pl
        >>> from iso_week_date.polars_utils import is_isoweek_series
        >>>
        >>> s = pl.Series(["2022-W52", "2023-W01", "2023-W02"])
        >>> is_isoweek_series(s)
        True

        The `Expr` form answers inside a frame:

        >>> df = pl.DataFrame({"isoweek": ["2022-W52", "2023-W01"]})
        >>> df.select(is_isoweek=is_isoweek_series(pl.col("isoweek")))["is_isoweek"].item()
        True
    """
    return _match_series(series, ISOWEEK_PATTERN.pattern)

def is_isoweekdate_series(series: pl.Series | pl.Expr) -> bool | pl.Expr:
    """Checks if a series or expr contains only values in ISO Week date format.

    Arguments:
        series: series or expr of `str` values to check against "YYYY-WNN-D" pattern

    Returns:
        For a `pl.Series`, `True` if all values match ISO Week date format and `False` otherwise. For
            a `pl.Expr`, a boolean `Expr` computing the same answer, to be used inside `select` /
            `filter`. An `Expr` is not a `bool`, so `if is_isoweekdate_series(expr):` raises on its
            ambiguous truth value.

    Raises:
        TypeError: If `series` is not of type `pl.Series` or `pl.Expr`

    Examples:
        >>> import polars as pl
        >>> from iso_week_date.polars_utils import is_isoweekdate_series
        >>>
        >>> s = pl.Series(["2022-W52-1", "2023-W01-1", "2023-W02-1"])
        >>> is_isoweekdate_series(series=s)
        True

        The `Expr` form answers inside a frame:

        >>> df = pl.DataFrame({"isoweekdate": ["2022-W52-1", "2023-W01-1"]})
        >>> df.select(check=is_isoweekdate_series(pl.col("isoweekdate")))["check"].item()
        True
    """
    return _match_series(series, ISOWEEKDATE_PATTERN.pattern)