Skip to content

About

Pure-Python EU 561/2006 and 2002/15/EC driver working-time engine: shifts, breaks, violations, feasibility. Zero deps.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

driver-hours

ci License: Apache-2.0

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.

What it is, and what it is not

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.

Timelines and shifts

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.

Checking a timeline

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.

How much is left, and can the driver make it?

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 extension

The 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 coverage

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

Roadmap

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.

License

Apache-2.0. All timelines in this repository are synthetic.

About

Pure-Python EU 561/2006 and 2002/15/EC driver working-time engine: shifts, breaks, violations, feasibility. Zero deps.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages