EU hours-of-service engine (Regulation (EC) 561/2006 and Directive 2002/15/EC). Pure Python, no dependencies. Give it a driver's activity timeline and it tells you how the time divides into shifts, which rules were broken, by how much, under which article and in which category of seriousness, and how much driving is left.
Status: 0.1.0, pre-release. Shift segmentation, breaks (Article 7), daily, weekly and fortnightly driving (Article 6) and working time under Directive 2002/15/EC, with violations classified by Regulation (EU) 2016/403, a JSON report and a CLI. Daily and weekly rest are evaluated by a rest provider behind an open contract. Counters say how much driving is left, and the planner says when a driver arrives.
A planning and analysis tool. It is not a legal record and not legal advice: the tachograph and the enforcement authority are the final word. It encodes one documented interpretation of the rules (docs/ASSUMPTIONS.md) and does not parse tachograph files: it takes the JSON that existing parsers produce.
from driver_hours import segment
from driver_hours.testing import build
timeline = (
build("2026-09-01", tz="Europe/Warsaw")
.drive("05:00", "09:30")
.brk("09:30", "10:15")
.drive("10:15", "15:00")
.work("15:00", "16:00")
.rest("16:00", "05:00")
.next_day()
.drive("05:00", "09:00")
.work("09:00", "09:10")
.done()
)
for shift in segment(timeline).shifts:
print(shift.date, shift.closed_by, shift.driving_min, shift.active_min)The boundary is strict about the mistakes that silently move hours: naive datetimes and pytz time zones are
refused, 23:59:59.999999 means midnight, overlapping records are resolved deterministically and counted. Inside,
everything is whole UTC seconds.
How activity becomes shifts is specified in docs/SPEC_SEGMENTATION.md: a 9-hour rest closes a shift, a shift without one is cut at 24 hours (30 with two drivers), and a run of less than 15 minutes ("moving the truck at 23:00") never glues two working days together. Each rule states the failure it prevents, and the invariants are checked with generated timelines.
driver-hours scenario continuous_driving_5h30 > timeline.json
driver-hours check timeline.json | jq '.violations[0] | {type, actual_min, severity, severity_row}'
driver-hours check timeline.json --night-window 00:00-04:00 # national night time for Directive Art. 7{"type": "continuous_driving_exceeded", "actual_min": 330, "severity": "serious", "severity_row": "2016/403 Annex I part 1 row 14"}Every violation names its provision, the norm and the measured value. It says whether it can still grow (open,
when the data ends first). It gives its category in the EU classification of serious infringements and cites the
row (docs/LEGAL_BASIS.md); the rows are transcribed from the consolidated text and kept as
data. Penalty amounts are national and not part of the engine.
from datetime import datetime
from zoneinfo import ZoneInfo
from driver_hours.counters import counters_at
from driver_hours.planner import Leg, feasibility
from driver_hours.testing import build
from driver_hours.timeline import to_epoch
timeline = (
build("2026-09-01", tz="Europe/Warsaw").drive("05:00", "09:30").brk("09:30", "10:15").drive("10:15", "12:00").done()
)
counters = counters_at(timeline)
print(counters.driving_left_s // 60) # 165: daily driving runs out before the next break is due
legs = [Leg(drive_s=2 * 3600, service_s=3600, label="Berlin"), Leg(drive_s=90 * 60, label="Leipzig")]
verdict = feasibility(counters, legs, to_epoch(datetime(2026, 9, 1, 18, 0, tzinfo=ZoneInfo("Europe/Warsaw"))))
print(verdict.feasible, verdict.slack_s // 60) # True 45
print([(rest.kind.value, rest.reason) for rest in verdict.plan.rests])
# [('break', '4 h 30 min of driving since the last break')], with one 10-hour extensionThe planner inserts breaks, extensions, daily and weekly rests at the latest moment the rules allow, and uses an
extension only when the extra hour finishes the trip: an extension that just postpones the daily rest costs a break
and gains nothing. eta_conservative is the same trip with no extensions (here: 03:30 the next morning). Rest
deadlines come from the rest provider; without one the plan is conservative and says what it assumed
(docs/COUNTERS_AND_PLANNING.md).
driver-hours counters timeline.json --at 2026-09-01T12:00:00+02:00
driver-hours plan timeline.json --legs legs.json --deadline 2026-09-01T18:00:00+02:00| Rule | Status |
|---|---|
| Art. 7 break after 4 h 30 min, split 15 + 30, break in the moving vehicle with multi-manning | ✅ |
| Art. 6(1) daily driving, two extensions a week | ✅ |
| Art. 6(2) weekly and 6(3) fortnightly driving, divided at Monday 00:00 | ✅ |
| Art. 8 daily and weekly rest, compensation, six-day limit, rest in the vehicle | through a rest provider (docs/REST_ANALYSIS.md) |
| Directive 2002/15/EC Art. 4(a) 60 hours a week and the 48-hour average, Art. 5(1) breaks, Art. 7(1) night work (with a national night window) | ✅ |
| Art. 9 ferry and train interruptions of a rest | in segmentation; the rest's validity through the rest provider |
| Data quality: overlaps, long gaps, a mode selector left on work, activity outside shifts | reported as issues |
| Art. 12 exceptions, Art. 3 scope exemptions, national derogations, penalty amounts | not modelled |
| Milestone | Scope |
|---|---|
| E1 (done) | Timeline normalisation, shift segmentation, the timeline DSL, property tests, segmentation spec |
| E2 (done) | Breaks (Article 7), daily, weekly and fortnightly driving (Article 6), violations with EU seriousness categories (2016/403), JSON report, CLI |
| E3 (done) | Daily and weekly rests (Article 8) through the open rest-analysis contract and a client for Intelit's provider; seriousness rows 16 to 31 |
| E4 (done) | Counters ("how much driving is left") and a feasibility planner ("can this driver legally make 14:00?") |
| E5 (done) | Working time (Directive 2002/15/EC) with 2016/403 part 3, ferry and train interruptions (Article 9), data quality issues, release preparation |
| Next | Adapters for tachograph parser output, national plug-ins (penalty tables as plug-ins, never core) |
EU rules only. National penalty tables are plug-ins, never part of the core; FMCSA (US) rules are not planned.
Apache-2.0. All timelines in this repository are synthetic.