SimPyTick 0.0.1__py3-none-any.whl

simpytick/__init__.py

@@ -0,0 +1,11 @@
+"""SimPyTick (Simple Python Tick)."""
+
+import logging
+
+from simpytick._version import __version__
+from simpytick.sleep import sleep
+from simpytick.sleep_2 import CompensatedSleep as sleep_2
+
+__all__ = ["sleep", "sleep_2"]
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())

simpytick/_version.py

@@ -0,0 +1,3 @@
+"""Single version source for package imports and distribution metadata."""
+
+__version__ = "0.0.1"

simpytick/_worker.py

@@ -0,0 +1,13 @@
+"""Report background worker completion and failures to its owner."""
+
+
+def run_worker(target, args, kwargs, status):
+    """Run a target and send a bounded, serializable terminal status."""
+    try:
+        target(*args, **kwargs)
+    except BaseException as error:  # pylint: disable=broad-exception-caught
+        status.send(("error", f"{type(error).__name__}: {str(error)[:1000]}"))
+    else:
+        status.send(("done", None))
+    finally:
+        status.close()

simpytick/logger.py

@@ -0,0 +1,183 @@
+"""
+Logging utilities: ``GrpcLogger`` adapter with project-specific levels and
+a ``get_logger`` factory that attaches console + rotating file handlers.
+"""
+import logging
+import tempfile
+import warnings
+from datetime import datetime
+from logging.handlers import TimedRotatingFileHandler
+from pathlib import Path
+
+import coloredlogs
+
+INTERNAL_DEBUG = 5
+INTERNAL_INFO = 7
+
+
+class GrpcLogger(logging.LoggerAdapter):
+    """Adapt a standard logger with custom levels without changing its class."""
+
+    def __init__(self, logger: logging.Logger | str):
+        super().__init__(logging.getLogger(logger) if isinstance(logger, str) else logger, {})
+
+    @property
+    def handlers(self):
+        """Return the underlying logger's handlers."""
+        return self.logger.handlers
+
+    @property
+    def level(self) -> int:
+        """Return the underlying logger's configured level."""
+        return self.logger.level
+
+    def removeHandler(self, handler: logging.Handler) -> None:  # pylint: disable=invalid-name
+        """Match logging.Logger.removeHandler on the underlying logger."""
+        self.logger.removeHandler(handler)
+
+    def iinfo(self, message, *args, **kwargs):
+        """Log at INTERNAL_INFO level (7) --- framework lifecycle events, below DEBUG."""
+        self.log(INTERNAL_INFO, message, *args, **kwargs)
+
+    def idebug(self, message, *args, **kwargs):
+        """
+        Log at INTERNAL_DEBUG level (5) --- fine-grained framework tracing, below INTERNAL_INFO.
+        """
+        self.log(INTERNAL_DEBUG, message, *args, **kwargs)
+
+    def setLevel(self, level) -> None:
+        """Set level on the logger and all attached handlers simultaneously."""
+        self.logger.setLevel(level)
+        for handler in self.handlers:
+            handler.setLevel(level)
+
+
+_ADAPTERS: dict[str, GrpcLogger] = {}
+
+
+def get_logger(
+    name: str = "default",
+    *,
+    console_log_level: int | None = logging.INFO,
+    log_dir: str = None,
+    file_log_level: int | None = INTERNAL_DEBUG,
+    use_colored_output: bool = True
+) -> GrpcLogger:
+    """
+    Get or create a configured logger instance.
+
+    Parameters
+    ----------
+    name : str
+        Logger name (default: "default")
+    console_log_level : int | None
+        Console handler level. Set to None to disable console logging.
+    log_dir : str
+        Directory for log files. If None, uses system temp dir.
+    file_log_level : int | None
+        File handler level. Set to None to disable file logging.
+    use_colored_output : bool
+        Whether to use colored console output (default: True)
+
+    Returns
+    -------
+    GrpcLogger
+        Adapter around a configured standard logger. Importing this module does
+        not register a global logger class or custom level names; level names
+        are registered only when this factory is explicitly called.
+    """
+    logger = logging.getLogger(name)
+    adapter = _ADAPTERS.setdefault(name, GrpcLogger(logger))
+    logging.addLevelName(INTERNAL_DEBUG, "INTERNAL_DEBUG")
+    logging.addLevelName(INTERNAL_INFO, "INTERNAL_INFO")
+
+    # Avoid adding handlers multiple times
+    if logger.handlers:
+        warnings.warn(
+            f"Logger '{name}' already configured; returning cached logger "\
+                "and ignoring new settings.",
+            stacklevel=2
+        )
+        return adapter
+
+    # Logger level must be INTERNAL to allow file handler to capture everything
+    # Individual handlers control their own output levels
+    logger.setLevel(INTERNAL_DEBUG)
+    logger.propagate = False
+
+    # Determine log directory
+    if log_dir is None:
+        log_location = Path(tempfile.gettempdir()) / "grpcLogs"
+    else:
+        log_location = Path(log_dir)
+
+    # Create file formatter
+    file_formatter = logging.Formatter(
+        "%(asctime)s.%(msecs)03d - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S"
+    )
+
+    # Console handler with coloredlogs
+    if console_log_level is not None:
+        if use_colored_output:
+            # coloredlogs installs directly on the logger with field-level colors
+            coloredlogs.install(
+                level=console_log_level,
+                logger=logger,
+                fmt="%(asctime)s.%(msecs)03d %(hostname)s %(name)s[%(process)d] "\
+                    "%(levelname)s %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+                level_styles={
+                    "internal_debug": {"color": "blue"},
+                    "internal_info": {"color": "white"},
+                    "debug": {"color": "cyan"},
+                    "info": {"color": "green"},
+                    "warning": {"color": "yellow", "bold": True},
+                    "error": {"color": "red", "bold": True},
+                    "critical": {"color": "red", "bold": True, "background": "white"}
+                },
+                field_styles={
+                    "asctime": {"color": "white", "bold": True},
+                    "hostname": {"color": "magenta"},
+                    "levelname": {"color": "white", "bold": True},
+                    "name": {"color": "cyan"},
+                    "programname": {"color": "cyan"},
+                    "process": {"color": "magenta"}
+                }
+            )
+        else:
+            console_handler = logging.StreamHandler()
+            console_handler.setLevel(console_log_level)
+            console_handler.setFormatter(file_formatter)
+            logger.addHandler(console_handler)
+
+    # File handler with rotation
+    if file_log_level is not None:
+        try:
+            log_location.mkdir(parents=True, exist_ok=True)
+
+            # Generate timestamp for log filename
+            timestamp = datetime.now().strftime("%Y%m%d")
+            log_filename = log_location / f"{name}_{timestamp}.log"
+
+            # Use TimedRotatingFileHandler for automatic daily rotation
+            file_handler = TimedRotatingFileHandler(
+                log_filename,
+                when="midnight",
+                interval=1,
+                backupCount=30,  # Keep 30 days of logs
+                encoding="utf-8"
+            )
+            file_handler.setLevel(file_log_level)
+            file_handler.setFormatter(file_formatter)
+            logger.addHandler(file_handler)
+            logger.info("Logging files to %s", log_location)
+
+        except (PermissionError, OSError) as e:
+            warnings.warn(
+                f"Could not create log directory at {log_location}: {e}. "
+                "File logging disabled.",
+                stacklevel=2
+            )
+
+    return adapter

simpytick/sleep.py

@@ -0,0 +1,38 @@
+"""Sleep-based waiting with optional cooperative cancellation."""
+
+import math
+import threading
+import time
+
+
+def sleep(
+    seconds: float,
+    *,
+    stop_event: threading.Event | None = None,
+    check_interval: float = 0.01,
+) -> bool:
+    """Sleep for seconds; return True if stopped, False if the wait completes.
+
+    seconds must be finite and nonnegative. check_interval must be finite and
+    positive; it limits each sleep chunk when stop_event is supplied. An active
+    sleep cannot be interrupted, and OS scheduling can delay cancellation beyond
+    check_interval. Without stop_event, use a single time.sleep() call.
+
+    Monotonic deadlines account for chunk overhead, but do not guarantee exact
+    wake-up times or compensate for work between separate calls.
+    """
+    if not math.isfinite(seconds) or seconds < 0:
+        raise ValueError("seconds must be finite and nonnegative")
+    if not math.isfinite(check_interval) or check_interval <= 0:
+        raise ValueError("check_interval must be finite and positive")
+    if stop_event is None:
+        time.sleep(seconds)
+        return False
+
+    deadline = time.monotonic() + seconds
+    while not stop_event.is_set():
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            return False
+        time.sleep(min(remaining, check_interval))
+    return True

simpytick/sleep_2.py

@@ -0,0 +1,76 @@
+"""Automatically drift-compensated sleeping without background workers.
+
+Exported as simpytick.sleep_2, CompensatedSleep always enables compensation;
+there is no compensation switch. Create one instance before a loop and reuse
+it on every iteration. Creating an instance inside the loop discards its
+schedule and prevents compensation across iterations. For independent,
+uncompensated waits, use simpytick.sleep() instead.
+"""
+
+import math
+import threading
+import time
+
+from simpytick.sleep import sleep
+
+
+class CompensatedSleep:
+    """Callable sleeper with automatic, always-active drift compensation.
+
+    Reuse the same instance across calls: create it once outside the loop.
+    Recreating it each iteration loses the state required for compensation.
+    There is no flag to enable compensation; it is always active. Use one
+    instance per loop and do not share an instance across threads.
+
+    The schedule starts on the first call. Each call advances the deadline by
+    seconds, accounting for work and oversleep since previous calls. Missed
+    deadlines produce zero waits until caught up; exact timing is not guaranteed.
+    reset() or cancellation clears the schedule; the next call starts a new one.
+
+    Example::
+
+        from simpytick import sleep_2
+
+        sleep = sleep_2()
+        for _ in range(100):
+            sleep(0.01)
+    """
+
+    def __init__(self):
+        self._deadline: float | None = None
+
+    def reset(self) -> None:
+        """Discard the schedule so the next call starts a new one."""
+        self._deadline = None
+
+    def __call__(
+        self,
+        seconds: float,
+        *,
+        stop_event: threading.Event | None = None,
+        check_interval: float = 0.01,
+    ) -> bool:
+        """Wait for the next deadline; return True on cancellation, else False.
+
+        seconds must be finite and nonnegative; check_interval must be finite
+        and positive. Cancellation resets the schedule. Invalid arguments leave
+        it unchanged. Stop checks have the same latency limits as simpytick.sleep.
+        """
+        if not math.isfinite(seconds) or seconds < 0:
+            raise ValueError("seconds must be finite and nonnegative")
+        if not math.isfinite(check_interval) or check_interval <= 0:
+            raise ValueError("check_interval must be finite and positive")
+        if stop_event is not None and stop_event.is_set():
+            self.reset()
+            return True
+
+        now = time.monotonic()
+        self._deadline = (now if self._deadline is None else self._deadline) + seconds
+        interrupted = sleep(
+            max(self._deadline - now, 0.0),
+            stop_event=stop_event,
+            check_interval=check_interval,
+        )
+        if interrupted:
+            self.reset()
+        return interrupted

simpytick/timer.py

@@ -0,0 +1,317 @@
+"""
+High-precision periodic timer backed by a ``multiprocessing.Process``.
+
+Public surface:
+- :func:`timer` --- fire an event *n* times at interval *s*.
+- :class:`TimedEvent` --- context manager that iterates once per tick.
+"""
+import itertools
+import logging
+import math
+import multiprocessing
+import threading
+import time
+from multiprocessing import synchronize
+from typing import Literal, Union
+
+from simpytick._worker import run_worker
+from simpytick.logger import get_logger
+from simpytick.sleep import sleep
+
+# Spawn prevents child code from retaining copied parent state. On POSIX its
+# launcher may still briefly fork, so use TimedEvent(backend="thread") after
+# libraries such as gRPC have started threads or opened poller descriptors.
+_SPAWN_CONTEXT = multiprocessing.get_context("spawn")
+
+
+def _validate_timer(n: int, s: float) -> None:
+    """Reject invalid cycle counts and periods before starting any work."""
+    if isinstance(n, bool) or not isinstance(n, int):
+        raise TypeError("n must be an integer")
+    if n < -1:
+        raise ValueError("n must be -1 or nonnegative")
+    if isinstance(s, bool) or not isinstance(s, (int, float)):
+        raise TypeError("s must be a real number")
+    if not math.isfinite(s) or s <= 0:
+        raise ValueError("s must be finite and positive")
+
+
+def _cycles(n: int):
+    """Yield cycle indices; runs indefinitely when n == -1."""
+    if n == -1:
+        yield from itertools.count()
+    else:
+        yield from range(n)
+
+
+def _wait_for_next_tick(duration: float, stop_event: threading.Event = None) -> bool:
+    """Wait for one interval; return whether thread shutdown was requested.
+
+    With a stop event, sleep in chunks of at most 10 ms and check for shutdown
+    between chunks. An active sleep cannot be interrupted; OS scheduling may
+    delay shutdown further. Monotonic deadlines avoid accumulating chunk overhead.
+    This avoids potentially coarse Event.wait() timeouts on Windows and other
+    platforms, but does not guarantee precise wake-up times.
+    """
+    return sleep(duration, stop_event=stop_event)
+
+
+def _tick(period: float, enable_compensation: bool):
+    """Yield monotonic deadline waits, or fixed waits without compensation."""
+    # Inspired by watsonic's generator-based periodic scheduling:
+    # https://stackoverflow.com/questions/8600161/executing-periodic-actions
+    # https://stackoverflow.com/users/watsonic
+    if not enable_compensation:
+        while True:
+            yield period
+
+    next_tick = time.monotonic()
+    while True:
+        next_tick += period
+        yield max(next_tick - time.monotonic(), 0.0)
+
+
+def timer(  # pylint: disable=too-many-arguments
+    n: int,
+    s: float,
+    event: Union[synchronize.Event, threading.Event],
+    enable_compensation: bool = True,
+    logger_level: int = None,
+    *,
+    stop_event: threading.Event = None,
+):
+    """
+    Timer function that sets an event periodically.
+
+    Args:
+        n: Nonnegative number of cycles, or -1 to run indefinitely.
+        s: Finite, positive timing interval in seconds.
+        event: multiprocessing.synchronize.Event or threading.Event which will be set periodically
+            based on the timing interval. The event is expected to be cleared by the caller
+            after each tick.
+        enable_compensation: Maintain accumulated monotonic deadlines to correct drift.
+            Late cycles shorten the next wait, down to zero while catching up.
+            When disabled, each tick is followed by a fixed interval wait.
+        stop_event: Optional thread-backend event used to request an early stop.
+
+    The first tick fires immediately. Prints warning if event is still set
+    from the previous cycle (timer overrun). Zero cycles returns without ticks.
+    """
+    _validate_timer(n, s)
+    if logger_level is not None:
+        process_logger = get_logger("timer", console_log_level=logger_level, file_log_level=None)
+    else:
+        process_logger = None
+
+    ticks = _tick(s, enable_compensation)
+    for i in _cycles(n):
+        if stop_event is not None and stop_event.is_set():
+            break
+
+        event.set()
+
+        sleep_duration = next(ticks)
+        if _wait_for_next_tick(sleep_duration, stop_event):
+            break
+
+        if event.is_set():
+            # not optimal but using log callback here would require passing a logger to the
+            # timer function and we want to avoid that for now
+            if process_logger:
+                process_logger.warning(
+                    "Warning: Timer overrun at cycle %d. Event is still set.", i + 1
+                )
+
+class TimedEvent:  # pylint: disable=too-many-instance-attributes
+    """
+    Context manager that drives periodic task execution using the existing
+    timer function.
+
+    Usage::
+
+        with TimedEvent(s=0.01, n=100) as te:
+            for tick in te:
+                # executed exactly n times, once per timer tick
+
+    Parameters
+    ----------
+    s : float
+        Period time in seconds between ticks.
+    n : int
+        Number of ticks (cycles) to run.
+    backend : {"process", "thread"}
+        ``"process"`` preserves process-isolated timing. ``"thread"`` avoids
+        creating a child after libraries such as gRPC have started threads.
+
+    Notes
+    -----
+    The timer runs in either a spawn-isolated daemon process or a daemon thread.
+    Workers retain normal OS priority. Exiting the context stops and joins the
+    worker. Iteration raises RuntimeError if a background worker fails.
+    """
+
+    def __init__(
+        self,
+        s: float,
+        n: int,
+        compensation: bool = True,
+        logger: logging.Logger | logging.LoggerAdapter | None = None,
+        backend: Literal["process", "thread"] = "process",
+    ):
+        _validate_timer(n, s)
+        if backend not in ("process", "thread"):
+            raise ValueError(f"Unsupported timer backend: {backend}")
+        self.s = s
+        self.n = n
+        self.compensation = compensation
+        self._event = (
+            threading.Event() if backend == "thread" else _SPAWN_CONTEXT.Event()
+        )
+        self._stop_event = threading.Event()
+        self._worker: multiprocessing.Process | threading.Thread | None = None
+        self._status_reader = None
+        self._status_writer = None
+        self._worker_result = None
+        self._backend = backend
+        self.overrun_count: int = 0  # number of cycles where task exceeded the tick period
+        self.logger = logger
+
+    def __enter__(self) -> "TimedEvent":
+        """Start a normal-priority worker, cleaning up if startup fails."""
+        timer_args = (
+            self.n,
+            self.s,
+            self._event,
+        )
+        timer_kwargs = {
+            "enable_compensation": self.compensation,
+            "logger_level": self.logger.getEffectiveLevel() if self.logger else None,
+            "stop_event": self._stop_event if self._backend == "thread" else None,
+        }
+        self._status_reader, self._status_writer = _SPAWN_CONTEXT.Pipe(duplex=False)
+        try:
+            worker_type = (
+                threading.Thread if self._backend == "thread" else _SPAWN_CONTEXT.Process
+            )
+            self._worker = worker_type(
+                target=run_worker,
+                args=(timer, timer_args, timer_kwargs, self._status_writer),
+                daemon=True,
+            )
+            self._worker.start()
+            if self._backend == "process":
+                self._status_writer.close()
+        except BaseException as error:
+            try:
+                started = self._worker is not None and (
+                    self._worker.ident is not None if self._backend == "thread"
+                    else self._worker.pid is not None
+                )
+                if started:
+                    self.__exit__(type(error), error, error.__traceback__)
+            finally:
+                self._close_status()
+            raise
+        return self
+
+    def _close_status(self) -> None:
+        for connection in (self._status_reader, self._status_writer):
+            if connection is not None:
+                connection.close()
+        self._status_reader = self._status_writer = None
+
+    def _check_worker_error(self) -> None:
+        if self._worker_result is None and self._status_reader is not None:
+            try:
+                if self._status_reader.poll():
+                    self._worker_result = self._status_reader.recv()
+            except (EOFError, BrokenPipeError):
+                pass
+        if self._worker_result is not None and self._worker_result[0] == "error":
+            raise RuntimeError(f"Timer worker failed: {self._worker_result[1]}")
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        """Stop and join the worker and close its status connections."""
+        try:
+            if self._worker is not None:
+                if self._backend == "process":
+                    if self._worker.is_alive():
+                        self._worker.terminate()
+                else:
+                    self._stop_event.set()
+                self._worker.join()
+                if exc_type is None:
+                    self._check_worker_error()
+        finally:
+            self._close_status()
+        return False  # do not suppress exceptions
+
+    def __iter__(self):
+        """
+        Yield the cycle index (0-based) once per timer tick.
+
+        Each iteration waits for the timer to set the event, then clears it
+        before yielding, so the task code runs synchronously between ticks.
+
+        After each yield (i.e. after the task body has finished), the event
+        is checked again.  If it is already set the timer has fired the next
+        tick while the task was still running --- a timer overrun.  A warning
+        is printed and ``self.overrun_count`` is incremented.
+
+        Deadlock prevention
+        -------------------
+        ``threading.Event.set()`` is idempotent: if the task overruns by more
+        than one tick, several timer fires collapse into a single set signal.
+        ``__iter__`` would then wait forever on a tick that the (now-finished)
+        timer thread will never fire.  To guard against this, every wait uses a
+        timeout capped at 100 ms. Normal completion with collapsed ticks stops
+        iteration early; worker failures raise RuntimeError, even without a logger.
+        """
+        try:
+            i = 0
+            while self.n == -1 or i < self.n:
+                self._check_worker_error()
+                while not self._event.wait(timeout=min(self.s, 0.1)):
+                    self._check_worker_error()
+                    if not self._worker.is_alive():
+                        self._worker.join()
+                        self._check_worker_error()
+                        if self._worker_result != ("done", None):
+                            exitcode = getattr(self._worker, "exitcode", None)
+                            raise RuntimeError(
+                                f"Timer worker exited without completion (exitcode={exitcode})"
+                            )
+                        if self._event.is_set():
+                            break
+                        if self.logger:
+                            self.logger.warning(
+                                "Timer process ended after %d ticks; %d tick(s) missed.",
+                                i,
+                                self.n - i,
+                            )
+                        return
+                    self._check_worker_error()
+                self._event.clear()
+                yield i
+                i += 1
+                # Stop after n ticks (mirrors the timer process cycle count).
+                # Checked here --- after the task body returns --- so the last
+                # yield is never skipped even if the process has already exited.
+                if self.n != -1 and i >= self.n:
+                    return
+        except KeyboardInterrupt:
+            if self.logger:
+                self.logger.info("strg+c")
+            raise  # re-raise so the caller's signal handling is not suppressed
+        # cleanup is handled solely by __exit__ (terminate + join)
+
+
+if __name__ == "__main__":
+
+    demo_logger = get_logger("timer_demo")
+    demo_logger.info("Starting timer demo with compensation enabled...")
+
+    with TimedEvent(s=0.01, n=10, compensation=True, logger=demo_logger) as te:
+        for tick in te:
+            demo_logger.info("Tick %d at %s", tick, time.time())
+            time.sleep(2.1)

simpytick-0.0.1.dist-info/METADATA

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: SimPyTick
+Version: 0.0.1
+Summary: SimPyTick (Simple Python Tick): process- and thread-backed periodic timers.
+Author-Email: Fabian Krumm <ghub_fk@gmx.de>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Requires-Dist: coloredlogs>=15.0
+Requires-Dist: psutil>=5.0.0
+Description-Content-Type: text/markdown
+
+# SimPyTick
+
+Simple Python Tick: periodic events using a spawn-isolated process or a thread.
+Requires Python 3.10 or later. Runtime dependencies: `psutil` and `coloredlogs`.
+
+## Release Status
+
+Releases before `1.0.0` are testing versions and may introduce breaking changes
+without a major version increment. Semantic versioning will begin with `1.0.0`.
+
+## Installation
+
+```shell
+pip install SimPyTick
+```
+
+From a checkout of this package:
+
+```shell
+uv pip install .
+```
+
+## Usage
+
+```python
+from simpytick.timer import TimedEvent
+
+
+def main():
+	with TimedEvent(s=0.01, n=100, backend="thread") as ticks:
+		for tick in ticks:
+			print(tick)
+
+
+if __name__ == "__main__":
+	main()
+```
+
+`TimedEvent(s, n, compensation=True, logger=None, backend="process")` uses a
+finite, positive period `s` and an integer count `n`. Booleans are not accepted
+as periods or counts. `n=-1` runs indefinitely; `n=0` yields no ticks. Invalid
+arguments raise `TypeError` or `ValueError` before any worker is created. Exiting the
+context terminates and joins the process, or signals and joins the thread.
+The first tick is emitted immediately; subsequent ticks use the given interval.
+
+The default process backend uses multiprocessing's `spawn` context. Keep process
+creation behind `if __name__ == "__main__":` in an importable script. Both backends
+retain normal OS priority; the package does not request real-time scheduling or
+require priority-changing privileges. Failed startup cleans up any started worker
+and its status connections. Use `backend="thread"` to
+avoid child creation after libraries such as gRPC start threads or open pollers.
+
+Background failures raise `RuntimeError` during iteration or normal context exit,
+even without a logger. Reported exceptions include their type and a bounded message;
+abrupt exits without completion are also errors. Health-check waits are capped at
+100 ms, subject to OS scheduling. Application exceptions remain primary during
+cleanup. Normal completion with collapsed event signals still ends iteration early.
+
+The low-level API keeps its positional arguments and validates `n` and `s` using
+the same rules:
+
+```python
+import threading
+from simpytick.timer import timer
+
+event = threading.Event()
+timer(3, 0.01, event, False, None)
+```
+
+`timer(n, s, event, enable_compensation=True, logger_level=None, *,
+stop_event=None)` sets the supplied event. Consumers clear it after each tick;
+multiple unconsumed signals can collapse into one. This low-level call blocks
+until completion. The first tick fires immediately. With compensation enabled,
+a persistent monotonic schedule corrects accumulated drift by shortening waits,
+including zero waits to catch up after missed deadlines. With compensation
+disabled, each tick is followed by a fixed interval wait. This is not a hard
+real-time scheduler, and slow consumers may miss ticks. Compensation no longer
+restricts the number of decimal places in the period; this does not guarantee
+that the operating system can achieve very short intervals.
+
+## Sleep
+
+```python
+import threading
+import simpytick
+
+simpytick.sleep(0.01)
+
+stop = threading.Event()
+interrupted = simpytick.sleep(1.0, stop_event=stop, check_interval=0.01)
+```
+
+`simpytick.sleep(seconds, *, stop_event=None, check_interval=0.01)` returns
+`True` if cancelled and `False` when the wait completes. Another thread can
+request cancellation with `stop.set()`. Without a stop event it uses a single
+`time.sleep()` call; otherwise it sleeps in chunks, checking the stop flag
+between them. `seconds` must be finite and nonnegative; `check_interval` must
+be finite and positive.
+
+An active sleep cannot be interrupted. Cancellation latency depends on the
+chunk size and OS scheduling, so `check_interval` is not a guaranteed bound.
+Monotonic deadlines account for chunk overhead without busy-waiting. Separate
+calls do not share a schedule or compensate for work between calls; use
+`sleep_2` or `TimedEvent` for periodic drift compensation. Exact wake-up times are not
+guaranteed.
+
+### Compensated Sleep
+
+```python
+import time
+from simpytick import sleep_2
+
+sleep = sleep_2()
+for _ in range(100):
+	sleep(0.01)
+	print(time.time())
+```
+
+Create the callable once outside the loop. It runs in the calling thread, with
+no background thread or process. Its monotonic schedule starts on the first
+call; subsequent calls advance the deadline by the supplied seconds, accounting
+for work and oversleep between calls. Overdue deadlines produce zero waits
+until caught up. Use a separate instance for each loop; instances are not
+thread-safe.
+
+Calls accept the same `stop_event` and `check_interval` keyword arguments and
+return the same cancellation flag as `simpytick.sleep()`. Cancellation resets the
+schedule; `sleep.reset()` also makes the next call start a new schedule. Exact
+wake-up times and immediate cancellation are not guaranteed.
+
+## Migration Scope
+
+The timer module originated in pookiepy. Its digit-based compensation has been
+replaced by persistent monotonic deadlines. The obsolete digit-compensation
+helpers and constants have been removed. `GrpcLogger` is now a
+`logging.LoggerAdapter`, not a `logging.Logger` subclass. `get_logger()` wraps
+standard named loggers, including those created before the package was imported.
+Its custom methods (`iinfo()` and `idebug()`), handler access, level access, and
+adapter caching remain available. Imports do not change the global logger class
+or register level names; explicit `get_logger()` calls register custom levels and
+configure output. The package installs a `NullHandler` for application-controlled
+logging. The factory still defaults to file output under `grpcLogs` in the system
+temporary directory. No dependency on pookiepy, gRPC, or protobuf remains.
+
+The timer worker and lifecycle tests and logger tests are copied with namespace
+adjustments. Timer API tests are retained; the gRPC broadcast integration test
+is excluded because it exercises the original framework, not the timer package.
+Spawn-worker tests exercise the actual process without mocking priority setup.
+Regression tests cover validation, startup cleanup, worker failures, logger import
+isolation, and matching runtime/distribution versions.
+
+Distribution name: `SimPyTick`. Import namespace: `simpytick`. Initial
+standalone version: `0.0.1`. Original BSD-3-Clause license and attribution remain.
+
+## Development
+
+Run commands from this directory:
+
+```shell
+uv pip install -r requirements.txt
+uv run --with-requirements requirements.txt python -m unittest discover -s tests -p "test_*.py"
+uv run --with-requirements requirements-dev.txt python -m pylint --jobs=1 simpytick tests
+uv build
+uvx twine check dist/*
+```
+
+`requirements-dev.txt` includes `-r requirements.txt` and adds development-only
+`pylint==4.0.10` and `coverage>=7.10,<8`; these tools are not published as runtime
+dependencies. CI reports coverage without a minimum. Pylint keeps its default
+fail-under of 10, with no disabled messages or explicit custom threshold.
+
+`requirements.txt` contains runtime-only dependencies and mirrors
+`pyproject.toml` project dependencies. The workflows use it before tests, build,
+and publication preflight; the requirements guard test detects drift, so update
+both files together. PDM's declared build backend supplies `uv build` build
+dependencies, while the generated wheel and source-distribution metadata causes
+pip installs to resolve runtime dependencies automatically. The requirements
+file is included in source distributions. `MANIFEST.in` is unnecessary; source
+distributions also include tests and workflows. No protobuf generation or
+parent-project build hook is used.
+
+## CI and Publication
+
+The workflows assume this directory is the root of its own GitHub repository.
+While nested in the original repository, GitHub does not discover these workflows.
+
+- `test.yml`: mandatory Python 3.10-3.14 tests on `ubuntu-latest`,
+	`windows-latest`, `macos-latest`, `ubuntu-22.04-arm`, and `ubuntu-24.04-arm`,
+	plus nonblocking `3.x` probes on the same five runners; coverage run/report
+	has no minimum.
+- `pylint.yml`: Python 3.14 / Ubuntu, Pylint 3.2.6, `--jobs=1 simpytick tests`.
+- `build.yml`: additional Ubuntu / Python 3.14 preflight, wheel/sdist build,
+	Twine checks, isolated installed-artifact smoke tests, and artifact upload.
+- `weekly-latest-python.yml`: Monday at 12:00 UTC and manual runs; nonblocking
+	`3.x` unit probes on the same five runners and Ubuntu lint with latest Pylint.
+- `verify-workflows.yml`: reference-equivalent actionlint syntax/expression
+	checks and zizmor security audit.
+- `pypi_publish.yml`: pushes to `master`, not GitHub Release publication. A read-only
+	build job runs preflight tests, build, Twine and wheel/sdist smoke checks, then
+	uploads validated artifacts. Its dependent `pypi-release` environment job
+	publishes them using OIDC with `skip-existing: true`, `print-hash: false`, and
+	`attestations: true`, without stored API tokens.
+
+After publication succeeds, an annotated `v<version>` tag is created from
+`simpytick/_version.py`. An existing tag on the same commit is an idempotent
+no-op; a tag on a different commit is never moved and causes failure. Set the
+version constant manually before a new release. No automatic version bump or
+semantic-version inference from commits or tags occurs; tags are output, not
+the version source. PDM reads the same file for distribution metadata, and
+`simpytick.__version__` imports it at runtime.
+
+Before publishing, configure the PyPI project `SimPyTick` with a trusted
+publisher matching your GitHub owner/repository, workflow `pypi_publish.yml`, and
+environment `pypi-release`. Keep the workflow filename to preserve that identity
+and retain the environment URL `https://pypi.org/project/SimPyTick/`. Confirm PyPI
+name availability and select an unpublished version before pushing. Skipping
+existing files supports retries, not replacement of published artifacts.
+
+There is no full-matrix mandatory CI `needs` barrier before publishing, matching
+the reference. Require supported-version tests, lint, build and workflow audit
+checks through `master` branch protection; configure environment reviewers and
+allowed branches. Do not require floating `3.x` probes as support guarantees.
+See [.github/CI.md](.github/CI.md) for CI ownership, reference differences,
+and justified deviations.
+
+# Todos
+
+## AI Findings
+
+Remaining Medium/Low findings from the pre-publication review. High-severity
+findings were addressed separately; these items remain open.
+
+- [ ] **Medium - Tick delivery and overrun accounting (review #7):** Define whether
+	delivery coalesces, skips, or guarantees ticks. Reconcile the exactly-`n` example
+	with missed signals, implement accurate `overrun_count` and sequence accounting,
+	and test consumers that span several periods. Avoid an unbounded queue.
+- [ ] **Medium - Context lifecycle (review #8):** Reject repeated/nested entry or
+	implement a fully reset lifecycle. Define iteration outside an active context;
+	test re-entry, nested entry, and reuse after thread shutdown.
+- [ ] **Medium - Scheduling scalability (review #9):** Define catch-up/skip policy
+	and bound catch-up bursts. Benchmark CPU use, jitter, startup, and shutdown over
+	increasing timer counts; assess chunked cancellation wakeups and worker-per-timer
+	overhead before making high-precision or scalability claims.
+- [ ] **Medium - Log-file path safety (review #10):** Separate logger identity from
+	filenames, validate filenames, and use an application-owned directory. Make file
+	output opt-in and address path traversal and shared-temporary-directory symlinks.
+- [ ] **Medium - Log retention and writers (review #11):** Use a stable log basename
+	so retention works across daily restarts. Give rotation a single owner for
+	multiprocess use, such as a `QueueListener`; test retention and concurrent writers.
+- [ ] **Medium - Release gates (review #12):** Make publication depend on the full
+	supported OS/Python test matrix and validated distributions for the release
+	commit. Check the release tag against the distribution version.
+- [ ] **Medium - Dependency and supply-chain validation (review #13):** Commit a
+	development lockfile, lock release tooling, test minimum and current runtime
+	dependencies, add scheduled advisory audits, and pin the publishing action to a
+	verified commit SHA. Reassess the now-unused `psutil` dependency after removing
+	automatic priority changes.
+- [ ] **Low - Packaged development output (review #14):** Exclude or remove
+	`simpytick/results.txt` from distributions. Keep reproducible benchmark methods and
+	meaningful results outside the import package, and inspect wheel/sdist contents.

simpytick-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+simpytick-0.0.1.dist-info/METADATA,sha256=E0GpIeW5rPURg2XvWRJggBJXbZcIspqXyqFSVUyEiGs,13127
+simpytick-0.0.1.dist-info/WHEEL,sha256=IuIk3wbaEnFH1cx75iM2R1CmliRI3dFLXTbRakgvgFQ,90
+simpytick-0.0.1.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+simpytick-0.0.1.dist-info/licenses/LICENSE,sha256=D5tHuFx3CsUmFQTursu3R7LmOAgCWqlytpquqGKWXdY,1499
+simpytick/__init__.py,sha256=uWp0sRDjYNuUwRvBbwhKRXsRxEQYJnhpfe963qud-oc,285
+simpytick/_version.py,sha256=UACWIKnT7L1-Lop1Ja1H0POQVFnhy-lJA8WEvPXZHvg,98
+simpytick/_worker.py,sha256=Uyc88DWA6PIHXquSkempEhg5LTq0XMy_B1f11aA77FY,469
+simpytick/logger.py,sha256=iRsr_fnifsRNXoTsQbxmpQ98WxxiupZer9btwhk3Jo8,6568
+simpytick/sleep.py,sha256=zeOPdx68_aHuDtLTOGEbDvYlDKOLXZgb5MOMxqulunE,1358
+simpytick/sleep_2.py,sha256=hQKoArVqqm28NEYAZbkZOBQHH1jzyxfCuD_Edib0_jM,2795
+simpytick/timer.py,sha256=JDJzR6apu8yVaJ6d5MceTTetZQJ7GeLuZ12K2Q-ZBck,12545
+simpytick-0.0.1.dist-info/RECORD,,

simpytick-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.5.0)
+Root-Is-Purelib: true
+Tag: py3-none-any

simpytick-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+
+[gui_scripts]
+

simpytick-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Fabian Krumm
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.