[Python-Dev] Issue5434: datetime.monthdelta

[Jess Austin]

Thanks for everyone's comments!

On Thu, Apr 16, 2009 at 9:54 AM, Paul Moore <p.f.moore at gmail.com> wrote:
> I like the idea in principle. In practice, of course, month
> calculations are inherently ill-defined, so you need to be very
> specific in documenting all of the edge cases, and you should have
> strong use cases to ensure that the behaviour implemented matches user
> requirements. (I haven't yet had time to read the patch - you may well
> already have these points covered, certainly your comments above
> indicate that you appreciate the subtleties involved).
>
> I agree that ultimately it would be useful in the core. However, I'd
> suggest that you release the functionality as an independent module in
> the first instance, to establish it outside of the core. Once it has
> matured somewhat as a 3rd party module, it would then be ready for
> integration in the core. This also has the benefit that it makes the
> functionality available to users of Python 2.6 (and possibly earlier)
> rather than just in 2.7/3.1 onwards.

I have uploaded a python-coded version of this functionality to the
bug page.  I should backport it through 2.3 and post that to pypi, but
I haven't done that yet.  The current effort was focused on the C
module since that's how the rest of datetime is implemented, and also
I wanted to learn a bit about CPython internals.  To the latter point,
I would _really_ appreciate it if someone could leave a few comments
on Rietveld.

>> Please let me know what you think of the idea and/or its execution.
>
> I hope the above comments help. Ultimately, I'd like to see this added
> to the core. It's tricky enough that having a "standard"
> implementation is a definite benefit in itself. But equally, I'd give
> it time to iron out the corner cases on a faster development cycle
> than the core offers before "freezing" it as part of the stdlib.


I understand these concerns.  I think I was too brief in my initial
message.  Here are the docstrings:

>>> print(monthdelta.__doc__)
Months offset from a date or datetime.

monthdeltas allow date calculation without regard to the different lengths
of different months. A monthdelta value added to a date produces another
date that has the same day-of-the-month, regardless of the lengths of the
intervening months. If the resulting date is in too short a month, the
last day in that month will result:

date(2008,1,30) + monthdelta(1) -> date(2008,2,29)

monthdeltas may be added, subtracted, multiplied, and floor-divided
similarly to timedeltas. They may not be added to timedeltas directly, as
both classes are intended to be used directly with dates and datetimes.
Only ints may be passed to the constructor, the default argument of which
is 1 (one). monthdeltas are immutable.

NOTE: in calculations involving the 29th, 30th, and 31st days of the
month, monthdeltas are not necessarily invertible [i.e., the result above
would NOT imply that date(2008,2,29) - monthdelta(1) -> date(2008,1,30)].

>>> print(monthmod.__doc__)
monthmod(start, end) -> (monthdelta, timedelta)

Distribute the interim between start and end dates into monthdelta and
timedelta portions. If and only if start is after end, returned monthdelta
will be negative. Returned timedelta is never negative, and is always
smaller than the month in which end occurs.

Invariant: dt + monthmod(dt, dt+td)[0] + monthmod(dt, dt+td)[1] = dt + td


There is better-looking documentation in html/library/datetime.html
and html/c-api/datetime.html in the patch.  By all means, if you're
curious, download the patch and try it out yourself!

cheers,
Jess