Pandas utils module

def datetime_to_isoweek(series: pd.Series[pd.Timestamp], offset: OffsetType = 0) -> pd.Series[str]:
    """Converts series of `date` or `datetime` values to `str` values representing ISO Week format YYYY-WNN.

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

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

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

            * `series` is not of type `pd.Series`
            * `series` values are not `datetime`-like
            * `offset` is not of type `pd.Timedelta` or `int`

    Examples:
        >>> from datetime import date
        >>> import pandas as pd
        >>> from iso_week_date.pandas_utils import datetime_to_isoweek
        >>>
        >>> s = pd.Series(pd.date_range(date(2023, 1, 1), date(2023, 1, 10), freq="1D"))
        >>> datetime_to_isoweek(series=s, offset=pd.Timedelta(days=1)).to_list()
        ['2022-W52', '2022-W52', '2023-W01',..., '2023-W01', '2023-W02']
    """
    return _datetime_to_format(series, offset, ISOWEEK__DATE_FORMAT)

def datetime_to_isoweekdate(series: pd.Series[pd.Timestamp], offset: OffsetType = 0) -> pd.Series[str]:
    """Converts series of `date` or `datetime` values to `str` values representing ISO Week date format YYYY-WNN-D.

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

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

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

            * `series` is not of type `pd.Series`
            * `series` values are not `datetime`-like
            * `offset` is not of type `pd.Timedelta` or `int`

    Examples:
        >>> from datetime import date
        >>> import pandas as pd
        >>> from iso_week_date.pandas_utils import datetime_to_isoweekdate
        >>>
        >>> s = pd.Series(pd.date_range(date(2023, 1, 1), date(2023, 1, 10), freq="1D"))
        >>> datetime_to_isoweekdate(series=s, offset=pd.Timedelta(days=1)).to_list()
        ['2022-W52-6', '2022-W52-7', '2023-W01-1',..., '2023-W01-7', '2023-W02-1']
    """
    return _datetime_to_format(series, offset, ISOWEEKDATE__DATE_FORMAT)

def isoweek_to_datetime(
    series: pd.Series[str],
    offset: OffsetType = 0,
    weekday: int = 1,
    *,
    strict: bool = True,
) -> pd.Series[pd.Timestamp]:
    """Converts series of `str` values in ISO Week format to a series of `datetime` values.

    `offset` represents how many days to add to the date before converting to datetime 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 of `str` values in ISO Week format.
        offset: Offset in days or pd.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 of converted datetime values

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

            * `series` is not of type `pd.Series`
            * `offset` is not of type `pd.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:
        >>> import pandas as pd
        >>> from iso_week_date.pandas_utils import isoweek_to_datetime
        >>>
        >>> s = pd.Series(["2022-W52", "2023-W01", "2023-W02"])
        >>> isoweek_to_datetime(series=s, offset=pd.Timedelta(days=1))  # doctest: +ELLIPSIS
        0   2022-12-27
        1   2023-01-03
        2   2023-01-10
        dtype: datetime64[...]
    """
    if not isinstance(offset, (pd.Timedelta, int)):
        msg = f"`offset` must be of type `pd.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: pd.Timedelta = pd.Timedelta(days=offset) if isinstance(offset, int) else offset
    errors: ErrorT = "raise" if strict else "coerce"
    return pd.to_datetime(series + f"-{weekday}", errors=errors, format=ISOWEEKDATE__DATE_FORMAT) + _offset  # pyrefly: ignore[unsupported-operation]

def isoweekdate_to_datetime(
    series: pd.Series[str],
    offset: OffsetType = 0,
    *,
    strict: bool = True,
) -> pd.Series[pd.Timestamp]:
    """Converts series of `str` values in ISO Week date format to a series of `datetime` values.

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

    Arguments:
        series: series of `str` in ISO Week date format.
        offset: offset in days or pd.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 of converted datetime values

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

            * `series` is not of type `pd.Series`
            * `offset` is not of type `pd.Timedelta` or `int`

    Examples:
        >>> import pandas as pd
        >>> from iso_week_date.pandas_utils import isoweekdate_to_datetime
        >>>
        >>> s = pd.Series(["2022-W52-1", "2023-W01-1", "2023-W02-1"])
        >>> isoweekdate_to_datetime(series=s, offset=pd.Timedelta(days=1))  # doctest: +ELLIPSIS
        0   2022-12-27
        1   2023-01-03
        2   2023-01-10
        dtype: datetime64[...]
    """
    if not isinstance(offset, (pd.Timedelta, int)):
        msg = f"`offset` must be of type `pd.Timedelta` or `int`, found {type(offset)}"
        raise TypeError(msg)

    _offset: pd.Timedelta = pd.Timedelta(days=offset) if isinstance(offset, int) else offset
    errors: ErrorT = "raise" if strict else "coerce"
    return pd.to_datetime(series, errors=errors, format=ISOWEEKDATE__DATE_FORMAT) + _offset

def is_isoweek_series(series: pd.Series[Any]) -> bool:
    """Checks if `series` contains only values in ISO Week format.

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

    Returns:
        `True` if all values match ISO Week format, `False` otherwise

    Raises:
        TypeError: If `series` is not of type `pd.Series`

    Examples:
        >>> import pandas as pd
        >>> from iso_week_date.pandas_utils import is_isoweek_series
        >>>
        >>> s = pd.Series(["2022-W52", "2023-W01", "2023-W02"])
        >>> is_isoweek_series(series=s)
        True
    """
    return _match_series(series, ISOWEEK_PATTERN.pattern)

def is_isoweekdate_series(series: pd.Series[Any]) -> bool:
    """Checks if `series` contains only values in ISO Week date format.

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

    Returns:
        `True` if all values match ISO Week date format, `False` otherwise

    Raises:
        TypeError: If `series` is not of type `pd.Series`

    Examples:
        >>> import pandas as pd
        >>> from iso_week_date.pandas_utils import is_isoweekdate_series
        >>> s = pd.Series(["2022-W52-1", "2023-W01-1", "2023-W02-1"])
        >>> is_isoweekdate_series(series=s)
        True
    """
    return _match_series(series, ISOWEEKDATE_PATTERN.pattern)