Chronopype

CI codecov Python 3.13+ PyPI License: MIT

A flexible, type-safe clock implementation for real-time and backtesting scenarios in Python. Chronopype provides a robust framework for managing time-based operations with async/await support, comprehensive performance monitoring, and an extensible processor framework.

Features

  • Flexible Clock System --- Support for both real-time and backtesting modes with a unified API
  • Processor Framework --- Extensible system for implementing time-based operations with retry and timeout support
  • Network-Aware --- Built-in network processor with automatic reconnection and exponential backoff
  • Async Support --- Full async/await support for efficient I/O operations
  • Performance Monitoring --- Built-in execution time tracking, percentile statistics, and lagging processor detection
  • Type Safe --- Fully typed with MyPy strict mode compliance
  • Well Tested --- Comprehensive test suite with high coverage

Quick Example

import asyncio
import time
from chronopype import ClockConfig, ClockMode
from chronopype.clocks import RealtimeClock
from chronopype.processors import TickProcessor


class MyProcessor(TickProcessor):
    async def async_tick(self, timestamp: float) -> None:
        print(f"Tick at {timestamp}")


async def main():
    config = ClockConfig(
        clock_mode=ClockMode.REALTIME,
        start_time=time.time(),
        tick_size=1.0,
    )
    async with RealtimeClock(config) as clock:
        clock.add_processor(MyProcessor())
        await clock.run_til(config.start_time + 10)


asyncio.run(main())

Architecture Overview

Chronopype is organized around two core abstractions:

  • Clocks manage time progression and coordinate processors. Choose RealtimeClock for live systems or BacktestClock for historical simulation.
  • Processors implement the work that happens on each tick. The base TickProcessor handles sync/async execution, while NetworkProcessor adds connectivity management.
ClockRuntime         ── lifecycle management (async + threaded)
└── BaseClock (abstract)
    ├── RealtimeClock    ── real-time with drift correction
    └── BacktestClock    ── deterministic stepping through historical time

TickProcessor (base)
└── NetworkProcessor ── network-aware with auto-reconnection

Next Steps