ga-clock 0.2.0__py3-none-any.whl

ga_clock/__init__.py

@@ -0,0 +1,16 @@
+"""GA Clock: controllable clocks and internal-time scheduling."""
+
+from ._api import CancelJob, Clock, Elapsed, Job
+from ._version import __version__
+from .exceptions import ClockError, GAClockError, GAClockWarning
+
+__all__ = [
+    "CancelJob",
+    "Clock",
+    "ClockError",
+    "Elapsed",
+    "GAClockError",
+    "GAClockWarning",
+    "Job",
+    "__version__",
+]

ga_clock/_api.py

@@ -0,0 +1,720 @@
+"""Internal implementation for the public GA Clock API."""
+
+from __future__ import annotations
+
+import time as time_module
+from collections.abc import Callable, Hashable, Mapping
+from dataclasses import dataclass, field, replace
+from datetime import date, datetime, time, timedelta, tzinfo
+from types import MappingProxyType
+from typing import Any, Final, Literal, TypeAlias, cast
+
+from .exceptions import ClockError
+
+ClockMode = Literal["realtime", "wrap", "fixed", "scheduled", "manual"]
+DeltaLike: TypeAlias = timedelta | int | float
+DatetimeLike: TypeAlias = datetime | str
+TimeSource = Callable[[], float]
+
+SECONDS_PER_DAY = 86_400
+DAYS_PER_GREGORIAN_YEAR = 365.2425
+SECONDS_PER_GREGORIAN_YEAR = SECONDS_PER_DAY * DAYS_PER_GREGORIAN_YEAR
+SECONDS_PER_GREGORIAN_MONTH = SECONDS_PER_GREGORIAN_YEAR / 12
+
+
+class _CancelJob:
+    """Sentinel returned by a job to remove itself from the scheduler."""
+
+
+CancelJob: Final = _CancelJob()
+
+
+@dataclass(frozen=True)
+class Elapsed:
+    """Elapsed duration represented with several convenient units."""
+
+    delta: timedelta
+    seconds: float
+    minutes: float
+    hours: float
+    days: float
+    months: float
+    years: float
+
+
+@dataclass(eq=False, frozen=True)
+class Job:
+    """A scheduled job created by :meth:`Clock.every`.
+
+    Jobs are usually configured fluently:
+
+    ```python
+    clock.every(5).minutes.do(send_heartbeat).tag("heartbeat")
+    ```
+    """
+
+    scheduler: _Scheduler
+    interval: int = 1
+    unit: str | None = None
+    at_time: time | None = None
+    start_day: int | None = None
+    tags: frozenset[Hashable] = field(default_factory=frozenset)
+    job_func: Callable[..., Any] | None = None
+    args: tuple[Any, ...] = field(default_factory=tuple)
+    kwargs: Mapping[str, Any] = field(default_factory=lambda: MappingProxyType({}))
+    last_run: datetime | None = None
+    next_run: datetime | None = None
+    _identity: object = field(default_factory=object, repr=False)
+
+    @property
+    def second(self) -> Job:
+        return self.seconds
+
+    @property
+    def seconds(self) -> Job:
+        return self._with_unit("seconds")
+
+    @property
+    def minute(self) -> Job:
+        return self.minutes
+
+    @property
+    def minutes(self) -> Job:
+        return self._with_unit("minutes")
+
+    @property
+    def hour(self) -> Job:
+        return self.hours
+
+    @property
+    def hours(self) -> Job:
+        return self._with_unit("hours")
+
+    @property
+    def day(self) -> Job:
+        return self.days
+
+    @property
+    def days(self) -> Job:
+        return self._with_unit("days")
+
+    @property
+    def week(self) -> Job:
+        return self.weeks
+
+    @property
+    def weeks(self) -> Job:
+        return self._with_unit("weeks")
+
+    @property
+    def month(self) -> Job:
+        return self.months
+
+    @property
+    def months(self) -> Job:
+        return self._with_unit("months")
+
+    @property
+    def year(self) -> Job:
+        return self.years
+
+    @property
+    def years(self) -> Job:
+        return self._with_unit("years")
+
+    @property
+    def monday(self) -> Job:
+        return self._with_weekday(0)
+
+    @property
+    def tuesday(self) -> Job:
+        return self._with_weekday(1)
+
+    @property
+    def wednesday(self) -> Job:
+        return self._with_weekday(2)
+
+    @property
+    def thursday(self) -> Job:
+        return self._with_weekday(3)
+
+    @property
+    def friday(self) -> Job:
+        return self._with_weekday(4)
+
+    @property
+    def saturday(self) -> Job:
+        return self._with_weekday(5)
+
+    @property
+    def sunday(self) -> Job:
+        return self._with_weekday(6)
+
+    def at(self, value: str) -> Job:
+        """Run at a specific clock time within the selected interval."""
+
+        self._ensure_not_scheduled()
+        if self.unit is None:
+            raise ClockError("Choose a time unit before calling at().")
+        configured = replace(self, at_time=_parse_at_time(value, self.unit))
+        self.scheduler.replace(self, configured)
+        return configured
+
+    def tag(self, *tags: Hashable) -> Job:
+        """Attach one or more tags to the job."""
+
+        configured = replace(self, tags=self.tags.union(tags))
+        self.scheduler.replace(self, configured)
+        return configured
+
+    def do(self, job_func: Callable[..., Any], *args: Any, **kwargs: Any) -> Job:
+        """Register the job function and add the job to the scheduler."""
+
+        self._ensure_not_scheduled()
+        if self.unit is None:
+            raise ClockError("Choose a time unit before calling do().")
+        configured = replace(
+            self,
+            job_func=job_func,
+            args=args,
+            kwargs=MappingProxyType(dict(kwargs)),
+        )
+        object.__setattr__(configured, "next_run", configured._next_after(self.scheduler.now()))
+        self.scheduler.add(configured)
+        return configured
+
+    def cancel(self) -> Job:
+        """Remove this job from its scheduler."""
+
+        self.scheduler.cancel(self)
+        return self
+
+    def run(self) -> Any:
+        """Execute the job function once and schedule the next run."""
+
+        if self.job_func is None:
+            raise ClockError("Cannot run a job before do() has been called.")
+
+        result = self.job_func(*self.args, **self.kwargs)
+        last_run = self.scheduler.now()
+        object.__setattr__(self, "last_run", last_run)
+
+        if result is CancelJob:
+            self.scheduler.cancel(self)
+        else:
+            object.__setattr__(self, "next_run", self._next_after(last_run))
+
+        return result
+
+    def _with_unit(self, unit: str) -> Job:
+        self._ensure_not_scheduled()
+        configured = replace(self, unit=unit)
+        self.scheduler.replace(self, configured)
+        return configured
+
+    def _with_weekday(self, weekday: int) -> Job:
+        self._ensure_not_scheduled()
+        configured = replace(self, unit="weeks", start_day=weekday)
+        self.scheduler.replace(self, configured)
+        return configured
+
+    def _ensure_not_scheduled(self) -> None:
+        if self.job_func is not None:
+            raise ClockError("A scheduled job cannot be reconfigured; create a new job instead.")
+
+    def _next_after(self, reference: datetime) -> datetime:
+        if self.unit is None:
+            raise ClockError("A scheduled job needs a time unit.")
+
+        if self.unit == "seconds":
+            return reference + timedelta(seconds=self.interval)
+        if self.unit == "minutes":
+            return self._next_subdaily_after(reference, "minutes")
+        if self.unit == "hours":
+            return self._next_subdaily_after(reference, "hours")
+        if self.unit == "days":
+            return self._next_daily_after(reference)
+        if self.unit == "weeks":
+            return self._next_weekly_after(reference)
+        if self.unit == "months":
+            return self._next_calendar_after(reference, months=self.interval)
+        if self.unit == "years":
+            return self._next_calendar_after(reference, years=self.interval)
+
+        raise ClockError(f"Unsupported time unit: {self.unit!r}")
+
+    def _next_subdaily_after(self, reference: datetime, unit: str) -> datetime:
+        if self.at_time is None:
+            if unit == "minutes":
+                return reference + timedelta(minutes=self.interval)
+            return reference + timedelta(hours=self.interval)
+
+        if unit == "minutes":
+            candidate = reference.replace(second=self.at_time.second, microsecond=0)
+            delta = timedelta(minutes=self.interval)
+        else:
+            candidate = reference.replace(
+                minute=self.at_time.minute,
+                second=self.at_time.second,
+                microsecond=0,
+            )
+            delta = timedelta(hours=self.interval)
+
+        while candidate <= reference:
+            candidate += delta
+        return candidate
+
+    def _next_daily_after(self, reference: datetime) -> datetime:
+        if self.at_time is None:
+            return reference + timedelta(days=self.interval)
+
+        candidate = datetime.combine(reference.date(), self.at_time, tzinfo=reference.tzinfo)
+        while candidate <= reference:
+            candidate += timedelta(days=self.interval)
+        return candidate
+
+    def _next_weekly_after(self, reference: datetime) -> datetime:
+        if self.start_day is None:
+            if self.at_time is None:
+                return reference + timedelta(weeks=self.interval)
+            candidate = datetime.combine(reference.date(), self.at_time, tzinfo=reference.tzinfo)
+            while candidate <= reference:
+                candidate += timedelta(weeks=self.interval)
+            return candidate
+
+        days_ahead = (self.start_day - reference.weekday()) % 7
+        candidate_date = reference.date() + timedelta(days=days_ahead)
+        candidate_time = self.at_time or reference.time().replace(microsecond=0)
+        candidate = datetime.combine(candidate_date, candidate_time, tzinfo=reference.tzinfo)
+
+        while candidate <= reference:
+            candidate += timedelta(weeks=self.interval)
+        return candidate
+
+    def _next_calendar_after(
+        self,
+        reference: datetime,
+        months: int = 0,
+        years: int = 0,
+    ) -> datetime:
+        candidate = reference
+        if months:
+            candidate = _add_months(candidate, months)
+        if years:
+            candidate = _add_months(candidate, years * 12)
+        if self.at_time is not None:
+            candidate = candidate.replace(
+                hour=self.at_time.hour,
+                minute=self.at_time.minute,
+                second=self.at_time.second,
+                microsecond=0,
+            )
+        return candidate
+
+
+class Clock:
+    """A controllable datetime source with an internal-time scheduler."""
+
+    def __init__(
+        self,
+        mode: ClockMode = "realtime",
+        start_at: DatetimeLike | None = None,
+        factor: float = 1.0,
+        step: DeltaLike = timedelta(seconds=1),
+        tz: tzinfo | None = None,
+        monotonic: TimeSource = time_module.monotonic,
+        auto_run_due: bool = True,
+    ) -> None:
+        self._mode = _validate_mode(mode)
+        self._factor = _validate_factor(factor)
+        self._fixed_step = _coerce_delta(step)
+        self._start_at = _coerce_datetime(start_at, tz)
+        self._current = self._start_at
+        self._monotonic = monotonic
+        self._real_start = self._monotonic()
+        self._scheduler = _Scheduler(self)
+        self.auto_run_due = auto_run_due
+
+    @classmethod
+    def realtime(
+        cls,
+        start_at: DatetimeLike | None = None,
+        tz: tzinfo | None = None,
+    ) -> Clock:
+        """Create a clock that advances at wall-clock speed."""
+
+        return cls(mode="realtime", start_at=start_at, tz=tz)
+
+    @classmethod
+    def wrap(
+        cls,
+        factor: float = 1.0,
+        start_at: DatetimeLike | None = None,
+        tz: tzinfo | None = None,
+    ) -> Clock:
+        """Create a clock that advances at ``factor * real_time``."""
+
+        return cls(mode="wrap", start_at=start_at, factor=factor, tz=tz)
+
+    @classmethod
+    def fixed(
+        cls,
+        step: DeltaLike = timedelta(seconds=1),
+        start_at: DatetimeLike | None = None,
+        tz: tzinfo | None = None,
+    ) -> Clock:
+        """Create a clock that advances by a fixed delta on every step."""
+
+        return cls(mode="fixed", start_at=start_at, step=step, tz=tz)
+
+    @classmethod
+    def scheduled(
+        cls,
+        start_at: DatetimeLike | None = None,
+        tz: tzinfo | None = None,
+    ) -> Clock:
+        """Create a clock that jumps to the next scheduled job on step."""
+
+        return cls(mode="scheduled", start_at=start_at, tz=tz)
+
+    @classmethod
+    def manual(
+        cls,
+        start_at: DatetimeLike | None = None,
+        tz: tzinfo | None = None,
+    ) -> Clock:
+        """Create a clock that advances only by explicit step amounts."""
+
+        return cls(mode="manual", start_at=start_at, tz=tz)
+
+    @property
+    def mode(self) -> ClockMode:
+        """The active clock mode."""
+
+        return self._mode
+
+    @property
+    def start_at(self) -> datetime:
+        """The datetime used as the internal clock origin."""
+
+        return self._start_at
+
+    def now(self) -> datetime:
+        """Return the current internal datetime."""
+
+        if self._mode in {"realtime", "wrap"}:
+            elapsed_seconds = (self._monotonic() - self._real_start) * self._factor
+            return self._start_at + timedelta(seconds=elapsed_seconds)
+        return self._current
+
+    def elapsed(self) -> timedelta:
+        """Return the elapsed internal duration since initialization."""
+
+        return self.now() - self._start_at
+
+    def elapsed_seconds(self) -> float:
+        return self.elapsed().total_seconds()
+
+    def elapsed_minutes(self) -> float:
+        return self.elapsed_seconds() / 60
+
+    def elapsed_hours(self) -> float:
+        return self.elapsed_seconds() / 3_600
+
+    def elapsed_days(self) -> float:
+        return self.elapsed_seconds() / SECONDS_PER_DAY
+
+    def elapsed_months(self) -> float:
+        return self.elapsed_seconds() / SECONDS_PER_GREGORIAN_MONTH
+
+    def elapsed_years(self) -> float:
+        return self.elapsed_seconds() / SECONDS_PER_GREGORIAN_YEAR
+
+    def elapsed_values(self) -> Elapsed:
+        """Return elapsed time in all supported units."""
+
+        delta = self.elapsed()
+        seconds = delta.total_seconds()
+        return Elapsed(
+            delta=delta,
+            seconds=seconds,
+            minutes=seconds / 60,
+            hours=seconds / 3_600,
+            days=seconds / SECONDS_PER_DAY,
+            months=seconds / SECONDS_PER_GREGORIAN_MONTH,
+            years=seconds / SECONDS_PER_GREGORIAN_YEAR,
+        )
+
+    def step(
+        self,
+        amount: DeltaLike | None = None,
+        *,
+        seconds: float = 0,
+        minutes: float = 0,
+        hours: float = 0,
+        days: float = 0,
+        weeks: float = 0,
+        run_due: bool | None = None,
+    ) -> Clock:
+        """Advance the clock according to its mode and return ``self``.
+
+        Fixed clocks ignore wall-clock time and use the configured fixed step.
+        Manual clocks require an explicit amount, either as a positional
+        `timedelta`/seconds value or as keyword units. Scheduled clocks jump to
+        the next scheduled job. Realtime and wrap clocks only run pending jobs.
+        """
+
+        should_run = self.auto_run_due if run_due is None else run_due
+
+        if self._mode == "fixed":
+            if amount is not None or any([seconds, minutes, hours, days, weeks]):
+                raise ClockError("fixed clocks use their configured step; pass no step amount.")
+            self._current += self._fixed_step
+        elif self._mode == "manual":
+            delta = _coerce_delta(
+                amount,
+                seconds=seconds,
+                minutes=minutes,
+                hours=hours,
+                days=days,
+                weeks=weeks,
+            )
+            if delta == timedelta(0):
+                raise ClockError("manual clocks require a non-zero step amount.")
+            self._current += delta
+        elif self._mode == "scheduled":
+            if amount is not None or any([seconds, minutes, hours, days, weeks]):
+                raise ClockError("scheduled clocks advance to the next job; pass no step amount.")
+            next_run = self.next_run()
+            if next_run is not None:
+                self._current = next_run
+        elif self._mode in {"realtime", "wrap"}:
+            if amount is not None or any([seconds, minutes, hours, days, weeks]):
+                message = f"{self._mode} clocks advance from real time; pass no step amount."
+                raise ClockError(message)
+        else:
+            raise ClockError(f"Unsupported mode: {self._mode!r}")
+
+        if should_run:
+            self.run_pending()
+        return self
+
+    def every(self, interval: int = 1) -> Job:
+        """Start building a scheduled job."""
+
+        if interval < 1:
+            raise ClockError("Job interval must be at least 1.")
+        return Job(scheduler=self._scheduler, interval=interval)
+
+    def run_pending(self) -> list[Any]:
+        """Run all jobs due at the current internal time."""
+
+        return self._scheduler.run_pending()
+
+    def run_all(self) -> list[Any]:
+        """Run all scheduled jobs once, regardless of their next run time."""
+
+        return self._scheduler.run_all()
+
+    def next_run(self) -> datetime | None:
+        """Return the next scheduled internal datetime, if any."""
+
+        return self._scheduler.next_run()
+
+    def jobs(self, tag: Hashable | None = None) -> list[Job]:
+        """Return scheduled jobs, optionally filtered by tag."""
+
+        return self._scheduler.jobs(tag)
+
+    def cancel(self, job: Job) -> Clock:
+        """Cancel a scheduled job and return ``self``."""
+
+        self._scheduler.cancel(job)
+        return self
+
+    def clear(self, *tags: Hashable) -> Clock:
+        """Clear all jobs, or only jobs matching one of the provided tags."""
+
+        self._scheduler.clear(*tags)
+        return self
+
+
+class _Scheduler:
+    def __init__(self, clock: Clock) -> None:
+        self.clock = clock
+        self._jobs: list[Job] = []
+
+    def now(self) -> datetime:
+        return self.clock.now()
+
+    def add(self, job: Job) -> None:
+        for index, existing in enumerate(self._jobs):
+            if existing._identity is job._identity:
+                self._jobs[index] = job
+                break
+        else:
+            self._jobs.append(job)
+        self._sort()
+
+    def cancel(self, job: Job) -> None:
+        self._jobs = [
+            existing for existing in self._jobs if existing._identity is not job._identity
+        ]
+
+    def replace(self, old: Job, new: Job) -> None:
+        for index, existing in enumerate(self._jobs):
+            if existing._identity is old._identity:
+                self._jobs[index] = new
+                self._sort()
+                return
+
+    def contains(self, job: Job) -> bool:
+        return any(existing._identity is job._identity for existing in self._jobs)
+
+    def clear(self, *tags: Hashable) -> None:
+        if not tags:
+            self._jobs.clear()
+            return
+
+        tag_set = set(tags)
+        self._jobs = [job for job in self._jobs if job.tags.isdisjoint(tag_set)]
+
+    def jobs(self, tag: Hashable | None = None) -> list[Job]:
+        if tag is None:
+            return list(self._jobs)
+        return [job for job in self._jobs if tag in job.tags]
+
+    def next_run(self) -> datetime | None:
+        scheduled = [job.next_run for job in self._jobs if job.next_run is not None]
+        if not scheduled:
+            return None
+        return min(scheduled)
+
+    def run_pending(self) -> list[Any]:
+        now = self.now()
+        due_jobs = [
+            job
+            for job in sorted(self._jobs, key=lambda item: item.next_run or datetime.max)
+            if job.next_run is not None and job.next_run <= now
+        ]
+
+        results = []
+        for job in due_jobs:
+            if self.contains(job):
+                results.append(job.run())
+        self._sort()
+        return results
+
+    def run_all(self) -> list[Any]:
+        results = []
+        for job in list(self._jobs):
+            if self.contains(job):
+                results.append(job.run())
+        self._sort()
+        return results
+
+    def _sort(self) -> None:
+        self._jobs.sort(key=lambda job: job.next_run or datetime.max)
+
+
+def _validate_mode(mode: str) -> ClockMode:
+    if mode not in {"realtime", "wrap", "fixed", "scheduled", "manual"}:
+        raise ClockError(
+            "mode must be one of: 'realtime', 'wrap', 'fixed', 'scheduled', 'manual'."
+        )
+    return cast(ClockMode, mode)
+
+
+def _validate_factor(factor: float) -> float:
+    if factor <= 0:
+        raise ClockError("factor must be greater than zero.")
+    return factor
+
+
+def _coerce_datetime(value: DatetimeLike | None, tz: tzinfo | None) -> datetime:
+    if value is None:
+        return datetime.now(tz)
+    if isinstance(value, str):
+        value = datetime.fromisoformat(value)
+    if tz is not None and value.tzinfo is None:
+        return value.replace(tzinfo=tz)
+    return value
+
+
+def _coerce_delta(
+    value: DeltaLike | None = None,
+    *,
+    seconds: float = 0,
+    minutes: float = 0,
+    hours: float = 0,
+    days: float = 0,
+    weeks: float = 0,
+) -> timedelta:
+    if value is None:
+        delta = timedelta(0)
+    elif isinstance(value, timedelta):
+        delta = value
+    elif isinstance(value, (int, float)):
+        delta = timedelta(seconds=value)
+    else:
+        raise ClockError("Expected a timedelta or a numeric seconds value.")
+
+    return delta + timedelta(seconds=seconds, minutes=minutes, hours=hours, days=days, weeks=weeks)
+
+
+def _parse_at_time(value: str, unit: str) -> time:
+    parts = value.split(":")
+    if unit == "minutes":
+        if len(parts) != 2 or parts[0] != "":
+            raise ClockError("Minute jobs use at(':SS').")
+        return time(second=_bounded_int(parts[1], 0, 59, "second"))
+
+    if unit == "hours":
+        if len(parts) == 2 and parts[0] == "":
+            return time(minute=_bounded_int(parts[1], 0, 59, "minute"))
+        if len(parts) == 3 and parts[0] == "":
+            return time(
+                minute=_bounded_int(parts[1], 0, 59, "minute"),
+                second=_bounded_int(parts[2], 0, 59, "second"),
+            )
+        raise ClockError("Hourly jobs use at(':MM') or at(':MM:SS').")
+
+    if unit in {"days", "weeks", "months", "years"}:
+        if len(parts) == 2:
+            return time(
+                hour=_bounded_int(parts[0], 0, 23, "hour"),
+                minute=_bounded_int(parts[1], 0, 59, "minute"),
+            )
+        if len(parts) == 3:
+            return time(
+                hour=_bounded_int(parts[0], 0, 23, "hour"),
+                minute=_bounded_int(parts[1], 0, 59, "minute"),
+                second=_bounded_int(parts[2], 0, 59, "second"),
+            )
+        raise ClockError("Daily and larger jobs use at('HH:MM') or at('HH:MM:SS').")
+
+    raise ClockError(f"at() is not supported for {unit} jobs.")
+
+
+def _bounded_int(value: str, minimum: int, maximum: int, name: str) -> int:
+    try:
+        parsed = int(value)
+    except ValueError as exc:
+        raise ClockError(f"{name} must be an integer.") from exc
+
+    if parsed < minimum or parsed > maximum:
+        raise ClockError(f"{name} must be between {minimum} and {maximum}.")
+    return parsed
+
+
+def _add_months(value: datetime, months: int) -> datetime:
+    month_index = value.month - 1 + months
+    year = value.year + month_index // 12
+    month = month_index % 12 + 1
+    day = min(value.day, _days_in_month(year, month))
+    return value.replace(year=year, month=month, day=day)
+
+
+def _days_in_month(year: int, month: int) -> int:
+    next_month = date(year + 1, 1, 1) if month == 12 else date(year, month + 1, 1)
+    return (next_month - date(year, month, 1)).days

ga_clock/_version.py

@@ -0,0 +1,3 @@
+"""Package version: the single source of truth for builds and releases."""
+
+__version__ = "0.2.0"

ga_clock/exceptions.py

@@ -0,0 +1,15 @@
+"""Public exceptions and warnings raised by GA Clock."""
+
+from __future__ import annotations
+
+
+class GAClockError(Exception):
+    """Base exception for all GA Clock errors."""
+
+
+class ClockError(GAClockError, ValueError):
+    """Raised when an operation is invalid for the selected clock mode."""
+
+
+class GAClockWarning(UserWarning):
+    """Base warning for non-fatal GA Clock conditions."""

ga_clock/py.typed

@@ -0,0 +1 @@
+

ga_clock-0.2.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: ga-clock
+Version: 0.2.0
+Summary: GA Clock is a controllable Python clock with realtime, accelerated, fixed, scheduled, and manual time modes.
+Author: GA Clock contributors
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/andreagemma/clock#readme
+Project-URL: Issues, https://github.com/andreagemma/clock/issues
+Project-URL: Source, https://github.com/andreagemma/clock
+Keywords: ga-clock,clock,scheduler,time,testing,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# GA Clock
+
+[![CI](https://github.com/andreagemma/clock/actions/workflows/ci.yml/badge.svg)](https://github.com/andreagemma/clock/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ga-clock.svg)](https://pypi.org/project/ga-clock/)
+[![Python](https://img.shields.io/pypi/pyversions/ga-clock.svg)](https://pypi.org/project/ga-clock/)
+
+GA Clock provides a controllable datetime source and an internal-time scheduler for
+applications, simulations, and deterministic tests. A clock can follow wall time,
+accelerate it, advance in fixed or manual steps, or jump directly between scheduled
+events. The scheduler always uses the selected clock's internal time.
+
+## Installation
+
+The PyPI distribution is named `ga-clock`; the import package is named `ga_clock`.
+
+```bash
+python -m pip install ga-clock
+```
+
+GA Clock has no runtime dependencies. Development and test tools are available as
+extras:
+
+```bash
+python -m pip install -e ".[test]"
+python -m pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from datetime import datetime
+
+from ga_clock import Clock
+
+clock = Clock.manual(start_at=datetime(2026, 1, 1, 9, 0))
+clock.step(hours=2)
+
+assert clock.now() == datetime(2026, 1, 1, 11, 0)
+assert clock.elapsed_hours() == 2
+```
+
+When `start_at` is omitted, the clock starts at the current datetime. It also accepts
+an ISO datetime string and an optional `tzinfo` object.
+
+## Clock Modes
+
+| Mode | Internal-time behavior | `step()` behavior |
+| --- | --- | --- |
+| `realtime` | Advances at wall-clock speed | Runs due jobs without moving time directly |
+| `wrap` | Advances at `factor * wall time` | Runs due jobs without moving time directly |
+| `fixed` | Changes only when stepped | Advances by the configured fixed duration |
+| `scheduled` | Changes only when stepped | Jumps to the next scheduled event |
+| `manual` | Changes only when stepped | Advances by the supplied duration |
+
+### Realtime and Wrap
+
+```python
+from ga_clock import Clock
+
+realtime = Clock.realtime()
+accelerated = Clock.wrap(factor=60)
+```
+
+A wrap factor of `60` advances internal time by one minute for every elapsed wall-time
+second. Factors must be greater than zero.
+
+### Fixed and Manual
+
+```python
+from datetime import timedelta
+
+from ga_clock import Clock
+
+fixed = Clock.fixed(step=timedelta(minutes=15))
+fixed.step().step()
+assert fixed.elapsed_minutes() == 30
+
+manual = Clock.manual()
+manual.step(minutes=5).step(seconds=30)
+assert manual.elapsed_seconds() == 330
+```
+
+### Scheduled
+
+```python
+from datetime import datetime
+
+from ga_clock import Clock
+
+events: list[datetime] = []
+clock = Clock.scheduled(start_at=datetime(2026, 1, 1, 9, 0))
+clock.every().hour.do(lambda: events.append(clock.now()))
+
+clock.step()
+
+assert events == [datetime(2026, 1, 1, 10, 0)]
+```
+
+Calling `step()` with no jobs scheduled is a no-op.
+
+## Scheduling
+
+The fluent API is inspired by `schedule`, but all configuration operations return new
+objects instead of mutating earlier builder values.
+
+```python
+from datetime import datetime
+
+from ga_clock import Clock
+
+calls: list[str] = []
+clock = Clock.manual(start_at=datetime(2026, 1, 1, 8, 0))
+
+heartbeat = clock.every(10).seconds.do(lambda: calls.append("heartbeat"))
+report = clock.every().monday.at("10:00").do(
+    lambda: calls.append("report")
+).tag("reports")
+
+clock.step(seconds=10)
+assert calls == ["heartbeat"]
+
+clock.cancel(heartbeat)
+clock.clear("reports")
+assert clock.jobs() == []
+```
+
+Supported units are seconds, minutes, hours, days, weeks, months, and years. Weekday
+properties from `monday` through `sunday` are also available. `at()` accepts:
+
+- `:SS` for minute jobs;
+- `:MM` or `:MM:SS` for hourly jobs;
+- `HH:MM` or `HH:MM:SS` for daily and larger jobs.
+
+Returning `CancelJob` removes a job immediately after it runs:
+
+```python
+from ga_clock import CancelJob
+
+
+def run_once() -> object:
+    return CancelJob
+```
+
+## Elapsed Time
+
+```python
+clock.elapsed()          # datetime.timedelta
+clock.elapsed_seconds()  # float
+clock.elapsed_minutes()  # float
+clock.elapsed_hours()    # float
+clock.elapsed_days()     # float
+clock.elapsed_months()   # float
+clock.elapsed_years()    # float
+clock.elapsed_values()   # immutable Elapsed dataclass
+```
+
+Months and years are duration approximations based on the average Gregorian year of
+365.2425 days; they are not calendar-boundary counts.
+
+## Errors
+
+Invalid modes, factors, durations, schedule formats, and mode-specific operations raise
+`ClockError`. It derives from both `GAClockError` and `ValueError`. Non-fatal package
+warnings derive from `GAClockWarning`.
+
+Scheduled job callbacks propagate their exceptions to the caller of `step()`,
+`run_pending()`, or `run_all()`; GA Clock does not silently suppress callback failures.
+
+## Security
+
+GA Clock does not deserialize data or load executable content. Scheduled callbacks are
+ordinary Python callables and execute with the permissions of the current process. Only
+schedule callbacks from trusted application code.
+
+## Development
+
+GA Clock supports Python 3.10 and newer.
+
+```bash
+python -m pip install -e ".[dev]"
+python -m compileall -q src
+python -m pytest --cov=ga_clock --cov-report=term-missing
+ruff check .
+mypy
+python -m pip check
+python -m build
+python -m twine check dist/*
+```
+
+## Releases
+
+`src/ga_clock/_version.py` is the only version source. To publish a release:
+
+1. Update `__version__` in `_version.py` and commit the release changes.
+2. Push `main` and wait for CI to pass.
+3. Configure the PyPI Trusted Publisher with project `ga-clock`, owner `andreagemma`,
+   repository `ga-clock`, workflow `release.yml`, and environment `pypi`.
+4. Run the **Create release** GitHub Actions workflow. With no override it creates the
+   `v<version>` tag, creates release notes, and explicitly dispatches the build and PyPI
+   publication workflow.
+
+PyPI versions are immutable. Increment `_version.py` before publishing different
+content.
+
+## License
+
+GA Clock is distributed under the MIT License. See [LICENSE](LICENSE).

ga_clock-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ga_clock/__init__.py,sha256=XPeADzR9LA7yy0Sqa-gS11TYzfFdU5MRFhmV0rnO0dg,365
+ga_clock/_api.py,sha256=gEMxAii-gLUwrKjTP0O8rnzrzZvK4gbfNbofylj9tW4,23066
+ga_clock/_version.py,sha256=TvH7SkPKsvdPulwBwEaEgs2Vf0g_FGjej1jP8oFmiwQ,98
+ga_clock/exceptions.py,sha256=NYGXGpwB0hXAlZSN9O7r0cmr572f9cH7uEI0WMWsH_o,392
+ga_clock/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+ga_clock-0.2.0.dist-info/licenses/LICENSE,sha256=npXSAB3WakiK5W7m4VZUYNEIzLBP6IxMpi8AeOyVwrI,1078
+ga_clock-0.2.0.dist-info/METADATA,sha256=t2DOlTAgmX2pefneMJ8TgKsf2QFE5orZpoPnwm3oaTQ,7380
+ga_clock-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ga_clock-0.2.0.dist-info/top_level.txt,sha256=AbFxNAAriBBon7u1lHGtTBGOhTiLif8cN14JGXaW9mw,9
+ga_clock-0.2.0.dist-info/RECORD,,

ga_clock-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ga_clock-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GA Clock contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ga_clock-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ga_clock