[Python-Dev] dateutil

[Tim Peters]

[Gustavo Niemeyer]
> Subject: [Python-Dev] dateutil
>
> Yes, it's time for the classical question. ;-)
>
> What's your opinion about the inclusion of the dateutil[1]
> extension in the standard library?
>
> [1] https://moin.conectiva.com.br/DateUtil

The docs aren't clear enough to predict what the code may or may not do.  I
can't make time for an exhaustive review, so I'll just stop after pointing
out ambiguities in the relativedelta docs:

    And the other way is to use any of the following keyword arguments:

    year, month, day, hour, minute, seconds, microseconds
    Absolute information.

Why are only the last two plural?  What does absolute *mean*?  What type(s)
are these things?

    years, months, weeks, days, hours, minutes, seconds, microseconds
    Relative information, may be negative.

How can "seconds" and "microseconds" be both absolute and relative?  What
type(s)?  What ranges?  For example, does days=+1000 make sense?

    weekday
    One of the weekday instances (MO, TU, etc).  These instances may
    receive a parameter n, specifying the nth weekday, which could be
    positive or negative (like MO(+2) or MO(-3).

Does MO(+42) make sense?  MO(-42)?  At this point it's not clear what MO(+2)
or MO(-3) may mean either.  What about MO(0)?  Or is there "a hole" at 0 in
this scheme?  Is MO(+2) different than MO(2)?

    Not specifying it is the same as specifying +1.

Not exactly clear what "it" means.  Assuming it means the argument n.

    You can also use an integer, where 0=MO.

Meaning that MO(0) is the same as MO(MO)?  Or that you can say weekday=0?
If the latter, what's the full set of allowed integers?

    Notice that, for example, if the calculated date is already Monday,
    using MO or MO(+1) (which is the same thing in this context), won't
    change the day.

So we know that if the calculated date is a Monday, then if

    weekday=MO
or
    weekday=MO(+1)

were specified then they won't change the day.  It hasn't explained what any
other value means.

    leapdays
    Will add given days to the date found, but only if the computed
    year is a leap year and the computed date is post 28 of february.

Couldn't follow this one at all.  Is this a Boolean argument?  An integer?
The explanation below makes it sound like a bool, but the "add given days"
above makes it sound like an int.  If integer, what range?  What use is
this?

    yearday, nlyearday
    Set the yearday or the non-leap year day (jump leap days). These are
    converted to day/month/leapdays information.

"jump leap days" doesn't mean anything to me, and neither does "yearday".
Are "yearday" and "nlyearday" mutually exclusive, or can you specifiy both?
What types, and ranges, make sense for them?  What do they mean?

    If you're curious about exactly how the relative delta will act on
    operations, here is a description of its behavior.

What are the supported operations?  The docs mention

    relativedelta(datetime1, datetime2)

and

    datetime1 = datetime2 + relativedelta(datetime1, datetime2)

The explanation below doesn't seem to make any sense for the first of those,
so it must be explaining the second.  Are these the *only* supported
operations?  For example, datetime.timedelta also supports multiplying
timedelta by an integer.

    1. Calculate the absolute year, using the year argument, or the
       original datetime year, if the argument is not present.

Are there range restrictions on these?  If so, what happens if they go out
of bounds?

    2. Add the relative years argument to the absolute year.

I *assume* that the relative years added here is 0 if no years= was
specified.  Same questions about range restrictions.

    3. Do steps 1 and 2 for month/months.

Same questions, but more acutely, as it's obviously possible for even simple
arguments like months=-2 to lead to a calculated month outside range(1, 13).
What happens then?

    4. Calculate the absolute day, using the day argument, or the
       original datetime day, if the argument is not present.  Then,
       subtract from the day until it fits in the year and month found
       after their operations.

    5. Add the relative days argument to the absolute day.

What if the resulting day doesn't "fit in the year and month found" so far?

      Notice that the weeks argument is multiplied by 7 and added
      to days.

   6. If leapdays is present, the computed year is a leap year, and
      the computed month is after february, remove one day from the
      found date.

So leapdays=True and leapdays=False and leapdays=45 and leapdays=None all
mean the same thing?

   7. Do steps 1 and 2 for hour/hours, minute/minutes, second/seconds,
      microsecond/microseconds.

All the same questions about types, ranges, and what happens when results
are out of range.  If I understood what the rest of it intended, I suspect
I'd also wonder what happens if leapdays=True, the computed date after #6 is
February 1, and hours=24*60 was passed.  *Presumably* 60 days get added to
the date then, moving the result well beyond February, but then the presence
of leapdays *doesn't* "remove one day"?

   8. If the weekday argument is present, calculate the nth occurrence of
      the given weekday.

Where +1 means "don't move if you're already there, but move ahead to the
closest succeeding if you're not"?  -1 means "move to closest preceding, and
regardless of whether you're already there"?  0 is an error, or means the
same as +1, or ...?

That was the end of the explanation, and "yearday" and "nlyearday" weren't
mentioned again.

None of this is meant to imply that the functionality isn't useful -- it's
that the functionality isn't specified clearly enough to know what it is.

Is it true that adding relativedelta(months=+1) 12 times isn't necessarily
the same as adding relativedelta(years=+1) once?  (I picture starting with
31 January, landing on Feb 28 or 29 after one addition of months=+1, and
then sticking on 28 or 29 thereafter.)