Project Overview

Project Purpose and Objectives

This project delivers a lightweight, precise timing and scheduling utility designed primarily for developers and testers who need to measure elapsed time and compute next scheduled run times based on cron-like expressions. Its core objectives are:

• Accurate task timing: Provide a simple, easy-to-use timer class (TaskTimer) capable of measuring elapsed time in milliseconds for arbitrary code blocks or tasks.

• Flexible schedule parsing: Offer a minimal cron expression parser and next-run calculator that supports standard five-field schedules (minute, hour, day of month, month, day of week).

• Ease of integration: Maintain a clean, minimal dependency API suitable for embedding in test frameworks or documentation generation environments.

• Reliability with tests: Include basic testing to ensure timer correctness and future extensibility.

Major Functionalities:

• TaskTimer (timer.py): Implements start, stop, reset, and elapsed time retrieval for timing tasks with millisecond precision. The timer handles start/stop idempotency and returns elapsed time even if stopped before starting.

• Schedule parser (schedule.py): Parses a cron-like 5-field string into discrete integer sets for each time unit, then calculates the next datetime matching the schedule after a given reference time.

• Demo script (demo.py): Illustrates the usage of both timing and scheduling features, showing how to start a timer and calculate the next scheduled run time.

Example Workflows and Use Cases

Measuring Elapsed Time of a Code Block

1. Create a TaskTimer instance.

2. Call .start() before the code block.

3. Execute the code to be timed.

4. Call .stop() after execution.

5. Access .elapsed_ms to retrieve elapsed time in milliseconds.

from tasktimer.timer import TaskTimer

timer = TaskTimer()
timer.start()
# ... code to measure ...
timer.stop()
print(f"Elapsed time: {timer.elapsed_ms} ms")

Calculating Next Scheduled Run Time

Given a cron expression such as "0 9 * * 1-5" (9 AM on weekdays), compute the next occurrence after the current moment:

from tasktimer.schedule import next_run

cron_expr = "0 9 * * 1-5"
next_run_time = next_run(cron_expr)
print(f"Next run at: {next_run_time}")

The next_run function parses the expression, expands the fields, and iterates forward up to one year from now to find the next matching datetime.

Stack and Technologies

• Python 3.x — Core programming language chosen for its expressiveness, rich standard library (e.g., time, datetime), and wide adoption in testing environments.

• Standard libraries: time, datetime, dataclasses, and typing provide lightweight, efficient implementations without external dependencies.

• Cron parsing logic: Custom parser tailored for simplicity and reliability, avoiding heavyweight cron libraries.

• Testing: Basic internal testing using plain Python functions to validate core timer behavior.

• Packaging: Lightweight package structure with init.py to facilitate easy imports.

These choices prioritize minimal dependencies, ease of understanding, and portability, making the project suitable as a utility in different Python environments.

High-Level Architecture

The project consists of three main logical components:

• Timer module (timer.py): Implements the TaskTimer class and the now_ts() helper function to measure elapsed time with epoch timestamps.

• Schedule module (schedule.py): Provides parsing and calculation logic for cron-style schedules, returning the next matching datetime.

• Demo and Testing (demo.py, test_timer.py): Demonstration script to showcase usage and a test script verifying timer correctness.

The package initialization (__init__.py) exposes the timer API cleanly.

Interactions

• The frontend to the utility is the public API consisting of TaskTimer and next_run.

• The timer internally interacts with system time via Python’s time module.

• The schedule parser translates cron expressions into internal data structures (CronField) and uses datetime for date arithmetic.

• The demo script acts as a usage example combining timer and schedule components.

• The test module validates timer behavior independently.

graph TB
Demo --> Timer[Timer Module]
Demo --> Schedule[Schedule Module]
Test --> Timer
Timer --> TimeLib[time Module]
Schedule --> DateTimeLib[datetime Module]
__init__ --> Timer

Developer Navigation

• Frontend developers start here:
  Explore demo.py for practical examples of using the timer and schedule APIs. It demonstrates typical usage patterns and can serve as a base for UI or CLI integration.

• Backend developers focus on these commands:

  • timer.py for extending or modifying timing functionality.

  • schedule.py for enhancing parsing rules or scheduling algorithms.

• Test contributors:
  Review and expand test_timer.py to add more test coverage, particularly edge cases for timer states.

• Package maintainers:
  Manage imports and exports in init.py and keep dependency files (requirements.txt, pyproject.toml) up to date.

Visual Diagrams

Component Diagram: High-Level Architecture

graph TB
Demo --> Timer
Demo --> Schedule
Test --> Timer
Timer --> Time
Schedule --> DateTime
__init__ --> Timer

Flowchart: Timer Usage Workflow

flowchart TD
Start["Create TaskTimer instance"]
Start --> S1["Call start()"]
S1 --> Work["Execute code to time"]
Work --> S2["Call stop()"]
S2 --> Result["Retrieve elapsed_ms"]
Result --> End["Use elapsed time"]

Flowchart: Schedule Next Run Calculation

flowchart TD
Input["Input cron expression"]
Input --> Parse["Parse expression into fields"]
Parse --> Expand["Expand fields to integer lists"]
Expand --> Search["Iterate dates from 'now'"]
Search --> Match{"Date matches schedule?"}
Match -- Yes --> Output["Return next run datetime"]
Match -- No --> Search
Search -->|1 year limit exceeded| Error["Raise error: no match found"]