Skip to content
Sarj Standards

Python · correctness

prefer-timedelta-for-durations

python:prefer-timedelta-for-durations

Duration-bearing name is typed as a raw integer or float.

Code
SARJ014
Default
error
Fix
none
Languages
python

Why

A `timedelta` makes the unit explicit and prevents incompatible duration values from mixing silently.

Fix

Use `datetime.timedelta` at the typed boundary and convert only at external interfaces.

Before / after

Executed by this rule’s unit tests.

Before

Seconds represented as an integer

scheduler.py · focus
def schedule(timeout_seconds: int) -> None: ...

After

Duration represented as timedelta

scheduler.py · focus
from datetime import timedelta

def schedule(timeout: timedelta) -> None: ...

Limits

  • Detection relies on duration-shaped names and numeric type annotations.
  • Tests, generated files, CLI parameters, settings fields, counts, rates, calendar units, and timestamps are excluded.