brokerclock 0.1.0__py3-none-any.whl

brokerclock/__init__.py

@@ -0,0 +1,42 @@
+"""MetaTrader broker server time to UTC and back, with daylight saving done right.
+
+>>> from datetime import datetime, timezone
+>>> from brokerclock import ServerZone
+>>> zone = ServerZone.us()  # GMT+2/+3 following US daylight saving, the most common broker clock
+>>> zone.to_utc(1751371200)  # a bar time as MetaTrader returns it: 2025-07-01 12:00 on the server clock
+datetime.datetime(2025, 7, 1, 9, 0, tzinfo=datetime.timezone.utc)
+>>> zone.server_timestamp(datetime(2025, 7, 1, 9, 0, tzinfo=timezone.utc))
+1751371200
+"""
+
+from brokerclock._detect import Detection, WeekClose, detect
+from brokerclock._errors import (
+    AmbiguousTimeError,
+    BrokerClockError,
+    NonexistentTimeError,
+    NotEnoughData,
+    OffsetOutOfRange,
+    StaleTickError,
+    ZoneMismatchError,
+)
+from brokerclock._live import check, measure_offset
+from brokerclock._zone import ServerZone
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AmbiguousTimeError",
+    "BrokerClockError",
+    "Detection",
+    "NonexistentTimeError",
+    "NotEnoughData",
+    "OffsetOutOfRange",
+    "ServerZone",
+    "StaleTickError",
+    "WeekClose",
+    "ZoneMismatchError",
+    "__version__",
+    "check",
+    "detect",
+    "measure_offset",
+]

brokerclock/_detect.py

@@ -0,0 +1,181 @@
+"""Find a broker's clock rule from the weekly closes in its price history, without the PC clock."""
+
+from __future__ import annotations
+
+import math
+import numbers
+import operator
+from collections import Counter
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import datetime, time, timedelta, timezone
+from itertools import pairwise
+from zoneinfo import ZoneInfo
+
+from brokerclock._errors import NotEnoughData
+from brokerclock._zone import _EPOCH, _MAX_OFFSET, _MIN_OFFSET, _QUARTER_HOUR, _RULES, ServerZone
+
+_NEW_YORK = ZoneInfo("America/New_York")
+_WEEKLY_CLOSE = time(17)  # Friday 17:00 New York ends the forex week
+_FRIDAY = 4
+_WEEKEND_GAP = timedelta(hours=40)
+_LATE_SLACK = timedelta(seconds=60)  # a last bar may end a few seconds after 17:00 (a late tick, a fast clock)
+_MIN_TIMEFRAME = 60
+_MAX_TIMEFRAME = 3600
+_MIN_WEEKS = 2
+
+
+@dataclass(frozen=True)
+class WeekClose:
+    """One weekly close found in the bars.
+
+    ``friday_close_utc`` is the Friday 17:00 New York instant (aware UTC), ``server_close`` the close on the server
+    clock in epoch seconds (last bar open + timeframe), and ``offset`` their difference rounded up to 15 minutes.
+    """
+
+    friday_close_utc: datetime
+    server_close: int
+    offset: timedelta
+
+
+@dataclass(frozen=True)
+class Detection:
+    """The result of :func:`detect`.
+
+    ``zone`` is the best-scoring server clock, or None when several clocks score the same (``candidates`` then
+    holds all of them). ``matched`` of ``total`` weeks agree with it; ``outliers`` are the weeks it does not
+    predict (for example early holiday closes), and ``unexplained`` the server close times that fit no Friday.
+    """
+
+    zone: ServerZone | None
+    candidates: tuple[ServerZone, ...]
+    weeks: tuple[WeekClose, ...]
+    matched: int
+    total: int
+    unexplained: tuple[int, ...]
+    outliers: tuple[WeekClose, ...]
+
+    @property
+    def ambiguous(self) -> bool:
+        """True when the data cannot tell the candidates apart."""
+        return self.zone is None
+
+
+def detect(bar_times: Iterable[int], timeframe: int = 3600) -> Detection:
+    """Find the server clock from the open times of a forex major's bars.
+
+    ``bar_times`` are server epoch seconds (the ``time`` column of ``copy_rates_*``) in any order; duplicates are
+    ignored. ``timeframe`` is the bar length in seconds, from 60 (M1) to 3600 (H1).
+
+    Each gap of 40 hours or more after a bar marks a weekly close at that bar's open + ``timeframe``. The forex
+    week ends on Friday at 17:00 New York, so each close gives the server's offset in that week. Each candidate
+    clock (fixed, US, EU or Australian daylight saving, any base offset) scores the weeks it predicts, and the
+    best wins. A tie means the data cannot tell the clocks apart.
+
+    What the data needs:
+
+    * a forex major such as EURUSD; metals and indices follow their exchange's hours;
+    * at least six months of H1 bars, or a span that includes March or late October to early November, when the
+      US and EU switch on different dates. Summer-only data cannot separate US from EU rules, and data without a
+      switch cannot separate a fixed clock from a switching one;
+    * bars of one hour or shorter. The close is taken as the last bar's open + ``timeframe``, so it is exact only
+      when a bar ends at the weekly close; longer bars end on the server's 4-hour or day boundaries, which hide
+      the switch weeks, so they are rejected. Use M15 or shorter for clocks with 30- or 45-minute offsets.
+
+    Running it on two majors and comparing the results is good practice.
+
+    A broker's week ends at or before 17:00 New York, never after, so each offset is rounded up to the next 15
+    minutes (after allowing 60 seconds for a bar that ends just past 17:00). Closes less than 14 minutes early
+    (16:50 in M5 bars, 16:47 or later in M1 bars) are read correctly. A week that ends 14 minutes or more early
+    (16:40, say) reads 15 minutes off: if only some weeks do that they become ``outliers``; if every week does,
+    the whole result is 15 minutes off, for example GMT+1:45/+2:45 instead of GMT+2/+3. H1 bars are not
+    affected, because the last H1 bar still ends at 17:00.
+
+    Raises ``NotEnoughData`` when fewer than two weekly closes match a Friday.
+
+    >>> monday = 1736121600  # 2025-01-06 00:00 on a GMT+2 server, which is Sunday 17:00 New York
+    >>> bars = [monday + week * 7 * 86400 + hour * 3600 for week in range(3) for hour in range(120)]
+    >>> result = detect(bars)  # three weeks of H1 bars: two weekly closes
+    >>> result.total, result.weeks[0].offset
+    (2, datetime.timedelta(seconds=7200))
+    >>> result.ambiguous  # January only: no switch, so several clocks fit
+    True
+    >>> [str(zone) for zone in result.candidates]
+    ['GMT+2/+3 (US daylight saving)', 'GMT+2/+3 (EU daylight saving)', 'GMT+1/+2 (AU daylight saving)', 'GMT+2 (fixed)']
+    """
+    if isinstance(timeframe, bool) or not isinstance(timeframe, numbers.Integral):
+        raise ValueError(f"timeframe must be a whole number of seconds, got {timeframe!r}")
+    if not _MIN_TIMEFRAME <= timeframe <= _MAX_TIMEFRAME:
+        raise ValueError(f"timeframe must be between 60 and 3600 seconds (M1 to H1), got {timeframe}")
+    weeks: list[WeekClose] = []
+    unexplained: list[int] = []
+    for close in _weekly_closes(bar_times, int(timeframe)):
+        week = _week_close(close)
+        if week is None:
+            unexplained.append(close)
+        else:
+            weeks.append(week)
+    if len(weeks) < _MIN_WEEKS:
+        raise NotEnoughData(
+            f"found {len(weeks)} weekly close(s) that match a Friday ({len(unexplained)} more do not); "
+            f"need {_MIN_WEEKS}"
+        )
+    candidates, matched = _best_zones(weeks)
+    outliers = tuple(w for w in weeks if all(z.offset_at(w.friday_close_utc) != w.offset for z in candidates))
+    return Detection(
+        zone=candidates[0] if len(candidates) == 1 else None,
+        candidates=candidates,
+        weeks=tuple(weeks),
+        matched=matched,
+        total=len(weeks),
+        unexplained=tuple(unexplained),
+        outliers=outliers,
+    )
+
+
+def _weekly_closes(bar_times: Iterable[int], timeframe: int) -> list[int]:
+    """Server close times of the bars followed by a weekend-sized gap."""
+    gap = int(_WEEKEND_GAP.total_seconds())
+    times = sorted({operator.index(t) for t in bar_times})
+    return [bar + timeframe for bar, following in pairwise(times) if following - (bar + timeframe) >= gap]
+
+
+def _week_close(server_close: int) -> WeekClose | None:
+    """Match a server close to the Friday 17:00 New York that puts it within -12 h..+14 h, if there is one."""
+    wall = _EPOCH + timedelta(seconds=server_close)
+    # Within that range the server's date is the Friday itself or the Saturday after it.
+    for days_back in (0, 1):
+        day = wall.date() - timedelta(days=days_back)
+        if day.weekday() != _FRIDAY:
+            continue
+        friday = datetime.combine(day, _WEEKLY_CLOSE, tzinfo=_NEW_YORK).astimezone(timezone.utc)
+        offset = wall - friday.replace(tzinfo=None)
+        if _MIN_OFFSET <= offset <= _MAX_OFFSET:
+            return WeekClose(friday, server_close, _round_up_quarter(offset))
+    return None
+
+
+def _round_up_quarter(offset: timedelta) -> timedelta:
+    """Round a measured weekly-close offset up to 15 minutes: brokers close at or before 17:00, never after."""
+    return _QUARTER_HOUR * math.ceil((offset - _LATE_SLACK) / _QUARTER_HOUR)
+
+
+def _best_zones(weeks: list[WeekClose]) -> tuple[tuple[ServerZone, ...], int]:
+    """The clocks that predict the most weeks, and how many weeks that is."""
+    votes: Counter[ServerZone] = Counter()
+    for week in weeks:
+        for key, standard in _RULES.values():
+            tz = ZoneInfo(key)
+            daylight = tz.dst(week.friday_close_utc.astimezone(tz))
+            zone = _valid_zone(key, week.offset - daylight - standard)
+            if zone is not None:
+                votes[zone] += 1
+    best = max(votes.values())
+    return tuple(zone for zone, count in votes.items() if count == best), best
+
+
+def _valid_zone(key: str, shift: timedelta) -> ServerZone | None:
+    try:
+        return ServerZone(key, shift)
+    except ValueError:
+        return None

brokerclock/_errors.py

@@ -0,0 +1,29 @@
+"""Exceptions raised by brokerclock. All of them are ``ValueError`` subclasses."""
+
+
+class BrokerClockError(ValueError):
+    """Base class of every brokerclock error."""
+
+
+class AmbiguousTimeError(BrokerClockError):
+    """A server wall time occurs twice (the hour repeated when daylight saving ends)."""
+
+
+class NonexistentTimeError(BrokerClockError):
+    """A server wall time never occurs (the hour skipped when daylight saving starts)."""
+
+
+class NotEnoughData(BrokerClockError):
+    """The bar history holds fewer than two weekly closes that can be matched to a Friday."""
+
+
+class StaleTickError(BrokerClockError):
+    """A tick time is not a whole quarter hour away from the PC clock: the tick is old or the PC clock is off."""
+
+
+class OffsetOutOfRange(BrokerClockError):
+    """A measured offset lies outside the possible UTC offsets, -12 h to +14 h."""
+
+
+class ZoneMismatchError(BrokerClockError):
+    """A live tick contradicts the server zone: the zone is wrong or the PC clock is behind."""

brokerclock/_live.py

@@ -0,0 +1,108 @@
+"""Measure or confirm the server clock from live tick times and the PC clock."""
+
+from __future__ import annotations
+
+import numbers
+import time
+from collections.abc import Iterable
+from datetime import datetime, timedelta
+
+from brokerclock._errors import NonexistentTimeError, OffsetOutOfRange, StaleTickError, ZoneMismatchError
+from brokerclock._zone import _MAX_OFFSET, _MIN_OFFSET, _QUARTER_HOUR, ServerZone, _nearest_quarter, _require_aware
+
+
+def measure_offset(
+    server_times: Iterable[float], now: float | datetime | None = None, *, tolerance: float = 60
+) -> timedelta:
+    """Measure the server's current UTC offset from the freshest tick time.
+
+    ``server_times`` are tick times in server epoch seconds (``tick.time``, or ``tick.time_msc / 1000``); the
+    largest is used. ``now`` is the current UTC time as epoch seconds or an aware datetime, and defaults to the PC
+    clock. The offset is ``freshest - now`` rounded to 15 minutes.
+
+    Raises ``OffsetOutOfRange`` when the offset is outside -12 h to +14 h, and ``StaleTickError`` when the
+    unrounded difference is more than ``tolerance`` seconds from the offset: the tick is not fresh, or the PC
+    clock is off by more than ``tolerance``.
+
+    A tick that is stale by close to a multiple of 15 minutes passes this test with a wrong offset, so measure
+    only while the symbols trade, or prefer :func:`check` against a zone found by :func:`detect`.
+
+    >>> measure_offset([1751382000], now=1751371200.6)  # a tick from 0.6 s ago, 3 hours ahead of UTC
+    datetime.timedelta(seconds=10800)
+    """
+    if isinstance(tolerance, bool) or not 0 <= tolerance < _QUARTER_HOUR.total_seconds() / 2:
+        raise ValueError(f"tolerance must be at least 0 and under 450 seconds, got {tolerance!r}")
+    raw = timedelta(seconds=float(_freshest(server_times)) - _now_seconds(now))
+    offset = _nearest_quarter(raw)
+    if not _MIN_OFFSET <= offset <= _MAX_OFFSET:
+        raise OffsetOutOfRange(
+            f"the freshest tick is {raw.total_seconds() / 3600:+.2f} h from the PC clock, outside -12 h to +14 h: "
+            "the tick is old (market closed?) or the PC clock is wrong"
+        )
+    residual = (raw - offset).total_seconds()
+    if abs(residual) > tolerance:
+        raise StaleTickError(
+            f"the freshest tick is {residual:+.1f} s off a whole quarter hour from the PC clock: "
+            f"either the tick is not fresh or the PC clock is off by more than {tolerance} s"
+        )
+    return offset
+
+
+def check(
+    zone: ServerZone,
+    server_times: Iterable[float],
+    now: float | datetime | None = None,
+    *,
+    tolerance: float = 60,
+    max_age: float = 300,
+) -> bool:
+    """Check live tick times against ``zone``.
+
+    The age of the freshest tick is ``now`` minus its UTC time under ``zone``. ``server_times`` and ``now`` are as
+    in :func:`measure_offset`. Three outcomes:
+
+    * ``ZoneMismatchError`` when the tick is more than ``tolerance`` seconds in the future: the zone is behind
+      the real server clock, or the PC clock is behind.
+    * ``True`` when the tick is at most ``max_age`` seconds old: a fresh tick agrees with the zone.
+    * ``False`` when the tick is older: nothing can be confirmed, because the market is closed or quiet, or the
+      zone is ahead of the real one.
+
+    A tick in an hour the clock repeats is checked against both occurrences.
+
+    >>> from brokerclock import ServerZone
+    >>> check(ServerZone.us(), [1751382000], now=1751371200.6)  # 2025-07-01 12:00 server is 09:00 UTC
+    True
+    """
+    if tolerance < 0 or max_age < 0:
+        raise ValueError(f"tolerance and max_age must be at least 0, got {tolerance!r} and {max_age!r}")
+    freshest = _freshest(server_times)
+    try:
+        earlier = zone.to_utc(freshest, ambiguous="earlier")
+    except NonexistentTimeError as exc:
+        raise ZoneMismatchError(f"tick time {freshest} falls in an hour that {zone} skips") from exc
+    later = zone.to_utc(freshest, ambiguous="later")
+    current = _now_seconds(now)
+    if current - earlier.timestamp() < -tolerance:
+        raise ZoneMismatchError(
+            f"under {zone} the freshest tick is from {earlier:%Y-%m-%d %H:%M:%S} UTC, in the future: "
+            "the zone is behind the real server clock or the PC clock is behind"
+        )
+    return any(-tolerance <= current - tick.timestamp() <= max_age for tick in (earlier, later))
+
+
+def _freshest(server_times: Iterable[float]) -> float:
+    freshest = max(server_times, default=None)
+    if freshest is None:
+        raise ValueError("server_times is empty")
+    return freshest
+
+
+def _now_seconds(now: float | datetime | None) -> float:
+    if now is None:
+        return time.time()
+    if isinstance(now, datetime):
+        _require_aware(now, "now")
+        return now.timestamp()
+    if isinstance(now, bool) or not isinstance(now, numbers.Real):
+        raise TypeError(f"now must be epoch seconds or an aware datetime, got {now!r}")
+    return float(now)

brokerclock/_zone.py

@@ -0,0 +1,231 @@
+"""The broker's server clock: the wall clock of an IANA time zone plus a fixed shift."""
+
+from __future__ import annotations
+
+import math
+import numbers
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from functools import cache
+from typing import Literal
+from zoneinfo import ZoneInfo, available_timezones
+
+from brokerclock._errors import AmbiguousTimeError, NonexistentTimeError
+
+AmbiguousPolicy = Literal["raise", "earlier", "later"]
+
+# MetaTrader epoch numbers count seconds from this moment on the server's own wall clock, so it has no time zone.
+_EPOCH = datetime(1970, 1, 1)  # noqa: DTZ001
+_SECOND = timedelta(seconds=1)
+_HOUR = timedelta(hours=1)
+_QUARTER_HOUR = timedelta(minutes=15)
+_MIN_OFFSET = timedelta(hours=-12)
+_MAX_OFFSET = timedelta(hours=14)
+_MAX_SHIFT_HOURS = 26
+_AMBIGUOUS_POLICIES = ("raise", "earlier", "later")
+
+# Daylight-saving rule -> (IANA zone that follows it, that zone's standard UTC offset).
+_RULES: dict[str, tuple[str, timedelta]] = {
+    "US": ("America/New_York", timedelta(hours=-5)),
+    "EU": ("Europe/London", timedelta(0)),
+    "AU": ("Australia/Sydney", timedelta(hours=10)),
+    "fixed": ("UTC", timedelta(0)),
+}
+
+
+@dataclass(frozen=True)
+class ServerZone:
+    """A broker server clock: the wall clock of ``zone`` (an IANA key) plus ``shift``.
+
+    ``shift`` is a multiple of 15 minutes, at most 26 hours either way, and the resulting UTC offset must lie
+    between -12 h and +14 h. The constructors cover the usual broker clocks:
+
+    >>> str(ServerZone.us())
+    'GMT+2/+3 (US daylight saving)'
+    >>> str(ServerZone.eu(1))
+    'GMT+1/+2 (EU daylight saving)'
+    >>> str(ServerZone.fixed(5.75))
+    'GMT+5:45 (fixed)'
+    >>> str(ServerZone("Europe/Athens"))
+    'Europe/Athens'
+    """
+
+    zone: str
+    shift: timedelta = timedelta(0)
+
+    def __post_init__(self) -> None:
+        if self.zone not in _iana_keys():
+            raise ValueError(f"unknown IANA time zone key: {self.zone!r}")
+        if not isinstance(self.shift, timedelta):
+            raise TypeError(f"shift must be a datetime.timedelta, got {type(self.shift).__name__}")
+        if self.shift % _QUARTER_HOUR or abs(self.shift) > _MAX_SHIFT_HOURS * _HOUR:
+            raise ValueError(f"shift must be a multiple of 15 minutes within 26 hours, got {self.shift!r}")
+        year = datetime.now(timezone.utc).year
+        for month in (1, 7):
+            offset = self.offset_at(datetime(year, month, 1, tzinfo=timezone.utc))
+            if not _MIN_OFFSET <= offset <= _MAX_OFFSET:
+                raise ValueError(
+                    f"{self.zone} shifted by {self.shift!r} gives GMT{_format_offset(offset)}, outside -12 h to +14 h"
+                )
+
+    @classmethod
+    def us(cls, base_hours: float = 2) -> ServerZone:
+        """New York wall clock plus ``base_hours + 5`` h: GMT+base in winter, GMT+base+1 in summer, US dates.
+
+        The default, GMT+2/+3, is the most common broker clock: its midnight is 17:00 in New York, when the
+        forex day rolls over.
+        """
+        return cls._from_rule("US", base_hours)
+
+    @classmethod
+    def eu(cls, base_hours: float = 2) -> ServerZone:
+        """London wall clock plus ``base_hours``: GMT+base in winter, GMT+base+1 in summer, EU dates.
+
+        ``eu()`` is GMT+2/+3 and ``eu(1)`` is GMT+1/+2, both switching on the last Sundays of March and October.
+        """
+        return cls._from_rule("EU", base_hours)
+
+    @classmethod
+    def au(cls, base_hours: float = 2) -> ServerZone:
+        """Sydney wall clock plus ``base_hours - 10`` h: GMT+base+1 from October to April, GMT+base otherwise."""
+        return cls._from_rule("AU", base_hours)
+
+    @classmethod
+    def fixed(cls, hours: float) -> ServerZone:
+        """A clock that never switches: UTC plus ``hours`` (0.25 steps, so ``fixed(5.75)`` is GMT+5:45)."""
+        return cls._from_rule("fixed", hours)
+
+    @classmethod
+    def _from_rule(cls, rule: str, base_hours: float) -> ServerZone:
+        key, standard = _RULES[rule]
+        return cls(key, _hours(base_hours) - standard)
+
+    def __str__(self) -> str:
+        for rule, (key, standard) in _RULES.items():
+            if self.zone == key:
+                base = standard + self.shift
+                if rule == "fixed":
+                    return f"GMT{_format_offset(base)} (fixed)"
+                return f"GMT{_format_offset(base)}/{_format_offset(base + _HOUR)} ({rule} daylight saving)"
+        return f"{self.zone} {_format_offset(self.shift)}" if self.shift else self.zone
+
+    @property
+    def _tz(self) -> ZoneInfo:
+        return ZoneInfo(self.zone)
+
+    def offset_at(self, instant: datetime) -> timedelta:
+        """Return the server's UTC offset at an aware ``instant``.
+
+        >>> ServerZone.us().offset_at(datetime(2025, 3, 20, tzinfo=timezone.utc))  # US summer time, EU not yet
+        datetime.timedelta(seconds=10800)
+        >>> ServerZone.eu().offset_at(datetime(2025, 3, 20, tzinfo=timezone.utc))
+        datetime.timedelta(seconds=7200)
+        """
+        _require_aware(instant, "instant")
+        return instant.astimezone(self._tz).utcoffset() + self.shift
+
+    def to_utc(self, server_time: float | datetime, *, ambiguous: AmbiguousPolicy = "raise") -> datetime:
+        """Convert a server time to an aware UTC datetime.
+
+        ``server_time`` is epoch seconds as MetaTrader returns them (``time``, or ``time_msc / 1000``), or a naive
+        datetime of server wall time. An aware datetime raises ``TypeError``, because it is unclear whether it was
+        already converted.
+
+        A wall time in the hour repeated when daylight saving ends is resolved by ``ambiguous``: ``"raise"`` raises
+        ``AmbiguousTimeError``, ``"earlier"`` takes the first occurrence and ``"later"`` the second. A wall time in
+        the hour skipped when daylight saving starts raises ``NonexistentTimeError``.
+
+        >>> zone = ServerZone.us()
+        >>> zone.to_utc(1735693200)  # 2025-01-01 01:00 on the server clock
+        datetime.datetime(2024, 12, 31, 23, 0, tzinfo=datetime.timezone.utc)
+        >>> zone.to_utc(datetime(2025, 7, 1, 12, 0))
+        datetime.datetime(2025, 7, 1, 9, 0, tzinfo=datetime.timezone.utc)
+        """
+        if ambiguous not in _AMBIGUOUS_POLICIES:
+            raise ValueError(f"ambiguous must be one of {_AMBIGUOUS_POLICIES}, got {ambiguous!r}")
+        wall = _server_wall(server_time)
+        local = wall - self.shift
+        tz = self._tz
+        earlier = local.replace(tzinfo=tz, fold=0).astimezone(timezone.utc)
+        later = local.replace(tzinfo=tz, fold=1).astimezone(timezone.utc)
+        if earlier == later:
+            return earlier
+        if earlier.astimezone(tz).replace(tzinfo=None) != local:
+            raise NonexistentTimeError(f"server time {wall} falls in the hour that {self} skips")
+        if ambiguous == "raise":
+            raise AmbiguousTimeError(f"server time {wall} occurs twice in {self}; pass ambiguous='earlier' or 'later'")
+        return earlier if ambiguous == "earlier" else later
+
+    def to_server(self, instant: datetime) -> datetime:
+        """Return the naive server wall time at an aware ``instant``.
+
+        >>> ServerZone.us().to_server(datetime(2025, 7, 1, 9, 0, tzinfo=timezone.utc))
+        datetime.datetime(2025, 7, 1, 12, 0)
+        """
+        offset = self.offset_at(instant)
+        return instant.astimezone(timezone.utc).replace(tzinfo=None) + offset
+
+    def server_timestamp(self, instant: datetime) -> int:
+        """Return the server-wall epoch seconds of an aware ``instant``, flooring any fraction of a second.
+
+        Pass these numbers to ``copy_rates_range``, ``copy_ticks_range`` and ``history_deals_get``, and as the
+        ``expiration`` of an order: MetaTrader reads all of them as server wall time. An int also avoids the
+        terminal reading a naive datetime in the PC's local zone.
+
+        >>> ServerZone.us().server_timestamp(datetime(2025, 7, 1, 9, 0, 0, 999999, tzinfo=timezone.utc))
+        1751371200
+        """
+        return (self.to_server(instant) - _EPOCH) // _SECOND
+
+
+@cache
+def _iana_keys() -> frozenset[str]:
+    return frozenset(available_timezones())
+
+
+def _hours(value: float) -> timedelta:
+    """Turn a number of hours in 0.25 steps into a timedelta."""
+    valid = (
+        isinstance(value, (int, float))
+        and not isinstance(value, bool)
+        and math.isfinite(value)
+        and abs(value) <= _MAX_SHIFT_HOURS
+        and float(value * 4).is_integer()
+    )
+    if not valid:
+        raise ValueError(f"hours must be an int or float in 0.25 steps, got {value!r}")
+    return timedelta(minutes=round(value * 60))
+
+
+def _require_aware(value: object, name: str) -> None:
+    if not isinstance(value, datetime) or value.utcoffset() is None:
+        raise TypeError(f"{name} must be an aware datetime (with tzinfo), got {value!r}")
+
+
+def _server_wall(server_time: float | datetime) -> datetime:
+    """Turn epoch seconds or a naive datetime of server wall time into a naive datetime."""
+    if isinstance(server_time, datetime):
+        if server_time.utcoffset() is not None:
+            raise TypeError("server_time must be naive server wall time or epoch seconds, not an aware datetime")
+        return server_time
+    if isinstance(server_time, bool) or not isinstance(server_time, numbers.Real):
+        raise TypeError(f"server_time must be epoch seconds or a naive datetime, got {server_time!r}")
+    if isinstance(server_time, numbers.Integral):
+        return _EPOCH + timedelta(seconds=int(server_time))
+    seconds = float(server_time)
+    if not math.isfinite(seconds):
+        raise ValueError(f"server_time must be finite, got {server_time!r}")
+    return _EPOCH + timedelta(seconds=seconds)
+
+
+def _nearest_quarter(offset: timedelta) -> timedelta:
+    """Round to the nearest 15 minutes, halves up."""
+    return _QUARTER_HOUR * math.floor(offset / _QUARTER_HOUR + 0.5)
+
+
+def _format_offset(offset: timedelta) -> str:
+    """Format an offset as +2, -3:30 or +5:45."""
+    minutes = offset // timedelta(minutes=1)
+    sign = "-" if minutes < 0 else "+"
+    hours, minutes = divmod(abs(minutes), 60)
+    return f"{sign}{hours}:{minutes:02d}" if minutes else f"{sign}{hours}"

brokerclock/pandas.py

@@ -0,0 +1,78 @@
+"""Vectorized conversions for whole pandas columns. Needs pandas: ``pip install "brokerclock[pandas]"``.
+
+>>> import brokerclock.pandas as bcpd
+>>> from brokerclock import ServerZone
+>>> utc = bcpd.to_utc([1751371200, 1751374800], ServerZone.us())  # 12:00 and 13:00 on the server clock
+>>> [str(t) for t in utc]
+['2025-07-01 09:00:00+00:00', '2025-07-01 10:00:00+00:00']
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from brokerclock._zone import _EPOCH, ServerZone
+
+try:
+    import pandas as pd
+except ImportError as exc:
+    raise ImportError('brokerclock.pandas needs pandas: pip install "brokerclock[pandas]"') from exc
+
+if TYPE_CHECKING:
+    import numpy as np
+    import numpy.typing as npt
+
+    Times = pd.Series | pd.DatetimeIndex
+
+
+def to_utc(
+    values: npt.ArrayLike,
+    zone: ServerZone,
+    *,
+    unit: str = "s",
+    ambiguous: str | npt.ArrayLike = "infer",
+    nonexistent: str = "raise",
+) -> Times:
+    """Convert server epoch numbers to aware UTC times.
+
+    ``values`` is a Series, Index or array of server epoch numbers in ``unit`` (``"s"`` for ``time``, ``"ms"`` for
+    ``time_msc``). A Series comes back as a Series with the same index; anything else as a DatetimeIndex.
+
+    ``ambiguous`` and ``nonexistent`` are passed to pandas' ``tz_localize``. The default ``"infer"`` resolves the
+    repeated hour when the values are in time order, as bars and ticks are, and raises when it cannot (for example
+    a single value, or one merged H1 bar). A value in a skipped hour raises by default. Both errors are pandas'
+    own: ``ValueError`` in pandas 3, pytz's ``AmbiguousTimeError`` or ``NonExistentTimeError`` in pandas 2.
+    """
+    times = pd.to_datetime(values, unit=unit) - zone.shift
+    local = _datetimes(times).tz_localize(zone.zone, ambiguous=ambiguous, nonexistent=nonexistent)
+    return _datetimes(local).tz_convert("UTC")
+
+
+def frame_to_utc(
+    frame: pd.DataFrame | np.ndarray, zone: ServerZone, column: str = "time", **kwargs: Any
+) -> pd.DataFrame:
+    """Return a copy of ``frame`` with ``column`` converted by :func:`to_utc`.
+
+    ``frame`` is a DataFrame or the structured array that ``copy_rates_*`` and ``copy_ticks_*`` return.
+    ``kwargs`` go to :func:`to_utc`; for tick arrays pass ``column="time_msc", unit="ms"``.
+    """
+    out = frame.copy() if isinstance(frame, pd.DataFrame) else pd.DataFrame(frame)
+    out[column] = to_utc(out[column], zone, **kwargs)
+    return out
+
+
+def to_server_timestamps(index_or_series: Times, zone: ServerZone) -> npt.NDArray[np.int64]:
+    """Convert aware times to server epoch seconds (int64, fractions of a second floored).
+
+    The inverse of :func:`to_utc`, for building query bounds or comparing with MetaTrader data.
+    """
+    times = pd.DatetimeIndex(index_or_series)
+    if times.tz is None:
+        raise TypeError("to_server_timestamps needs aware times (for example UTC), got naive ones")
+    wall = times.tz_convert(zone.zone).tz_localize(None) + zone.shift
+    return ((wall - pd.Timestamp(_EPOCH)) // pd.Timedelta(seconds=1)).to_numpy(dtype="int64")
+
+
+def _datetimes(times: Times) -> Any:
+    """The object that carries the datetime methods: ``.dt`` for a Series, the index itself otherwise."""
+    return times.dt if isinstance(times, pd.Series) else times

brokerclock-0.1.0.dist-info/METADATA

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: brokerclock
+Version: 0.1.0
+Summary: MetaTrader broker server time to UTC and back, with daylight saving done right.
+Project-URL: Homepage, https://github.com/raiez-alshamaly/brokerclock
+Project-URL: Source, https://github.com/raiez-alshamaly/brokerclock
+Project-URL: Issues, https://github.com/raiez-alshamaly/brokerclock/issues
+Author-email: Raeez alshamaly <github@raeez-alshamaly.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: algorithmic trading,backtesting,broker,daylight saving,dst,forex,fx,gmt offset,metatrader,metatrader5,mt4,mt5,pandas,server time,time zone,timezone,trading,utc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: tzdata; sys_platform == 'win32'
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: pandas>=2.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff==0.17.0; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# brokerclock — MetaTrader broker server time to UTC (and back), with daylight saving done right
+
+MetaTrader 5 does not give you UTC. The `time` and `time_msc` values that `copy_rates_*`, `copy_ticks_*`,
+`history_deals_get` and `history_orders_get` return are the broker's **server clock written as epoch seconds**,
+even though they look like Unix timestamps. If you searched for "MT5 server time UTC", "broker GMT offset" or
+"copy_rates time zone", this is why your bars are two or three hours off.
+
+- Most brokers run **GMT+2 in winter and GMT+3 in summer, switching with US daylight saving**: New York time plus
+  7 hours, so the forex day starts at server midnight, 17:00 in New York.
+- A fixed offset breaks for weeks every year. `+3` is wrong all winter, and even a European daylight-saving rule is
+  wrong for about three weeks in March and one week around the start of November, when the US and Europe switch
+  on different dates.
+- The server clock works in the other direction too: the date arguments of `copy_rates_range` and friends, and an
+  order's `expiration`, are read as server time.
+
+brokerclock models the server clock as an IANA time zone plus a shift, so every conversion uses the rule in force at
+that moment. It finds the rule from price history alone, confirms it against live ticks, and converts single values
+or whole pandas columns. It needs only the standard library (plus `tzdata` on Windows) and never imports
+`MetaTrader5`, so it runs and tests on any operating system.
+
+## Install (after the first release)
+
+```bash
+pip install brokerclock
+pip install "brokerclock[pandas]"   # with the pandas helpers
+```
+
+Python 3.10 or newer.
+
+## Quick start
+
+### 1. Find the broker's clock from H1 EURUSD bars
+
+```python
+import MetaTrader5 as mt5
+
+import brokerclock
+
+mt5.initialize()
+
+# About a year of H1 bars of a forex major.
+rates = mt5.copy_rates_from_pos("EURUSD", mt5.TIMEFRAME_H1, 0, 6500)
+result = brokerclock.detect(rates["time"], timeframe=3600)
+print(result.zone)  # GMT+2/+3 (US daylight saving)
+print(f"{result.matched} of {result.total} weeks agree")
+zone = result.zone
+```
+
+If `result.ambiguous` is true, the bars cannot separate the clocks in `result.candidates` (summer-only data, for
+example): fetch a longer span. Running the same check on a second major is good practice. Once known, the clock is a
+constant you can keep in your configuration, such as `brokerclock.ServerZone.us()`.
+
+### 2. Convert bars to UTC
+
+```python
+import brokerclock.pandas as bcpd
+
+bars = bcpd.frame_to_utc(rates, zone)  # a DataFrame whose "time" column is aware UTC
+print(bars[["time", "close"]].tail(3))
+
+first_bar = zone.to_utc(rates["time"][0])  # one value, without pandas: an aware UTC datetime
+```
+
+### 3. Query by UTC and set an order expiration
+
+```python
+from datetime import datetime, timedelta, timezone
+
+# Bars of March 2025 in UTC terms. Pass server-clock ints: a naive datetime would go through the PC's time zone.
+start = datetime(2025, 3, 1, tzinfo=timezone.utc)
+end = datetime(2025, 4, 1, tzinfo=timezone.utc)
+march = mt5.copy_rates_range("EURUSD", mt5.TIMEFRAME_H1, zone.server_timestamp(start), zone.server_timestamp(end))
+
+# A pending order that expires four hours from now.
+expiry = datetime.now(timezone.utc) + timedelta(hours=4)
+request = {
+    "action": mt5.TRADE_ACTION_PENDING,
+    "symbol": "EURUSD",
+    "volume": 0.1,
+    "type": mt5.ORDER_TYPE_BUY_LIMIT,
+    "price": 1.05,
+    "type_time": mt5.ORDER_TIME_SPECIFIED,
+    "expiration": zone.server_timestamp(expiry),
+}
+mt5.order_send(request)
+```
+
+### 4. Check the clock against live ticks
+
+```python
+tick = mt5.symbol_info_tick("EURUSD")
+if brokerclock.check(zone, [tick.time_msc / 1000]):
+    print("live ticks agree with", zone)
+else:
+    print("no fresh tick to confirm it: the market is closed, or the zone is ahead of the server")
+
+# Without a known zone: the current offset, while the market trades.
+print(brokerclock.measure_offset([tick.time_msc / 1000]))  # 3:00:00 in summer, 2:00:00 in winter
+```
+
+`check` raises `ZoneMismatchError` when the tick would be from the future under that zone (the zone is behind the
+server, or the PC clock is behind). `measure_offset` raises `StaleTickError` or `OffsetOutOfRange` instead of
+guessing when the tick is not fresh.
+
+## Broker clock conventions
+
+| Server clock | Winter | Summer | Switch dates | `ServerZone` |
+|---|---|---|---|---|
+| New York close, the most common | GMT+2 | GMT+3 | US: second Sunday of March, first Sunday of November | `ServerZone.us()` |
+| EU rule | GMT+2 | GMT+3 | EU: last Sundays of March and October | `ServerZone.eu()` |
+| EU rule, central European | GMT+1 | GMT+2 | EU | `ServerZone.eu(1)` |
+| Australian rule | GMT+2 (April to October) | GMT+3 (October to April) | AU: first Sundays of October and April | `ServerZone.au()` |
+| Fixed GMT | GMT+0 | GMT+0 | none | `ServerZone.fixed(0)` |
+| Fixed GMT+2 | GMT+2 | GMT+2 | none | `ServerZone.fixed(2)` |
+| Any other clock | | | | `ServerZone.us(3)`, `ServerZone.fixed(5.75)`, `ServerZone("Asia/Tokyo")`, `ServerZone("Europe/Berlin", timedelta(hours=1))` |
+
+A `ServerZone` is the wall clock of an IANA zone plus a shift in 15-minute steps; `str(zone)` describes it, for
+example `GMT+2/+3 (US daylight saving)`.
+
+## How detection works
+
+1. A gap of 40 hours or more after a bar is a weekend; that bar's end is the weekly close on the server clock.
+2. The forex week ends on Friday at 17:00 New York, so each close gives the server's offset that week. Brokers close
+   at or before 17:00, never after, so the offset is rounded up to the next 15 minutes.
+3. Every candidate clock (fixed, or US, EU or Australian daylight saving, at any base offset) predicts each week.
+4. The clock that predicts the most weeks wins; the weeks it misses are `outliers` (early holiday closes), and closes
+   that fit no Friday are `unexplained`.
+5. A tie means the data cannot tell the clocks apart, and `zone` is `None`: use a longer span.
+
+Detection needs a forex major and bars from M1 to H1 (`timeframe` 60 to 3600 seconds; longer bars are rejected
+because they end on the server's own 4-hour or day boundaries and hide the switch weeks). Use M15 or shorter for
+clocks with 30- or 45-minute offsets. The data should cover at least six months, or a span that includes March or
+late October to early November.
+
+## API
+
+| Name | Purpose |
+|---|---|
+| `ServerZone(zone, shift)`, `.us()`, `.eu()`, `.au()`, `.fixed()` | the server clock |
+| `zone.to_utc(server_time, ambiguous="raise")` | server epoch seconds or naive server datetime to aware UTC |
+| `zone.server_timestamp(instant)`, `zone.to_server(instant)` | aware instant to server epoch int, or naive server datetime |
+| `zone.offset_at(instant)` | the server's UTC offset at an aware instant |
+| `detect(bar_times, timeframe=3600)` | the clock from M1 to H1 bar history, as a `Detection` |
+| `measure_offset(server_times, now=None, tolerance=60)` | the current offset from a fresh tick and the PC clock |
+| `check(zone, server_times, now=None, tolerance=60, max_age=300)` | whether live ticks agree with a zone |
+| `brokerclock.pandas`: `to_utc`, `frame_to_utc`, `to_server_timestamps` | the same conversions for whole columns |
+
+The library's own errors share the base class `BrokerClockError`, a `ValueError`: `AmbiguousTimeError`,
+`NonexistentTimeError`, `NotEnoughData`, `StaleTickError`, `OffsetOutOfRange` and `ZoneMismatchError`. Invalid
+arguments raise a plain `ValueError` or `TypeError`.
+
+## Limitations
+
+- When a broker switches the clock of 24/7 symbols (crypto CFDs) is broker-specific, so bars of those symbols right
+  at a switch can be an hour off.
+- Metals and indices follow their own exchange hours; detect the clock from a forex major.
+- Live measurement depends on the PC clock; keep automatic time sync on.
+- A broker's demo and live servers can run different clocks; detect each one.
+- A broker that changes its clock may rewrite its history in the new clock; detect again after a change.
+- Weekly closes less than 14 minutes before 17:00 New York are handled (16:50 in M5 bars, 16:47 or later in M1
+  bars). If the last bar of a week ends 14 minutes or more early (16:40, say), that week reads 15 minutes off. A
+  few such weeks become `outliers`; if every week ends that way, the whole result is 15 minutes off, for example
+  GMT+1:45/+2:45 instead of GMT+2/+3. H1 bars avoid this, because the last H1 bar still ends at 17:00.
+
+## Notes
+
+Not affiliated with MetaQuotes. MetaTrader is a trademark of MetaQuotes Ltd.
+
+Copyright 2026 Raeez alshamaly. Licensed under the Apache License, Version 2.0; see [LICENSE](LICENSE).

brokerclock-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+brokerclock/__init__.py,sha256=KHzdfk2fFG_M-KxiYA8dUXkjyoNCtebEaH3RoOsbjMI,1243
+brokerclock/_detect.py,sha256=yP1wZNX0G5E8otdNjwJmP0K3ZUFamQSB4optDAqJPw4,8461
+brokerclock/_errors.py,sha256=nFLMvmnShtPom5_nLqPVvp-T5CSYF9UlPYrd4O13Xag,1031
+brokerclock/_live.py,sha256=M-rr6Agvi51QdnY8KCC-6KTgVmWcm86Ctj3Hyg6MoVY,5083
+brokerclock/_zone.py,sha256=wjhS5iwZPYsFVhFC-cUSzxNamQhfddFXkkxBvOtgk40,10447
+brokerclock/pandas.py,sha256=whwFw_AhBNaz-XW4GWUkacWKof1-16c3lvEACVQiTl0,3375
+brokerclock/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+brokerclock-0.1.0.dist-info/METADATA,sha256=1PuXtcEmQIkOPcBLPAgzfY2KacEwH-o_e7NNPk76DDQ,10275
+brokerclock-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+brokerclock-0.1.0.dist-info/licenses/LICENSE,sha256=6N4ac5NFfpyIdot45rp5BiL777BAzkgZTCyw8bbU6f8,11562
+brokerclock-0.1.0.dist-info/RECORD,,

brokerclock-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

brokerclock-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.