opencode-pyneruntime 6.6.4__py3-none-any.whl

pynecore/core/datetime.py

@@ -0,0 +1,296 @@
+import re
+import sys
+from zoneinfo import ZoneInfo
+from datetime import datetime, UTC
+from functools import cache, lru_cache
+
+# Standard formats for non-ISO dates
+# %b = abbreviated month (Jan, Feb), %B = full month (January, February)
+STANDARD_FORMATS = [
+    "%d %b %Y %H:%M:%S %z",  # "20 Feb 2020 15:30:00 +0200"
+    "%d %b %Y %H:%M %z",  # "01 Jan 2018 00:00 +0000"
+    "%d %B %Y %H:%M:%S %z",  # "20 February 2020 15:30:00 +0200"
+    "%d %B %Y %H:%M %z",  # "1 January 2018 00:00 +0000"
+    "%Y-%m-%d %H:%M:%S %z",  # "2021-01-01 00:00:00 +0000"
+    "%Y-%m-%d %H:%M %z",  # "2021-01-01 00:00 +0000"
+    "%m %d %Y %H:%M:%S %z",  # "05 12 2000 10:20:30 +0000" (month-first)
+    "%m %d %Y %H:%M %z",  # "01 1 2000 00:00 +0000" (month-first)
+    "%m %d %Y %z",  # "01 1 2000 +0000" (month-first)
+]
+
+# Pine Script specific formats (without timezone)
+# %b = abbreviated month (Jan, Feb), %B = full month (January, February)
+# Numeric dates are MONTH-FIRST (MM-DD-YYYY) with '-', '/', '.' or ' ' separators:
+# TradingView parses "03-04-2023" (and "05 12 2000") as March 4 / May 12 and
+# rejects a day-first "13-04-2023" ("31 1 2000") outright ("timestamp(s):
+# unrecognized datetime format"), so there is intentionally no day-first
+# fallback here.
+PINE_FORMATS = [
+    "%b %d %Y %H:%M:%S",  # "Feb 01 2020 22:10:05"
+    "%d %b %Y %H:%M:%S",  # "04 Dec 1995 00:12:00"
+    "%d %b %Y %H:%M",  # "01 Jan 2018 00:00"
+    "%b %d %Y",  # "Feb 01 2020"
+    "%d %b %Y",  # "04 Dec 1995"
+    "%B %d %Y %H:%M:%S",  # "February 01 2020 22:10:05"
+    "%d %B %Y %H:%M:%S",  # "04 December 1995 00:12:00"
+    "%d %B %Y %H:%M",  # "01 January 2018 00:00"
+    "%B %d %Y",  # "February 01 2020"
+    "%d %B %Y",  # "04 December 1995"
+    "%Y-%m-%d",  # "2020-02-20"
+    "%Y-%m-%d %H:%M:%S",  # "2021-01-01 00:00:00"
+    "%Y-%m-%d %H:%M",  # "2021-01-01 00:00"
+    "%m %d %Y %H:%M:%S",  # "05 12 2000 10:20:30"
+    "%m %d %Y %H:%M",  # "01 1 2000 00:00"
+    "%m %d %Y",  # "05 12 2000", "3 4 2023"
+    "%m-%d-%Y %H:%M:%S",  # "03-04-2023 10:20:30"
+    "%m-%d-%Y %H:%M",  # "03-04-2023 10:20"
+    "%m-%d-%Y",  # "03-04-2023", "3-4-2023"
+    "%m/%d/%Y %H:%M:%S",  # "03/04/2023 10:20:30"
+    "%m/%d/%Y %H:%M",  # "03/04/2023 10:20"
+    "%m/%d/%Y",  # "03/04/2023"
+    "%m.%d.%Y %H:%M:%S",  # "03.04.2023 10:20:30"
+    "%m.%d.%Y %H:%M",  # "03.04.2023 10:20"
+    "%m.%d.%Y",  # "03.04.2023"
+]
+
+
+def normalize_timezone(datestring: str) -> str:
+    """
+    Normalize timezone format to be compatible with Python's datetime.
+    Converts formats like "+00:00" to "+0000"
+
+    :param datestring: Input date string
+    :return: Normalized date string
+    """
+    tz_match = re.search(r'([+-])(\d{2}):(\d{2})(?:\s|$)', datestring)
+    if tz_match:
+        sign, hours, minutes = tz_match.groups()
+        new_tz = f"{sign}{hours}{minutes}"
+        return datestring[:tz_match.start()] + new_tz + datestring[tz_match.end():]
+    return datestring
+
+
+# Matches UTC/GMT±HHMM offset forms with optional colon: "UTC-5", "GMT+0530", "+05:30"
+_OFFSET_RE = re.compile(r'^(UTC|GMT)?([+-])(\d{1,2})(?::?(\d{2})?)?$')
+
+
+class TimezoneNotFoundError(ValueError):
+    """
+    Raised when a timezone string cannot be resolved to a ``ZoneInfo``.
+
+    Subclasses ``ValueError`` so existing ``except ValueError`` handlers keep
+    working, but is a distinct type so callers (e.g. :func:`pynecore.lib.time`)
+    can surface it as an actionable error instead of silently degrading to ``na``.
+    """
+
+
+@cache
+def _timezone_db_available() -> bool:
+    """
+    Return whether an IANA timezone database is reachable on this system.
+
+    Probes a canonical zone name. On Windows without the ``tzdata`` package and
+    without a system zoneinfo database, even standard names fail to resolve.
+
+    :return: True if standard IANA names can be resolved
+    """
+    try:
+        ZoneInfo("America/New_York")
+        return True
+    except Exception:  # noqa - any failure means the database is unusable
+        return False
+
+
+def _missing_timezone_message(timezone: str) -> str:
+    """
+    Build an actionable error message for an unresolved timezone when the IANA
+    database is missing.
+
+    :param timezone: The timezone string that could not be resolved
+    :return: Multi-line, platform-aware error message
+    """
+    lines = [
+        f"Timezone {timezone!r} could not be resolved: the IANA timezone database "
+        "is not available on this system.",
+        "",
+        "Install it with:",
+        "    pip install tzdata",
+    ]
+    if sys.platform.startswith("win"):
+        lines += [
+            "",
+            "Windows has no built-in timezone database, so the 'tzdata' package is "
+            "required. PyneCore's [cli] and [all] installs include it automatically.",
+        ]
+    return "\n".join(lines)
+
+
+@lru_cache(maxsize=128)
+def _parse_timezone_cached(timezone: str) -> ZoneInfo:
+    """
+    Parse a concrete, non-empty timezone string into a ZoneInfo object.
+
+    Kept separate from :func:`parse_timezone` so the cache is only ever keyed on
+    an explicit timezone string. The ``None`` -> exchange-timezone fallback must
+    NOT be cached: it resolves against the mutable ``syminfo.timezone`` global,
+    so a cached ``None`` entry would leak one script's timezone into the next run
+    in the same process.
+
+    :param timezone: Concrete timezone string (IANA name or UTC/GMT±HHMM offset)
+    :return: ZoneInfo object
+    :raises TimezoneNotFoundError: If the timezone cannot be resolved
+    """
+    # Try as IANA timezone first
+    try:
+        return ZoneInfo(timezone)
+    except KeyError:
+        # ZoneInfoNotFoundError is a KeyError subclass: the name is not in the IANA
+        # database. UTC/GMT±HHMM offset forms are parsed below; any other name is an
+        # IANA name whose lookup genuinely failed.
+        pass
+
+    # Parse UTC/GMT±HHMM offset format with optional colon
+    match = _OFFSET_RE.match(timezone)
+    if match is None:
+        # Not an offset form -> the timezone name could not be resolved. The most
+        # common cause is a missing IANA database (Windows ships none by default).
+        if not _timezone_db_available():
+            raise TimezoneNotFoundError(_missing_timezone_message(timezone))
+        raise TimezoneNotFoundError(
+            f"Unknown timezone {timezone!r}. Use a valid IANA name "
+            "(e.g. 'America/New_York') or a UTC/GMT±HHMM offset (e.g. 'UTC-5', 'GMT+0530')."
+        )
+
+    prefix, sign, hours, minutes = match.groups()
+    offset = int(hours)
+    if minutes:
+        offset += int(minutes) / 60
+
+    # UTC/GMT+X maps to Etc/GMT-X and vice versa
+    # Special case: offset 0 should use UTC directly
+    if offset == 0:
+        return ZoneInfo("UTC")
+    zone = f"Etc/GMT{'-' if sign == '+' else '+'}{int(abs(offset))}"
+    return ZoneInfo(zone)
+
+
+# Lazily bound to the ``lib.syminfo`` module on first use. Importing it at module
+# top would create a datetime <-> lib import cycle (lib pulls in timeframe, which
+# imports parse_timezone), so the reference is fetched once on the first fallback
+# call and reused -- keeping the hot path a plain attribute read with no per-call
+# import cost.
+_syminfo = None
+
+
+def parse_timezone(timezone: str | None) -> ZoneInfo:
+    """
+    Parse timezone string into ZoneInfo object. Supports:
+    - IANA timezone names (e.g. "America/New_York")
+    - UTC±HHMM format (e.g. "UTC-5", "UTC+0530")
+    - GMT±HHMM format (e.g. "GMT-5", "GMT+0530")
+    - Raw offset (e.g. "+0530", "-05:00")
+
+    When ``timezone`` is falsy the exchange timezone (``syminfo.timezone``) is
+    used, defaulting to UTC when that is unset too. This fallback value is read on
+    every call -- never cached -- so changing the active symbol's timezone takes
+    effect immediately instead of returning a previous run's cached zone.
+
+    :param timezone: Timezone string, or None to use the exchange timezone
+    :return: ZoneInfo object
+    :raises TimezoneNotFoundError: If the timezone cannot be resolved
+    """
+    if not timezone:
+        global _syminfo
+        if _syminfo is None:
+            from ..lib import syminfo
+            _syminfo = syminfo
+        timezone = _syminfo.timezone or 'UTC'
+    return _parse_timezone_cached(timezone)
+
+
+def parse_datestring(datestring: str) -> datetime:
+    """
+    Parse date string using multiple formats.
+    Handles ISO 8601 with microseconds and timezone offsets.
+    If no time is supplied, "00:00" is used.
+    If no timezone is supplied, GMT+0 is used.
+
+    :param datestring: Date string to parse
+    :return: Parsed datetime object
+    :raises ValueError: If the date format is invalid
+    """
+    datestring = datestring.strip()
+    if not datestring:
+        return datetime.now(UTC).replace(hour=0, minute=0, second=0, microsecond=0)
+
+    # Try parsing ISO 8601 style dates WITH TIME first (handles both T and space
+    # separator; seconds are optional -- "2021-01-01 00:00" is accepted too)
+    iso_match = re.match(
+        r'(\d{4}-\d{2}-\d{2}[T\s]\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?)'  # datetime part
+        r'([+-]\d{2}:\d{2})?$',  # timezone part
+        datestring
+    )
+    if iso_match:
+        dt_part, tz_part = iso_match.groups()
+        if tz_part:
+            datestring = normalize_timezone(datestring)
+            dt_str = datestring.replace(' ', 'T')  # Normalize to T for parsing
+            for fmt in ("%Y-%m-%dT%H:%M:%S.%f%z", "%Y-%m-%dT%H:%M:%S%z", "%Y-%m-%dT%H:%M%z"):
+                try:
+                    return datetime.strptime(dt_str, fmt)
+                except ValueError:
+                    continue
+        else:
+            dt_str = dt_part.replace(' ', 'T')
+            for fmt in ("%Y-%m-%dT%H:%M:%S.%f", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%dT%H:%M"):
+                try:
+                    return datetime.strptime(dt_str, fmt).replace(tzinfo=UTC)
+                except ValueError:
+                    continue
+
+    # Try parsing ISO 8601 DATE ONLY format (YYYY-MM-DD) before timezone extraction
+    # This prevents the timezone regex from incorrectly matching date parts like -09 in 2025-01-09
+    iso_date_match = re.match(r'^\d{4}-\d{2}-\d{2}$', datestring)
+    if iso_date_match:
+        dt = datetime.strptime(datestring, "%Y-%m-%d")
+        # Use exchange timezone (from syminfo) when no timezone is specified
+        default_tz = parse_timezone(None)  # This will return syminfo.timezone
+        return dt.replace(tzinfo=default_tz)
+
+    # Extract timezone if present at the end for other formats
+    # The regex requires whitespace before timezone to avoid matching date parts
+    tz_match = re.search(r'\s+((?:UTC|GMT)?[+-]\d{1,2}(?::?\d{2})?)\s*$', datestring)
+    if tz_match:
+        tz = parse_timezone(
+            f"UTC{tz_match.group(1)}" if not tz_match.group(1).startswith(('UTC', 'GMT')) else tz_match.group(1))
+        datestring = datestring[:tz_match.start()].strip()
+    else:
+        # Use exchange timezone (from syminfo) when no timezone is specified
+        tz = parse_timezone(None)  # This will return syminfo.timezone
+
+    # Try standard formats (with timezone)
+    if tz_match:
+        normalized = normalize_timezone(f"{datestring} {tz_match.group(1)}")
+        for fmt in STANDARD_FORMATS:
+            try:
+                return datetime.strptime(normalized, fmt)
+            except ValueError:
+                continue
+
+    # Try Pine formats (without timezone)
+    for fmt in PINE_FORMATS:
+        try:
+            dt = datetime.strptime(datestring, fmt)
+            return dt.replace(tzinfo=tz)
+        except ValueError:
+            continue
+
+    raise ValueError(
+        f"Invalid date format: {datestring}\n"
+        "Supported formats:\n"
+        "- ISO Style: '2020-02-20T15:30:00+02:00', '2025-01-01 01:23:45-05:00'\n"
+        "- With fraction: '2024-08-01T04:38:47.731215+00:00'\n"
+        "- RFC Style: '20 Feb 2020 15:30:00 GMT+0200', '1 January 2018 00:00 +0000'\n"
+        "- Simple Pine: 'Feb 01 2020 22:10:05', '1 January 2018', '2020-02-20'\n"
+        "- Numeric, month first: '01-01-2023', '03/04/2023', '03.04.2023 10:20:30'"
+    )

pynecore/core/download_info.py

@@ -0,0 +1,71 @@
+"""
+Persist the originating provider string of a download in the syminfo TOML.
+
+``pyne data download`` appends a ``[download]`` section to the ``.toml`` saved
+next to the ``.ohlcv`` file::
+
+    [download]
+    provider = "ccxt:BYBIT:BTC/USDT:USDT@1D"
+
+The provider string is the canonical CLI form, so the file can be re-downloaded
+or resumed without reconstructing it from ``SymInfo`` fields (``prefix`` and the
+flattened filename are both lossy). ``SymInfo.load_toml`` reads only the
+``[symbol]`` section, so older pynecore versions ignore this section;
+``SymInfo.save_toml`` preserves it verbatim when rewriting the file.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+__all__ = ['read_download_provider', 'write_download_provider', 'extract_download_section']
+
+# [download] up to (not including) the next section header or EOF
+_SECTION_RE = re.compile(r'(?ms)^\[download\][^\n]*\n.*?(?=^\[|\Z)')
+
+
+def read_download_provider(toml_path: Path) -> str | None:
+    """
+    Read the persisted provider string from a syminfo TOML.
+
+    :param toml_path: Path to the ``.toml`` next to the ``.ohlcv`` file.
+    :return: The provider string, or None if the file or section is missing
+        or unparsable.
+    """
+    import tomllib
+    try:
+        with open(toml_path, 'rb') as f:
+            data = tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError):
+        return None
+    value = data.get('download', {}).get('provider')
+    return value if isinstance(value, str) and value else None
+
+
+def extract_download_section(text: str) -> str | None:
+    """
+    Extract the ``[download]`` section verbatim from TOML text.
+
+    :param text: Full TOML file content.
+    :return: The section text (without trailing whitespace), or None.
+    """
+    m = _SECTION_RE.search(text)
+    return m.group(0).rstrip() if m else None
+
+
+def write_download_provider(toml_path: Path, provider_string: str) -> None:
+    """
+    Write (or replace) the ``[download]`` section in a syminfo TOML.
+
+    Missing files are left untouched: the section rides along with the symbol
+    info and makes no sense on its own.
+
+    :param toml_path: Path to the ``.toml`` next to the ``.ohlcv`` file.
+    :param provider_string: Canonical provider string to persist.
+    """
+    if not toml_path.exists():
+        return
+    text = toml_path.read_text(encoding='utf-8')
+    text = _SECTION_RE.sub('', text).rstrip()
+    section = f'[download]\nprovider = "{provider_string}"'
+    toml_path.write_text(f'{text}\n\n{section}\n', encoding='utf-8')

pynecore/core/download_runner.py

@@ -0,0 +1,274 @@
+"""
+Shared OHLCV download core.
+
+The ``.ohlcv`` download flow (start-date resolution, range clamping, truncate
+handling, progress accounting, symbol-info persistence) is driven by several
+front-ends: the ``pyne data download`` CLI, the symbol-browser TUI and the
+IDE bridge's provider service. They only differ in how they render progress
+and how they answer the "the file would have to be truncated" question, so
+everything else lives here.
+
+This module is part of the non-interactive ``core`` layer: it never prompts,
+never prints and knows nothing about typer/rich. Front-ends pass callbacks.
+"""
+from __future__ import annotations
+
+from typing import Callable, Literal, TypeAlias
+from dataclasses import dataclass
+from datetime import datetime, timedelta, UTC
+from pathlib import Path
+
+from .download_info import write_download_provider
+from .ohlcv_file import OHLCVWriter
+from .plugin.provider import ProviderPlugin
+from .syminfo import SymInfo
+
+__all__ = [
+    'ConflictAction', 'DownloadConflict', 'DownloadPlan', 'DownloadProgress',
+    'DownloadResult', 'DownloadError', 'DownloadConflictError',
+    'InvalidTimeRangeError', 'download_to_file',
+]
+
+ConflictAction: TypeAlias = Literal['truncate', 'abort']
+"""What to do when the requested start date precedes the first bar of the
+existing file: drop the file's content or raise. Appending before the existing
+first bar is not possible, the writer only ever appends at the end."""
+
+
+@dataclass(frozen=True)
+class DownloadConflict:
+    """The requested start date is before the first bar of the existing file."""
+    ohlcv_path: Path
+    time_from: datetime
+    existing_start: datetime
+
+
+@dataclass(frozen=True)
+class DownloadPlan:
+    """The resolved download range, handed to ``on_start`` before the first
+    provider request so front-ends can size their progress display."""
+    ohlcv_path: Path
+    time_from: datetime
+    time_to: datetime
+    fetch_all: bool
+    total_seconds: int
+    """Length of the range in seconds, 0 for a ``fetch_all`` download (whose
+    end is unknown, so no proportional progress can be shown)."""
+
+
+@dataclass(frozen=True)
+class DownloadProgress:
+    """One progress tick. Progress is time-proportional: the provider reports
+    the timestamp it has reached, not a bar count."""
+    current: datetime
+    elapsed_seconds: int
+    total_seconds: int
+
+
+@dataclass(frozen=True)
+class DownloadResult:
+    """Outcome of a finished download."""
+    ohlcv_path: Path
+    time_from: datetime
+    time_to: datetime
+    fetch_all: bool
+    bars_written: int
+    """Number of records the file grew by. Bars that overwrote already present
+    records do not count, so this is a lower bound of the fetched bars."""
+    syminfo: SymInfo | None
+    """The symbol info belonging to the file. When the caller passed one in, it
+    is the very same object, whose ``mincontract`` may have been refined."""
+
+
+class DownloadError(Exception):
+    """Base class of the errors raised by :func:`download_to_file`."""
+
+
+class InvalidTimeRangeError(DownloadError):
+    """The resolved end date is before the resolved start date."""
+
+
+class DownloadConflictError(DownloadError):
+    """The download would have truncated an existing file and the caller's
+    ``on_conflict`` policy was ``'abort'``."""
+
+    def __init__(self, conflict: DownloadConflict):
+        super().__init__(
+            f"The start date (from: {conflict.time_from}) is before the start of the "
+            f"existing file ({conflict.existing_start}); "
+            f"downloading it would truncate the file."
+        )
+        self.conflict = conflict
+
+
+def download_to_file(
+        provider: ProviderPlugin, *,
+        time_from: datetime | str,
+        time_to: datetime,
+        truncate: bool = False,
+        chunk_size: int | None = None,
+        extra_data: bool = False,
+        syminfo: SymInfo | None = None,
+        on_start: Callable[[DownloadPlan], None] | None = None,
+        on_progress: Callable[[DownloadProgress], None] | None = None,
+        on_conflict: "ConflictAction | Callable[[DownloadConflict], ConflictAction]" = 'abort',
+        provider_string: str | None = None,
+) -> DownloadResult:
+    """
+    Download OHLCV data into the provider's ``.ohlcv`` file.
+
+    The provider must already be bound to a symbol (built with one, so its
+    ``ohlcv_path`` and writer are set); every front-end constructs it that way,
+    which for multi-broker providers keeps the broker in the filename.
+
+    :param provider: The provider instance to download with.
+    :param time_from: Start date, or the ``"continue"`` sentinel to resume the
+        existing file (falling back to all available data for
+        ``fetch_all_by_default`` providers, otherwise one year back). Aware
+        datetimes are converted to UTC, naive ones are taken as UTC.
+    :param time_to: End date (same timezone handling as ``time_from``); clamped
+        to "now", as the future takes forever to download.
+    :param truncate: Drop the existing file content before downloading.
+    :param chunk_size: Override the provider's per-request bar count.
+    :param extra_data: Also fetch the provider's extra fields (``.extra.csv``).
+    :param syminfo: Already-loaded symbol info. When None it is fetched (and
+        persisted) *before* the download, best-effort, so an interrupted
+        download still leaves a resumable file.
+    :param on_start: Called once with the resolved :class:`DownloadPlan`, before
+        the first OHLCV request.
+    :param on_progress: Called with :class:`DownloadProgress` as the download
+        advances. Never called for a ``fetch_all`` download.
+    :param on_conflict: Policy or callback deciding what to do when the start
+        date precedes the existing file's first bar. A callback may prompt (the
+        CLI does) and must return one of the :data:`ConflictAction` values.
+    :param provider_string: Canonical provider string to persist in the
+        ``[download]`` section of the syminfo TOML, written *before* the
+        download so the file stays re-downloadable by path even if the download
+        is cut short. None skips it.
+    :return: The :class:`DownloadResult` of the finished download.
+    :raises InvalidTimeRangeError: If the end date is before the start date.
+    :raises DownloadConflictError: If a truncating conflict was answered with
+        ``'abort'``.
+    """
+    assert provider.ohlcv_path is not None
+    ohlcv_path = provider.ohlcv_path
+
+    with provider as ohlcv_writer:
+        if truncate:
+            ohlcv_writer.seek(0)
+            ohlcv_writer.truncate()
+
+        resolved_from, fetch_all = _resolve_from(provider, time_from, ohlcv_writer)
+
+        # The rest of the flow works with naive UTC datetimes
+        resolved_from = _to_naive_utc(resolved_from)
+        resolved_to = _to_naive_utc(time_to)
+
+        # We cannot download data from the future otherwise it would take very long
+        now_naive = datetime.now(UTC).replace(tzinfo=None)
+        if resolved_to > now_naive:
+            resolved_to = now_naive
+
+        if not fetch_all and resolved_to < resolved_from:
+            raise InvalidTimeRangeError(
+                "End date (to) must be greater than start date (from)!")
+
+        if ohlcv_writer.start_timestamp and not fetch_all:
+            existing_start = ohlcv_writer.start_datetime.replace(tzinfo=None)
+            if resolved_from < existing_start:
+                conflict = DownloadConflict(ohlcv_path=ohlcv_path, time_from=resolved_from,
+                                            existing_start=existing_start)
+                action = on_conflict(conflict) if callable(on_conflict) else on_conflict
+                if action == 'abort':
+                    raise DownloadConflictError(conflict)
+                if action != 'truncate':
+                    raise ValueError(f"Invalid conflict action: {action!r}")
+                ohlcv_writer.seek(0)
+                ohlcv_writer.truncate()
+
+        # Persist the symbol info and the originating provider string BEFORE the
+        # (potentially long) download, so an interrupted or user-aborted download
+        # still leaves a resumable file: the [download] section lets it be
+        # continued by path, and "continue" picks up from the last written bar.
+        if syminfo is None:
+            # noinspection PyBroadException
+            try:
+                syminfo = provider.get_symbol_info()  # save_toml() side effect
+            except Exception:
+                syminfo = None  # Symbol info is best-effort, don't block the download
+        if provider_string is not None:
+            # No-op until the syminfo TOML exists; get_symbol_info() above (or the
+            # caller) is what creates it.
+            write_download_provider(ohlcv_path.with_suffix('.toml'), provider_string)
+
+        total_seconds = 0 if fetch_all else max(0, int((resolved_to - resolved_from).total_seconds()))
+        if on_start is not None:
+            on_start(DownloadPlan(ohlcv_path=ohlcv_path, time_from=resolved_from,
+                                  time_to=resolved_to, fetch_all=fetch_all,
+                                  total_seconds=total_seconds))
+
+        progress_cb = on_progress
+
+        def cb_progress(current_time: datetime) -> None:
+            """ Callback to report time-proportional progress """
+            assert progress_cb is not None
+            elapsed = min(max(int((current_time - resolved_from).total_seconds()), 0), total_seconds)
+            progress_cb(DownloadProgress(current=current_time, elapsed_seconds=elapsed,
+                                         total_seconds=total_seconds))
+
+        cb = cb_progress if (progress_cb is not None and not fetch_all) else None
+
+        size_before = ohlcv_writer.size
+        provider.download_ohlcv(resolved_from, resolved_to, on_progress=cb,
+                                limit=chunk_size, with_extra=extra_data)
+        bars_written = ohlcv_writer.size - size_before
+
+        # Refine the heuristic mincontract from the downloaded volume data
+        # (only when the provider had no exchange value for it). save_toml()
+        # preserves the [download] section written before the download.
+        if syminfo is not None and provider.mincontract_estimated:
+            qty_step = ohlcv_writer.analyzed_qty_step or 0.0
+            if qty_step > 0.0 and qty_step != syminfo.mincontract:
+                syminfo.mincontract = qty_step
+                syminfo.save_toml(ohlcv_path.with_suffix('.toml'))
+
+    return DownloadResult(ohlcv_path=ohlcv_path, time_from=resolved_from, time_to=resolved_to,
+                          fetch_all=fetch_all, bars_written=bars_written, syminfo=syminfo)
+
+
+def _resolve_from(provider: ProviderPlugin, time_from: datetime | str,
+                  ohlcv_writer: OHLCVWriter) -> tuple[datetime, bool]:
+    """
+    Resolve the ``"continue"`` start-date sentinel against the existing file.
+
+    :param provider: The provider instance (its ``fetch_all_by_default``
+        decides what "no data yet" means).
+    :param time_from: Start date or the ``"continue"`` sentinel.
+    :param ohlcv_writer: The already opened writer of the target file.
+    :return: ``(start_date, fetch_all)``.
+    """
+    if isinstance(time_from, datetime):
+        return time_from, False
+
+    assert time_from == "continue", f"Unexpected from value: {time_from!r}"
+
+    end_ts = ohlcv_writer.end_timestamp
+    interval = ohlcv_writer.interval
+    if end_ts and interval:  # Resume from last download
+        # One interval ahead, otherwise the last bar would be downloaded again
+        return datetime.fromtimestamp(end_ts, UTC) + timedelta(seconds=interval), False
+    if provider.fetch_all_by_default:
+        return datetime.fromtimestamp(0, UTC), True
+    return datetime.now(UTC) - timedelta(days=365), False
+
+
+def _to_naive_utc(dt: datetime) -> datetime:
+    """
+    Convert a datetime to naive UTC, the form the download flow works with.
+
+    :param dt: Aware or naive (already UTC) datetime.
+    :return: Naive UTC datetime.
+    """
+    if dt.tzinfo is None:
+        return dt
+    return dt.astimezone(UTC).replace(tzinfo=None)