Skip to content

Support dateutil.relativedelta on the ordinal date representation #431

Description

@pschanely

Summary

Add CrossHair support for dateutil.relativedelta, so programs doing calendar-field
date math (+ relativedelta(months=1), + relativedelta(years=1), weekday
targeting) can be analyzed and have counterexamples found.

Dependencies

  • Blocked by the lazy/optional-module registration issue â�� dateutil is a
    third-party, optional dependency, so we need import-triggered registration before
    a dateutillib.py can exist cleanly.
  • Builds on Represent symbolic dates by ordinal, decomposing calendar fields lazily #428 (symbolic dates backed by ordinal): the absolute (days/weeks)
    portion of relativedelta rides on the now-linear ordinal arithmetic.

Motivation

timedelta is pure day/second offsets and is now linear on the ordinal (#428).
relativedelta is different: it does calendar-field arithmetic � add N months or
years, with day-clamping (Jan 31 + relativedelta(months=1) � Feb 28/29), and
relative weekday targeting. This is intrinsically calendar-nonlinear (month lengths,
leap years, boundary wrap) and unsupported today (no dateutil patching exists).

Proposal

  • New crosshair/libimpl/dateutillib.py registered lazily on import dateutilâ�¦.
  • Patch relativedelta construction and its __add__/__radd__/__sub__ against
    date/datetime.
  • Split the arithmetic: the absolute part (days, weeks, plus normalized
    hours/minutes/seconds/microseconds) reuses ordinal/total-micros arithmetic from
    Represent symbolic dates by ordinal, decomposing calendar fields lazily #428; the relative part (years, months, day-clamping, weekday) is the
    nonlinear core to model carefully � decide per field what stays symbolic vs.
    realizes.

Where this lives

  • New crosshair/libimpl/dateutillib.py (+ a _ch_test.py mirroring
    datetimelib_ch_test.py round-trips against real dateutil).
  • Hooks into the registration mechanism from the prerequisite issue.

Implementation sketch (phased)

  1. Benchmark first (per Represent symbolic dates by ordinal, decomposing calendar fields lazily #428's lesson): add a crosshair-benchmark case, e.g. a
    falsifiable contract over d + relativedelta(months=1).
  2. Absolute-only relativedelta (days/weeks/H:M:S) on the ordinal base � should
    be ~linear.
  3. Relative months/years + day-clamping � the nonlinear part; measure, and pick a
    realization policy where needed.
  4. Weekday targeting / relativedelta(date1, date2) diff form.

Risks / things to measure

Acceptance criteria

  • date/datetime +/- relativedelta(...) finds counterexamples and matches
    dateutil on a CrossHair-on-CrossHair round-trip suite.
  • Absolute-only relativedelta arithmetic is in the linear regime; relative
    (months/years) is at least tractable with no regression elsewhere.
  • No effect on users without dateutil installed.

References

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions