time-split 0.2.1__tar.gz → 0.3.0__tar.gz

{time_split-0.2.1 → time_split-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: time-split
-Version: 0.2.1
+Version: 0.3.0
 Summary: Time-based k-fold validation splits for heterogeneous data.
 Home-page: https://github.com/rsundqvist/time-split
 Author: Richard Sundqvist

{time_split-0.2.1 → time_split-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "time-split"
-version = "0.2.1"
+version = "0.3.0"
 description = "Time-based k-fold validation splits for heterogeneous data."
 authors = ["Richard Sundqvist <richard.sundqvist@live.se>"]
 
@@ -46,7 +46,7 @@ plotting = ["matplotlib", "seaborn"]
 [tool.poetry.group.manual-extras.dependencies]
 # Extras that must be available for docs + tests go here. Doc/test-only deps go in their respective groups.
 croniter = "^2.0.3"
-pyarrow = "^15.0.2"
+pyarrow = ">=15.0.2,<17.0.0"
 polars = { version = "^0.20.19", extras = ["pandas"] }
 
 [tool.poetry.group.docs]
@@ -55,9 +55,9 @@ polars = { version = "^0.20.19", extras = ["pandas"] }
 # description: https://github.com/astropy/astropy/issues/11723
 # https://github.com/astropy/astropy/pull/12270
 sphinx = "^7.2.6"
-sphinx-gallery = "^0.15.0"
+sphinx-gallery = "^0.16.0"
 pydata-sphinx-theme = "^0.15.2"
-myst-parser = "^2.0.0"
+myst-parser = ">=2,<4"
 nbsphinx = "^0.9.3"
 ipython = "^8.23.0"
 
@@ -80,12 +80,12 @@ scikit-learn = "^1.4.2"
 # dask.datasets.timeseries() warns:
 #     UserWarning: dask_expr does not support the DataFrameIOFunction protocol for column projection
 # on dask == 2024.3.1
-dask = { version = "==2024.4.1", extras = ["dataframe"] }
+dask = { version = "==2024.5.0", extras = ["dataframe"] }
 
 [tool.poetry.group.devops.dependencies]
 invoke = "^2.2.0"
 mypy = "^1.9.0"
-ruff = "^0.3.7"
+ruff = ">=0.3.7,<0.5.0"
 
 safety = "^3.1.0"
 codespell = "^2.2.6"

{time_split-0.2.1 → time_split-0.3.0}/src/time_split/__init__.py

@@ -11,6 +11,6 @@ __all__ = [
     "__version__",  # Make MyPy happy
 ]
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"
 
 _logging.getLogger(__name__).addHandler(_logging.NullHandler())

{time_split-0.2.1 → time_split-0.3.0}/src/time_split/_frontend/__init__.py

@@ -1,5 +1,5 @@
 from ._plot import plot
-from ._progress import log_split_progress
+from ._progress import default_metrics_formatter, log_split_progress
 from ._split import split
 from ._to_string import to_string
 from ._weight import fold_weight
@@ -7,6 +7,7 @@ from ._weight import fold_weight
 __all__ = [
     "fold_weight",
     "log_split_progress",
+    "default_metrics_formatter",
     "plot",
     "split",
     "to_string",

time_split-0.3.0/src/time_split/_frontend/_progress.py

@@ -0,0 +1,244 @@
+import logging
+from collections.abc import Callable, Iterable, MutableMapping, Sequence
+from dataclasses import dataclass
+from time import perf_counter
+from typing import Any, Generic
+
+import pandas as pd
+from rics.collections.dicts import flatten_dict
+from rics.performance import format_seconds
+
+from ..settings import log_split_progress as settings
+from ..types import DatetimeSplitBounds, FormatMetrics, GetMetrics, LoggerArg, MetricsType, SplitProgressExtras
+from ._to_string import _PrettyTimestamp
+
+
+def log_split_progress(
+    splits: Sequence[DatetimeSplitBounds],
+    *,
+    logger: LoggerArg = "time_split",
+    start_level: int = logging.INFO,
+    end_level: int = logging.INFO,
+    extra: dict[str, Any] | None = None,
+    get_metrics: GetMetrics[MetricsType] | None = None,
+) -> Iterable[DatetimeSplitBounds]:
+    """Log iteration progress.
+
+    Args:
+        splits: Splits to iterate over.
+        logger: Logger or logger name to use.
+        start_level: Log level to use for the :attr:`fold-begin message <.settings.log_split_progress.START_MESSAGE>`.
+        end_level: Log level to use for the :attr:`fold-end message <.settings.log_split_progress.END_MESSAGE>`.
+        extra: Immutable, user-defined `extra`-arguments to use when logging, merged with progress-related extras (see
+            :class:`~time_split.types.SplitProgressExtras`).
+        get_metrics: A callable ``(training_date) -> fold_metrics | str`` (see :attr:`~.DatetimeSplit.training_date`).
+            If given, metrics are added to the :attr:`fold-end message <.settings.log_split_progress.END_MESSAGE>`. The
+            message is formatted using the :func:`default formatter <.support.default_metrics_formatter>` unless
+            :attr:`~.settings.log_split_progress.FORMAT_METRICS` is set. If this callback returns a ``str`` argument,
+            the :func:`default formatter <.support.default_metrics_formatter>` will assume that the metrics are
+            pre-formatted, simply appending the formatted metrics to the
+            :attr:`fold-end message <.settings.log_split_progress.END_MESSAGE>` as-is.
+
+    Returns:
+        An iterable over `splits`.
+
+    Examples:
+        Configuring the `logger` name and
+        :attr:`fold-begin message <.settings.log_split_progress.START_MESSAGE>` log level.
+
+        >>> from time_split import split, log_split_progress
+        >>> schedule = ["2023-08-16", "2023-08-17 12", "2023-08-19"]
+        >>> tracked_splits = log_split_progress(
+        ...     split(schedule),
+        ...     logger="progress",
+        ...     start_level=logging.DEBUG,
+        ... )
+        >>> list(splits)  # doctest: +SKIP
+        [progress:DEBUG] Begin fold 1/2: '2023-08-09' <= [schedule: '2023-08-16' (Wednesday)] < '2023-08-17 12:00:00'.
+        [progress:INFO] Finished fold 1/2 [schedule: '2023-08-16' (Wednesday)] after 5m 18s.
+        [progress:DEBUG] Begin fold 2/2: '2023-08-10 12:00:00' <= [schedule: '2023-08-17 12:00:00' (Thursday)] < '2023-08-19'.
+        [progress:INFO] Finished fold 2/2 [schedule: '2023-08-17 12:00:00' (Thursday)] after 4m 3s.
+
+        Using the `get_metrics` callback argument.
+
+        >>> metrics = {
+        ...     "2023-08-16 00:00:00": {"rmse": {"train": 0.11, "test": 0.5}},
+        ...     "2023-08-17 12:00:00": {"rmse": {"test": 0.5, "future": 20.19}},
+        ... }
+        >>> tracked_splits = log_split_progress(
+        ...     split(schedule),
+        ...     get_metrics=lambda key: metrics[str(key)],
+        ... )
+        >>> list(tracked_splits)  # doctest: +SKIP
+        [time_split:INFO] Begin fold 1/2: '2023-08-09' <= [schedule: '2023-08-16' (Wednesday)] < '2023-08-17 12:00:00'.
+        [time_split:INFO] Finished fold 1/2 [schedule: '2023-08-16' (Wednesday)] after 5m 18s. Fold metrics:
+        rmse.train   0.11
+        rmse.test     0.5
+        [time_split:INFO] Begin fold 2/2: '2023-08-10 12:00:00' <= [schedule: '2023-08-17 12:00:00' (Thursday)] < '2023-08-19'.
+        [time_split:INFO] Finished fold 2/2 [schedule: '2023-08-17 12:00:00' (Thursday)] after 4m 3s. Fold metrics:
+        rmse.test       0.5
+        rmse.future   20.19
+
+        Formatting was done using the :func:`default formatter <.support.default_metrics_formatter>`, since the
+        :attr:`~.settings.log_split_progress.FORMAT_METRICS` setting is ``None``.
+
+    """
+    logger = logging.getLogger(logger) if isinstance(logger, str) else logger
+
+    if isinstance(logger, logging.LoggerAdapter) and not hasattr(logger, "merge_extra"):
+        # Backport of https://github.com/python/cpython/pull/107292
+        logger = _MergingLoggerAdapter(logger.logger, logger.extra)
+
+    track = _ProgressTracker(
+        logger=logger,
+        fold_format=settings.FOLD_FORMAT,
+        start_level=start_level,
+        start_message=settings.START_MESSAGE,
+        end_level=end_level,
+        end_message=settings.END_MESSAGE,
+        seconds_formatter=settings.SECONDS_FORMATTER or format_seconds,
+        user_extra={} if extra is None else extra.copy(),  # Not actually immutable; deepcopy can be very expensive.
+        get_metrics=get_metrics,
+        format_metrics=settings.FORMAT_METRICS or default_metrics_formatter,
+    )
+    return track(splits)
+
+
+@dataclass(frozen=True)
+class _ProgressTracker(Generic[MetricsType]):
+    logger: logging.Logger | logging.LoggerAdapter  # type: ignore[type-arg]
+    fold_format: str
+    start_level: int
+    start_message: str
+    end_level: int
+    end_message: str
+    seconds_formatter: Callable[[float], str]
+    user_extra: dict[str, Any]
+    get_metrics: GetMetrics[MetricsType] | None
+    format_metrics: FormatMetrics[MetricsType]
+
+    def __call__(self, splits: Sequence[DatetimeSplitBounds]) -> Iterable[DatetimeSplitBounds]:
+        n_splits = len(splits)
+
+        for n, split in enumerate(splits, start=1):
+            default_extras = SplitProgressExtras(
+                n=n,
+                n_splits=n_splits,
+                start=split.start.isoformat(),
+                mid=split.mid.isoformat(),
+                end=split.end.isoformat(),
+            )
+            extra = {**self.user_extra, **default_extras}
+            kwargs: dict[str, Any] = dict(
+                n=n,
+                n_splits=n_splits,
+                start=_PrettyTimestamp(split.start),
+                mid=_PrettyTimestamp(split.mid),
+                end=_PrettyTimestamp(split.end),
+                **self.user_extra,
+            )
+            kwargs.update(fold=self.fold_format.format(**kwargs))
+
+            self.logger.log(self.start_level, self.start_message.format(**kwargs), extra=extra)
+
+            # Yield split and count user time.
+            start = perf_counter()
+            yield split
+            seconds = round(perf_counter() - start, 6)
+
+            kwargs.update(
+                seconds=seconds,
+                formatted_seconds=self.seconds_formatter(seconds),
+            )
+            msg = self.end_message.format(**kwargs)
+
+            if self.get_metrics is not None:
+                extra["metrics"] = self.get_metrics(split.mid)
+                msg = self.format_metrics(msg, extra["metrics"])
+
+            extra.update(seconds=seconds)
+            self.logger.log(self.end_level, msg, extra=extra)
+
+
+def default_metrics_formatter(end_message: str, metrics: dict[Any, Any] | pd.Series | pd.DataFrame | str | Any) -> str:
+    """Default formatting implementation.
+
+    Format using an appropriate pandas ``to_string()``-method if `metrics` is a ``dict`` or a pandas type. Nested
+    dictionaries are flattened using :func:`~rics.collections.dicts.flatten_dict` if `metrics` is a dict-of-dicts.
+
+    Metrics of type ``str`` are assumed to be preformatted, and are appended to `end_message` as-is.
+
+    If any other types are given, fall back to
+    ``f"{end_message} Metrics: {metrics}"``.
+
+    Examples:
+        Formatting a nested dict.
+
+        >>> metrics = {"rmse": {"train": 0.11, "test": 0.5, "future": 20.19}}
+
+        >>> print(default_metrics_formatter("End message.", metrics))
+        End message. Fold metrics:
+              train  test  future
+        rmse   0.11   0.5   20.19
+
+        Formatting a :class:`pandas.DataFrame`.
+
+        >>> metrics = {"me": [0.1, 0.2, 0.3], "rmse": [0.11, 0.5, 20.19]}
+        >>> df = pd.DataFrame(metrics, index=["train", "test", "future"])
+        >>> print(default_metrics_formatter("End message.", df))
+        End message. Fold metrics:
+                 me   rmse
+        train   0.1   0.11
+        test    0.2   0.50
+        future  0.3  20.19
+
+        The index printed  unless` it is a :class:`pandas.RangeIndex`.
+    """
+    if isinstance(metrics, dict):
+        metrics = _convert_dict(metrics)
+
+    if isinstance(metrics, (pd.Series, pd.DataFrame)):
+        if isinstance(metrics, pd.DataFrame):
+            with_index = not isinstance(metrics, pd.RangeIndex)
+        else:
+            with_index = True
+        return f"{end_message} Fold metrics:\n{metrics.round(3).to_string(index=with_index)}"
+    elif isinstance(metrics, str):
+        return f"{end_message} {metrics}"
+    else:
+        return f"{end_message} Metrics: {metrics}"
+
+
+class _MergingLoggerAdapter(logging.LoggerAdapter[Any]):
+    # TODO(3.13): Use merge_extra=True init arg
+    def process(self, msg: Any, kwargs: MutableMapping[str, Any]) -> tuple[Any, MutableMapping[str, Any]]:
+        """See https://github.com/python/cpython/pull/107292."""
+        kwargs["extra"] = {**self.extra, **kwargs["extra"]} if "extra" in kwargs and self.extra else self.extra
+        return msg, kwargs
+
+
+def _convert_dict(metrics: dict[Any, Any]) -> dict[Any, Any] | pd.DataFrame | pd.Series:
+    original = metrics
+
+    scalar_leaves: bool = False
+
+    if all(isinstance(v, dict) for v in metrics.values()):
+        flat = flatten_dict(metrics)
+
+        # A single dot usually indicates nesting one level deep; can be formatted as a DataFrame.
+        if any(k.count(".") != 1 for k in flat) and all(pd.api.types.is_scalar(v) for v in flat.values()):
+            metrics = flat
+    elif all(pd.api.types.is_scalar(v) for v in original.values()):
+        scalar_leaves = True
+
+    try:
+        if scalar_leaves:
+            return pd.Series(metrics)
+
+        df = pd.DataFrame(metrics)
+    except Exception:
+        return original
+
+    if len(df) > len(df.columns):
+        df = df.T  # Prefer wider horizontal output
+    return df

{time_split-0.2.1 → time_split-0.3.0}/src/time_split/integration/_log_progress.py

@@ -1,18 +1,18 @@
 import logging
 from collections.abc import Iterable
-from typing import Any, Union
+from typing import Any
 
 from .. import log_split_progress
 from .._docstrings import add_docstrings
-from ..types import DatetimeSplitBounds, DatetimeSplits
+from ..types import DatetimeSplitBounds, DatetimeSplits, LogSplitProgressKwargs, MetricsType
 
-LogProgressArg = Union[str, bool, dict[str, Any], logging.Logger, logging.LoggerAdapter]  # type: ignore[type-arg]
+LogProgressArg = str | bool | logging.Logger | logging.LoggerAdapter[Any] | LogSplitProgressKwargs[MetricsType]
 
 add_docstrings(log_progress="Controls logging of fold progress. See :func:`~.log_split_progress` for details.")
 
 
 def handle_log_progress_arg(
-    log_progress: LogProgressArg, *, splits: DatetimeSplits
+    log_progress: LogProgressArg[MetricsType], *, splits: DatetimeSplits
 ) -> Iterable[DatetimeSplitBounds] | None:
     """Wrapper function for integrations."""
     if log_progress is True:

time_split-0.2.1/src/time_split/integration/split_data.py → time_split-0.3.0/src/time_split/integration/base.py

@@ -49,7 +49,7 @@ class DatetimeSplit(_t.NamedTuple, _t.Generic[DataT]):
 def split_data(
     data: DataT,
     *,
-    log_progress: _log_progress.LogProgressArg = False,
+    log_progress: _log_progress.LogProgressArg[_tst.MetricsType] = False,
     as_available: DataAsAvailableFn[DataT],
     select: DataSelectFn[DataT],
     **kwargs: _t.Unpack[_tst.DatetimeIndexSplitterKwargs],

{time_split-0.2.1 → time_split-0.3.0}/src/time_split/integration/pandas/_impl.py

@@ -6,9 +6,9 @@ from pandas import DataFrame, DatetimeIndex, Series, Timestamp
 from rics.misc import tname
 
 from ..._docstrings import docs
-from ...types import DatetimeIndexSplitterKwargs
+from ...types import DatetimeIndexSplitterKwargs, MetricsType
 from .._log_progress import LogProgressArg
-from ..split_data import DatetimeSplit, split_data
+from ..base import DatetimeSplit, split_data
 
 PandasT = TypeVar("PandasT", Series, DataFrame)
 """A splittable pandas type."""
@@ -19,7 +19,7 @@ def split_pandas(
     data: PandasT,
     time_column: Hashable = None,
     *,
-    log_progress: LogProgressArg = False,
+    log_progress: LogProgressArg[MetricsType] = False,
     **kwargs: Unpack[DatetimeIndexSplitterKwargs],
 ) -> Iterable[DatetimeSplit[PandasT]]:
     """Split a pandas type.

{time_split-0.2.1 → time_split-0.3.0}/src/time_split/integration/polars/_impl.py

@@ -6,9 +6,9 @@ from polars import DataFrame, Series
 from rics.misc import tname
 
 from ..._docstrings import docs
-from ...types import DatetimeIndexSplitterKwargs
+from ...types import DatetimeIndexSplitterKwargs, MetricsType
 from .._log_progress import LogProgressArg
-from ..split_data import DatetimeSplit, split_data
+from ..base import DatetimeSplit, split_data
 
 
 @docs
@@ -16,7 +16,7 @@ def split_polars(
     data: DataFrame,
     time_column: str,
     *,
-    log_progress: LogProgressArg = False,
+    log_progress: LogProgressArg[MetricsType] = False,
     **kwargs: Unpack[DatetimeIndexSplitterKwargs],
 ) -> Iterable[DatetimeSplit[DataFrame]]:
     """Split a polars frame.

{time_split-0.2.1 → time_split-0.3.0}/src/time_split/integration/sklearn/_impl.py

@@ -11,6 +11,7 @@ from ...types import (
     DatetimeSplits,
     DatetimeTypes,
     Flex,
+    MetricsType,
     Schedule,
     Span,
 )
@@ -60,7 +61,7 @@ class ScikitLearnSplitter(BaseCrossValidator):  # type: ignore[misc]
         n_splits: int = 0,
         flex: Flex = "auto",
         step: int = 1,
-        log_progress: LogProgressArg = False,
+        log_progress: LogProgressArg[MetricsType] = False,
         verify_xy: bool = True,
     ) -> None:
         super().__init__()

{time_split-0.2.1 → time_split-0.3.0}/src/time_split/settings.py

@@ -113,11 +113,10 @@ class log_split_progress:  # noqa: N801
        '2021-12-30' <= [schedule: '2022-01-04' (Tuesday)] < '2022-01-04 18:00:00'
     """
 
-    SECONDS_FORMATTER: str | _t.Callable[[float], str] = "rics.performance.format_seconds"
-    """A callable ``(seconds) -> formatted_seconds``.
+    SECONDS_FORMATTER: _t.Callable[[float], str] | None = None
+    """A callable ``(seconds) -> formatted_seconds``. Use :func:`rics.performance.format_seconds` if ``None``.
 
-    Both ``seconds`` and ``formatted_seconds`` will be available to the :attr:`END_MESSAGE` message. If a string is
-    given, the actual callable will be resolved using :func:`rics.misc.get_by_full_name`.
+    Both ``seconds`` and ``formatted_seconds`` will be available to the :attr:`END_MESSAGE` message.
     """
 
     START_MESSAGE: str = "Begin fold {n}/{n_splits}: {fold}."
@@ -156,6 +155,9 @@ class log_split_progress:  # noqa: N801
     AUTO_DATETIME_FORMAT = "%Y-%m-%d %H:%M:%S"
     """Long-form timestamp format_spec used by ``<key>.auto``."""
 
+    FORMAT_METRICS: _tst.FormatMetrics[_t.Any] | None = None
+    """A callable ``(end_message, metrics) -> str``. Use the :func:`default formatter <.support.default_metrics_formatter>` if ``None``."""
+
 
 class misc:  # noqa: N801
     """Miscellaneous settings that don't fit in any other namespace."""

{time_split-0.2.1 → time_split-0.3.0}/src/time_split/support/__init__.py

@@ -12,12 +12,13 @@ dependencies if you need to use the ``support`` module.
 """
 
 from .._backend import DatetimeIndexSplitter, expand_limits, process_available
-from .._frontend import fold_weight, to_string
+from .._frontend import default_metrics_formatter, fold_weight, to_string
 
 __all__ = [
     "DatetimeIndexSplitter",
     "expand_limits",
     "process_available",
+    "default_metrics_formatter",
     "fold_weight",
     "to_string",
 ]

{time_split-0.2.1 → time_split-0.3.0}/src/time_split/types.py

@@ -1,6 +1,7 @@
 """Types related to splitting data."""
 
 import datetime as _dt
+import logging as _logging
 import typing as _t
 
 import numpy as _np
@@ -62,3 +63,41 @@ class DatetimeIndexSplitterKwargs(_t.TypedDict, total=False):
     step: int
     n_splits: int
     flex: Flex
+
+
+LoggerArg = _logging.Logger | _logging.LoggerAdapter[_t.Any] | str
+
+
+MetricsType = _t.TypeVar("MetricsType")
+"""Metrics argument type."""
+GetMetrics = _t.Callable[[_pd.Timestamp], MetricsType]
+"""A callable ``(Timestamp) -> MetricsType``."""
+FormatMetrics = _t.Callable[[str, MetricsType], str]
+"""A callable ``(end_message, metrics) -> str``."""
+
+
+class LogSplitProgressKwargs(_t.TypedDict, _t.Generic[MetricsType], total=False):
+    """Keyword arguments for by :func:`.log_split_progress`."""
+
+    logger: LoggerArg
+    start_level: int
+    end_level: int
+    extra: dict[str, _t.Any] | None
+    get_metrics: GetMetrics[MetricsType]
+
+
+class SplitProgressExtras(_t.TypedDict):
+    """Named `extras` used for messages logged by :func:`.log_split_progress`."""
+
+    n: int
+    """Current split number (starting at 1)."""
+    n_splits: int
+    """Total split count."""
+    start: str
+    """An :meth:`ISO-formatted <pandas.Timestamp.isoformat>` timestamp (see :attr:`.DatetimeSplitBounds.start`)."""
+    mid: str
+    """An :meth:`ISO-formatted <pandas.Timestamp.isoformat>` timestamp (see :attr:`.DatetimeSplitBounds.mid`)."""
+    end: str
+    """An :meth:`ISO-formatted <pandas.Timestamp.isoformat>` timestamp (see :attr:`.DatetimeSplitBounds.end`)."""
+    seconds: _t.NotRequired[float]
+    """User time for the fold. Available only for the :attr:`fold-end message <.settings.log_split_progress.END_MESSAGE>`."""

time_split-0.2.1/src/time_split/_frontend/_progress.py

@@ -1,125 +0,0 @@
-import logging
-from collections.abc import Callable, Iterable, MutableMapping, Sequence
-from dataclasses import dataclass
-from time import perf_counter
-from typing import Any, Union
-
-from rics.misc import get_by_full_name
-
-from ..settings import log_split_progress as settings
-from ..types import DatetimeSplitBounds
-from ._to_string import _PrettyTimestamp
-
-LoggerArg = Union[logging.Logger, logging.LoggerAdapter, str]  # type: ignore[type-arg]
-
-
-def log_split_progress(
-    splits: Sequence[DatetimeSplitBounds],
-    *,
-    logger: LoggerArg = "time_split",
-    start_level: int = logging.INFO,
-    end_level: int = logging.INFO,
-    extra: dict[str, Any] | None = None,
-) -> Iterable[DatetimeSplitBounds]:
-    """Log iteration progress over `splits` using `logger`.
-
-    Args:
-        splits: Splits to iterate over.
-        logger: Logger or logger name to use.
-        start_level: Log level to use for the :attr:`fold-begin message <.settings.log_split_progress.START_MESSAGE>`.
-        end_level: Log level to use for the :attr:`fold-end message <.settings.log_split_progress.END_MESSAGE>`.
-        extra: User-defined `extra`-arguments to use when logging, merged with progress-related extras. Will be
-            available to all messages as well as the ``fold`` key. This argument is mutable; changes made to `extra`
-            will be reflected in logged records.
-
-    Returns:
-        An iterable over `splits`.
-
-    Examples:
-        Basic usage.
-
-        >>> from time_split import split, log_split_progress
-        >>> splits = split("36h", available=("2023-08-10", "2023-08-19"))
-        >>> tracked_splits = log_split_progress(
-        ...     splits, logger="progress", start_level=logging.DEBUG
-        ... )
-        >>> list(tracked_splits)  # doctest: +SKIP
-        [progress:DEBUG] Begin fold 1/2: ('2023-08-11' <= [schedule: '2023-08-16' (Wednesday)] < '2023-08-17 12:00:00').
-        [progress:INFO] Finished fold 1/2 [schedule: '2023-08-16' (Wednesday)] after 5m 18s.
-        [progress:DEBUG] Begin fold 2/2: ('2023-08-12 12:00:00' <= [schedule: '2023-08-17 12:00:00' (Thursday)] < '2023-08-19').
-        [progress:INFO] Finished fold 2/2 [schedule: '2023-08-17 12:00:00' (Thursday)] after 4m 3s.
-    """
-    logger = logging.getLogger(logger) if isinstance(logger, str) else logger
-
-    if isinstance(logger, logging.LoggerAdapter) and not hasattr(logger, "merge_extra"):
-        # Backport of https://github.com/python/cpython/pull/107292
-        logger = _MergingLoggerAdapter(logger.logger, logger.extra)
-
-    track = _ProgressTracker(
-        logger=logger,
-        fold_format=settings.FOLD_FORMAT,
-        start_level=start_level,
-        start_message=settings.START_MESSAGE,
-        end_level=end_level,
-        end_message=settings.END_MESSAGE,
-        seconds_formatter=settings.SECONDS_FORMATTER
-        if callable(settings.SECONDS_FORMATTER)
-        else get_by_full_name(settings.SECONDS_FORMATTER),
-        user_extra=extra or {},
-    )
-    return track(splits)
-
-
-@dataclass(frozen=True)
-class _ProgressTracker:
-    logger: logging.Logger | logging.LoggerAdapter  # type: ignore[type-arg]
-    fold_format: str
-    start_level: int
-    start_message: str
-    end_level: int
-    end_message: str
-    seconds_formatter: Callable[[float], str]
-    user_extra: dict[str, Any]
-
-    def __call__(self, splits: Sequence[DatetimeSplitBounds]) -> Iterable[DatetimeSplitBounds]:
-        n_splits = len(splits)
-
-        for n, split in enumerate(splits, start=1):
-            extra: dict[str, str | float | int | bool] = dict(
-                n=n,
-                n_splits=n_splits,
-                start=split.start.isoformat(),
-                mid=split.mid.isoformat(),
-                end=split.end.isoformat(),
-                **self.user_extra,
-            )
-            kwargs: dict[str, Any] = dict(
-                n=n,
-                n_splits=n_splits,
-                start=_PrettyTimestamp(split.start),
-                mid=_PrettyTimestamp(split.mid),
-                end=_PrettyTimestamp(split.end),
-                **self.user_extra,
-            )
-            kwargs.update(fold=self.fold_format.format(**kwargs))
-
-            self.logger.log(self.start_level, self.start_message.format(**kwargs), extra=extra)
-
-            # Yield split and count user time.
-            start = perf_counter()
-            yield split
-            seconds = round(perf_counter() - start, 6)
-
-            kwargs.update(
-                seconds=seconds,
-                formatted_seconds=self.seconds_formatter(seconds),
-            )
-            extra.update(seconds=seconds)
-            self.logger.log(self.end_level, self.end_message.format(**kwargs), extra=extra)
-
-
-class _MergingLoggerAdapter(logging.LoggerAdapter):  # type: ignore[type-arg]
-    def process(self, msg: Any, kwargs: MutableMapping[str, Any]) -> tuple[Any, MutableMapping[str, Any]]:
-        """See https://github.com/python/cpython/pull/107292."""
-        kwargs["extra"] = {**self.extra, **kwargs["extra"]} if "extra" in kwargs and self.extra else self.extra
-        return msg, kwargs