Datetime utility functions

Discussion in 'Python' started by Paul Moore, Sep 15, 2003.

  1. Paul Moore

    Paul Moore Guest

    I was just writing some code which did date/time manipulations, and I
    found that the Python 2.3 datetime module does not supply a number of
    fairly basic functions. I understand the reasoning (the datetime
    module provides a set of datatypes, and doesn't attempt to get into
    the murky waters of date algorithms) but as these things can be quite
    tricky to get right, I was wondering if anyone has already implemented
    any date algorithms, or alternatively if I'd missed some easy way of
    doing what I'm after.

    My specific requirements were:

    1. Get the last day of the month contatining a given date(time). I
    really was surprised to find this one missing, as it seems to me that
    the datetime module must know what the last day for each month is, so
    exposing it wouldn't have been hard.

    2. Add a number of months to a date. This is messy, as there are
    options (what is one month after 31st Jan). The trouble is that the
    calculation, while simple, is tricky to get right (month is 1-based,
    so off-by-1 errors are easy to make, and divmod isn't as useful as
    you'd first think).

    Other "nice to have" functions which I didn't need for this program,
    but which I have found useful in the past, are

    - Round a date(time) to a {year,month,day,quarter,week,...} Or
    truncate. Or (occasionally) chop to the next higher boundary
    (ceiling).
    - Calculate the number of {years,months,days,...} between two dates.
    (Which is more or less the equivalent of rounding a timedelta).

    These latter two aren't very well defined right now, because I have no
    immediate use case.

    In the absence of anything else, I'll probably write a "date
    utilities" module for myself at some point. But I'd hate to be
    reinventing the wheel.

    Paul.
     
    Paul Moore, Sep 15, 2003
    #1
    1. Advertising

  2. Paul Moore

    John Roth Guest

    "Paul Moore" <> wrote in message
    news:...
    > I was just writing some code which did date/time manipulations, and I
    > found that the Python 2.3 datetime module does not supply a number of
    > fairly basic functions. I understand the reasoning (the datetime
    > module provides a set of datatypes, and doesn't attempt to get into
    > the murky waters of date algorithms) but as these things can be quite
    > tricky to get right, I was wondering if anyone has already implemented
    > any date algorithms, or alternatively if I'd missed some easy way of
    > doing what I'm after.
    >
    > My specific requirements were:
    >
    > 1. Get the last day of the month contatining a given date(time). I
    > really was surprised to find this one missing, as it seems to me that
    > the datetime module must know what the last day for each month is, so
    > exposing it wouldn't have been hard.


    I'm kind of surprised to see that it's missing, too.

    > 2. Add a number of months to a date. This is messy, as there are
    > options (what is one month after 31st Jan). The trouble is that the
    > calculation, while simple, is tricky to get right (month is 1-based,
    > so off-by-1 errors are easy to make, and divmod isn't as useful as
    > you'd first think).


    That's application dependent. If a bond, for example, has interest
    payable on the 30th of the month, you probably want the 30th,
    except in February you want the last day of the month. However,
    the contract may specify something else. And in no case do you
    want the date to suddenly change to the 28th because you went
    through February.

    > Other "nice to have" functions which I didn't need for this program,
    > but which I have found useful in the past, are
    >
    > - Round a date(time) to a {year,month,day,quarter,week,...} Or
    > truncate. Or (occasionally) chop to the next higher boundary
    > (ceiling).
    > - Calculate the number of {years,months,days,...} between two dates.
    > (Which is more or less the equivalent of rounding a timedelta).
    >
    > These latter two aren't very well defined right now, because I have no
    > immediate use case.


    Most of these don't have well defined, globally useful use cases.
    It's heavily application dependent what you want out of these.

    > In the absence of anything else, I'll probably write a "date
    > utilities" module for myself at some point. But I'd hate to be
    > reinventing the wheel.


    There's a very well regarded date module out there in the
    Vaults of Parnassus. The name escapes me at the moment,
    but a bit of spelunking through the Vaults will turn up several
    date routines that may do what you want.

    John Roth

    >
    > Paul.
     
    John Roth, Sep 15, 2003
    #2
    1. Advertising

  3. Paul Moore

    Paul Moore Guest

    "John Roth" <> writes:

    > "Paul Moore" <> wrote in message
    > news:...


    >> 1. Get the last day of the month contatining a given date(time). I
    >> really was surprised to find this one missing, as it seems to me that
    >> the datetime module must know what the last day for each month is, so
    >> exposing it wouldn't have been hard.

    >
    > I'm kind of surprised to see that it's missing, too.


    The best solution I could find was

    def month_end(dt):
    # Get the next month
    y, m = dt.year, dt.month
    if m == 12:
    y += 1
    m = 1
    else:
    m += 1

    # Use replace to cater for both datetime and date types. This
    # leaves the time component of a datetime unchanged - it's
    # arguable whether this is the right thing.

    return dt.replace(year=y, month=m, day=1) - datetime.timedelta(days=1)

    It's not hard - but it's mildly tricky (I made a few false starts and
    some silly off-by-one errors) and I'd much rather grab it from a
    library than make the same mistakes next time I need it.

    >> 2. Add a number of months to a date. This is messy, as there are
    >> options (what is one month after 31st Jan). The trouble is that the
    >> calculation, while simple, is tricky to get right (month is 1-based,
    >> so off-by-1 errors are easy to make, and divmod isn't as useful as
    >> you'd first think).

    >
    > That's application dependent.


    True. But for "naive" use, a simple definition does. This is in line
    with the datetime module's philosophy of not trying to cater for
    "advanced" uses, but to provide something useful for straightforward
    use. In this particular case, I'd argue that the obvious definition
    (same day number N months on) where applicable, plus a well-documented
    "reasonable" answer for the edge cases (eg, Jan 31 plus 1 month) is
    useful. In practice, I suspect that 99% of cases involve adding a
    number of months to either the first or the last of a month.

    > If a bond, for example, has interest payable on the 30th of the
    > month, you probably want the 30th, except in February you want the
    > last day of the month. However, the contract may specify something
    > else. And in no case do you want the date to suddenly change to the
    > 28th because you went through February.


    But that's not so much a case of adding a month, as a more complex
    concept, a "repeating date". Nevertheless, I take your point.

    >> In the absence of anything else, I'll probably write a "date
    >> utilities" module for myself at some point. But I'd hate to be
    >> reinventing the wheel.

    >
    > There's a very well regarded date module out there in the
    > Vaults of Parnassus. The name escapes me at the moment,
    > but a bit of spelunking through the Vaults will turn up several
    > date routines that may do what you want.


    I guess you're thinking of mxDateTime. I'm aware of this, and agree
    that it's pretty comprehensive. I don't really know why I prefer not
    to use it - partly it's just a case of reducing dependencies, also
    there are already so many date types in my code (COM, cx_Oracle,
    datetime) that I am reluctant to add another - there is already far
    too much code devoted to converting representations...

    Thanks for the comments,
    Paul.
    --
    This signature intentionally left blank
     
    Paul Moore, Sep 15, 2003
    #3
  4. Paul Moore

    John Roth Guest

    "Paul Moore" <> wrote in message
    news:...
    > "John Roth" <> writes:
    >
    > > "Paul Moore" <> wrote in message
    > > news:...

    >
    > >> 1. Get the last day of the month contatining a given date(time). I
    > >> really was surprised to find this one missing, as it seems to me that
    > >> the datetime module must know what the last day for each month is, so
    > >> exposing it wouldn't have been hard.

    > >
    > > I'm kind of surprised to see that it's missing, too.

    >
    > The best solution I could find was
    >
    > def month_end(dt):
    > # Get the next month
    > y, m = dt.year, dt.month
    > if m == 12:
    > y += 1
    > m = 1
    > else:
    > m += 1


    This looks incomplete. You could use this to get the sequential date
    for the first of the next month, but you still have to subtract one day
    and then print out the day.

    >
    > # Use replace to cater for both datetime and date types. This
    > # leaves the time component of a datetime unchanged - it's
    > # arguable whether this is the right thing.
    >
    > return dt.replace(year=y, month=m, day=1) - datetime.timedelta(days=1)
    >
    > It's not hard - but it's mildly tricky (I made a few false starts and
    > some silly off-by-one errors) and I'd much rather grab it from a
    > library than make the same mistakes next time I need it.


    As I said, I don't see any obvious reason why they wouldn't accept
    a patch, if you want to submit it.

    > >> 2. Add a number of months to a date. This is messy, as there are
    > >> options (what is one month after 31st Jan). The trouble is that the
    > >> calculation, while simple, is tricky to get right (month is 1-based,
    > >> so off-by-1 errors are easy to make, and divmod isn't as useful as
    > >> you'd first think).

    > >
    > > That's application dependent.

    >
    > True. But for "naive" use, a simple definition does. This is in line
    > with the datetime module's philosophy of not trying to cater for
    > "advanced" uses, but to provide something useful for straightforward
    > use. In this particular case, I'd argue that the obvious definition
    > (same day number N months on) where applicable, plus a well-documented
    > "reasonable" answer for the edge cases (eg, Jan 31 plus 1 month) is
    > useful. In practice, I suspect that 99% of cases involve adding a
    > number of months to either the first or the last of a month.


    Except for the edge case I mention below, this is really too simple;
    it's just add one to the month and keep the same date. Hardly worth
    a method at all, especially if you have the "last day of month" method.

    > > If a bond, for example, has interest payable on the 30th of the
    > > month, you probably want the 30th, except in February you want the
    > > last day of the month. However, the contract may specify something
    > > else. And in no case do you want the date to suddenly change to the
    > > 28th because you went through February.

    >
    > But that's not so much a case of adding a month, as a more complex
    > concept, a "repeating date". Nevertheless, I take your point.


    Yes. When you've got something application dependent, they tend
    not to put in "naive" definitions. What's a 'naive' definition for one
    person
    is simply wrong for another.

    John Roth


    > Thanks for the comments,
    > Paul.
    > --
     
    John Roth, Sep 15, 2003
    #4
  5. On 15 Sep 2003 08:07:07 -0700, rumours say that
    (Paul Moore) might have written:

    [about missing datetime functionality]

    >1. Get the last day of the month contatining a given date(time). I
    >really was surprised to find this one missing, as it seems to me that
    >the datetime module must know what the last day for each month is, so
    >exposing it wouldn't have been hard.


    I would guess that the simple ones were not included just because they
    are only a few lines each:

    def end_of_month(a_date):
    year_inc, month_inc = divmod(a_date.month, 12)
    return a_date.__class__(a_date.year+year_inc, 1+month_inc, 1) - \
    datetime.timedelta(days=1)

    def month_days(a_date):
    return end_of_month(a_date).day

    Examples:

    >>> end_of_month(datetime.date.today())

    datetime.date(2003, 9, 30)
    >>> end_of_month(datetime.datetime(1972,2,11))

    datetime.datetime(1972, 2, 29, 0, 0)
    >>> month_days(datetime.date.today())

    30
    >>> end_of_month(datetime.date(1977,12,15))

    datetime.date(1977, 12, 31)

    The add_months_to_date seems not that hard too, but I don't have a need
    for one so far, so I haven't coded it :) My needs for datetime
    intervals are usually of the 'one month start - another month end' kind,
    so end_of_month is handy. If you do think these would be useful, feel
    free to use them (or your own versions) for a patch.

    Date / timedelta rounding / truncating to various units would have to
    take account of many different rules, and none would be very generic
    IMHO.
    --
    TZOTZIOY, I speak England very best,
    Microsoft Security Alert: the Matrix began as open source.
     
    Christos TZOTZIOY Georgiou, Sep 16, 2003
    #5
  6. On Mon, 15 Sep 2003 20:44:08 +0100, rumours say that Paul Moore
    <> might have written:

    [find the end of the month]

    >The best solution I could find was
    >
    >def month_end(dt):
    > # Get the next month
    > y, m = dt.year, dt.month
    > if m == 12:
    > y += 1
    > m = 1
    > else:
    > m += 1
    >
    > # Use replace to cater for both datetime and date types. This
    > # leaves the time component of a datetime unchanged - it's
    > # arguable whether this is the right thing.
    >
    > return dt.replace(year=y, month=m, day=1) - datetime.timedelta(days=1)


    I sent my own version without having seen your own --and mine might seem
    obfuscated, compared to yours. Only a minor suggestion: don't use
    dt.replace, use dt.__class__ instead, since you wouldn't want your
    function to have side-effects (that is, don't destroy the actual object
    that dt is bound to.)
    --
    TZOTZIOY, I speak England very best,
    Microsoft Security Alert: the Matrix began as open source.
     
    Christos TZOTZIOY Georgiou, Sep 16, 2003
    #6
  7. > I was just writing some code which did date/time manipulations, and I
    > found that the Python 2.3 datetime module does not supply a number of

    [...]

    Your message arrived in the exact time.. :)

    Have a look at this:

    http://article.gmane.org/gmane.comp.python.devel/52956

    I'll publish it somewhere an announce here once I get the
    time to do so.

    > My specific requirements were:
    >
    > 1. Get the last day of the month contatining a given date(time). I
    > really was surprised to find this one missing, as it seems to me that
    > the datetime module must know what the last day for each month is, so
    > exposing it wouldn't have been hard.


    I don't understand this one. The last day of the month containing
    a given datetime? A datetime is absolute, how would it be "contained"
    in something else?

    --
    Gustavo Niemeyer
    http://niemeyer.net
     
    Gustavo Niemeyer, Sep 16, 2003
    #7
  8. On Tue, 16 Sep 2003 11:28:58 -0400, rumours say that "Tim Peters"
    <> might have written:

    >[Christos TZOTZIOY Georgiou]
    >> I sent my own version without having seen your own --and mine might
    >> seem obfuscated, compared to yours. Only a minor suggestion: don't
    >> use dt.replace, use dt.__class__ instead, since you wouldn't want your
    >> function to have side-effects (that is, don't destroy the actual
    >> object that dt is bound to.)

    >
    >It's OK to use replace: datetime and date (also time and timedelta) objects
    >are immutable -- their values can't be changed after initialization. In
    >particular, x.replace() doesn't mutate x.


    In some strange, unprecedented and inexplicable way, you are right...
    <sigh> ...again :) RTFM-F virus not removed yet.

    PS That bang thingie (!) in Ruby is pythonic.
    --
    TZOTZIOY, I speak England very best,
    Microsoft Security Alert: the Matrix began as open source.
     
    Christos TZOTZIOY Georgiou, Sep 16, 2003
    #8
  9. On Tue, Sep 16, 2003 at 05:19:50PM +0300, Christos TZOTZIOY Georgiou wrote:
    ....
    > I sent my own version without having seen your own --and mine might seem
    > obfuscated, compared to yours.


    you both use the same indirect way of getting to the end of the month.
    why not do what datetime.c does, like:

    _days_in_month = [
    0, # unused; this vector uses 1-based indexing */
    31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31
    ]

    def _is_leap_year(year):
    return year % 4 == 0 and (year % 100 !=0 or year % 400 == 0)

    def days_in_month(year, month):
    if month == 2 and _is_leap_year(year):
    return 29
    else:
    return _days_in_month[month]

    def end_of_month(d):
    date(d.y, d.m, days_in_month(d.y, d.m))


    --
    groetjes, carel
     
    Carel Fellinger, Sep 16, 2003
    #9
  10. Paul Moore

    Paul Moore Guest

    Christos "TZOTZIOY" Georgiou <> writes:

    > I sent my own version without having seen your own --and mine might seem
    > obfuscated, compared to yours. Only a minor suggestion: don't use
    > dt.replace, use dt.__class__ instead, since you wouldn't want your
    > function to have side-effects (that is, don't destroy the actual object
    > that dt is bound to.)


    dt.replace doesn't have side effects - it creates a new object. Also,
    by using replace(), my version works with date, datetime, or
    subclasses. Yours does too, but it sets the time component of a
    datetime to zero. It's a matter of preference which behaviour is
    "better", I guess.

    Paul.
    --
    This signature intentionally left blank
     
    Paul Moore, Sep 16, 2003
    #10
  11. Paul Moore

    Paul Moore Guest

    Carel Fellinger <> writes:

    > On Tue, Sep 16, 2003 at 05:19:50PM +0300, Christos TZOTZIOY Georgiou wrote:
    > ...
    >> I sent my own version without having seen your own --and mine might seem
    >> obfuscated, compared to yours.

    >
    > you both use the same indirect way of getting to the end of the month.
    > why not do what datetime.c does, like:


    Mainly because that seems even more like reinventing the wheel.
    Writing code that already exists is something I dislike doing at the
    best of times. Writing *tricky* code that already exists feels even
    more unpleasant. (Yes, I know the leap year calculation isn't that
    hard - but lots of people have got it wrong in the past...)

    I guess that's my real issue. I know the datetime module already has
    this information. But persuading it to tell me requires me to jump
    through hoops, whereas reimplementing it feels like admitting defeat.

    None of it's hard, though. I've spent more time on emails about the
    issue than I'd ever need to spend in implementing anything :)

    Paul.
    --
    This signature intentionally left blank
     
    Paul Moore, Sep 16, 2003
    #11
  12. On Tue, 16 Sep 2003 20:26:01 +0100, rumours say that Paul Moore
    <> might have written:

    [I suggesting dt.__class__() instead of dt.replace()]

    >dt.replace doesn't have side effects - it creates a new object. Also,
    >by using replace(), my version works with date, datetime, or
    >subclasses. Yours does too, but it sets the time component of a
    >datetime to zero. It's a matter of preference which behaviour is
    >"better", I guess.


    You are right about dt.replace not having side-effects, just like some
    anonymous<wink> major python contributor commented. Also .replace feels
    "better" since it doesn't lose the time information.

    PS ...but I still like my use of divmod() ;-)
    --
    TZOTZIOY, I speak England very best,
    Microsoft Security Alert: the Matrix began as open source.
     
    Christos TZOTZIOY Georgiou, Sep 16, 2003
    #12
  13. > > you both use the same indirect way of getting to the end of the month.
    > > why not do what datetime.c does, like:

    >
    > Mainly because that seems even more like reinventing the wheel.
    > Writing code that already exists is something I dislike doing at the

    [...]

    Why not using calendar.monthrange()?

    --
    Gustavo Niemeyer
    http://niemeyer.net
     
    Gustavo Niemeyer, Sep 16, 2003
    #13
  14. Paul Moore

    Dan Bishop Guest

    (Paul Moore) wrote in message news:<>...
    > I was just writing some code which did date/time manipulations, and I
    > found that the Python 2.3 datetime module does not supply a number of
    > fairly basic functions. I understand the reasoning (the datetime
    > module provides a set of datatypes, and doesn't attempt to get into
    > the murky waters of date algorithms) but as these things can be quite
    > tricky to get right, I was wondering if anyone has already implemented
    > any date algorithms, or alternatively if I'd missed some easy way of
    > doing what I'm after.
    >
    > [description of needed functions]


    I wrote a module just like that at my last job. Given a date object,
    you could find the first or last day of the month, quarter, or year.
    There were also functions to answer questions like "What was the date
    5 months ago?" or "What date is the first Monday after October 8?"

    Unfortunately, I don't have a copy of the source code here.
     
    Dan Bishop, Sep 17, 2003
    #14
  15. Paul Moore

    Invalid User Guest

    Try 'mxDateTime' available at

    http://www.egenix.com/files/python/eGenix-mx-Extensions.html#Download-mxBASE

    It most likely has what you are looking for.

    Paul Moore wrote:
    > I was just writing some code which did date/time manipulations, and I
    > found that the Python 2.3 datetime module does not supply a number of
    > fairly basic functions. I understand the reasoning (the datetime
    > module provides a set of datatypes, and doesn't attempt to get into
    > the murky waters of date algorithms) but as these things can be quite
    > tricky to get right, I was wondering if anyone has already implemented
    > any date algorithms, or alternatively if I'd missed some easy way of
    > doing what I'm after.
    >
    > My specific requirements were:
    >
    > 1. Get the last day of the month contatining a given date(time). I
    > really was surprised to find this one missing, as it seems to me that
    > the datetime module must know what the last day for each month is, so
    > exposing it wouldn't have been hard.
    >
    > 2. Add a number of months to a date. This is messy, as there are
    > options (what is one month after 31st Jan). The trouble is that the
    > calculation, while simple, is tricky to get right (month is 1-based,
    > so off-by-1 errors are easy to make, and divmod isn't as useful as
    > you'd first think).
    >
    > Other "nice to have" functions which I didn't need for this program,
    > but which I have found useful in the past, are
    >
    > - Round a date(time) to a {year,month,day,quarter,week,...} Or
    > truncate. Or (occasionally) chop to the next higher boundary
    > (ceiling).
    > - Calculate the number of {years,months,days,...} between two dates.
    > (Which is more or less the equivalent of rounding a timedelta).
    >
    > These latter two aren't very well defined right now, because I have no
    > immediate use case.
    >
    > In the absence of anything else, I'll probably write a "date
    > utilities" module for myself at some point. But I'd hate to be
    > reinventing the wheel.
    >
    > Paul.
     
    Invalid User, Sep 17, 2003
    #15
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Christos TZOTZIOY Georgiou
    Replies:
    3
    Views:
    765
    Christos TZOTZIOY Georgiou
    Sep 13, 2003
  2. Tim Peters
    Replies:
    0
    Views:
    602
    Tim Peters
    Sep 9, 2003
  3. mp
    Replies:
    1
    Views:
    444
    John Machin
    Jul 28, 2006
  4. Martin
    Replies:
    0
    Views:
    378
    Martin
    Dec 27, 2008
  5. Replies:
    2
    Views:
    804
    M.-A. Lemburg
    Jan 6, 2009
Loading...

Share This Page