#!/usr/bin/python

# Copyright (C) 2001-2002 Michael D. Stenner <mstenner@phy.duke.edu>
#
#  This program is free software; you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation; either version 2 of the License, or
#  (at your option) any later version.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#
#  You may have received a copy of the GNU General Public License
#  along with this program; if not, write to the Free Software
#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
#  You can also find it at http://www.gnu.org/copyleft/gpl.html

import time

AUTHOR  = 'Michael D. Stenner <mstenner@phy.duke.edu>'
VERSION = '0.1'
DATE    = '2002-10-31'

def make_monthmap(pad=1, basetime=None, month_names=None, use_locale=0):
    """Return a map mapping months to the year they were probably in.

    Consider something like syslog, which returns logs with timestamps
    that look like this: Oct 15 04:11:04

    There's no year, so you have to guess.  A human would say "hmm,
    today is October 31, 2002 so the year of this log is probably
    2002".  This function does the same thing, intelligently
    negotiating year boundaries and allowing for some padding.  For
    example, the date "Nov 5" is assumed to be in the future.

    This returns a map with month abbreviations as keys, and the year
    the month probably occured in as values.

      pad           number of "future" months to use - setting this to 0
                    is probably unwise because local times and incorrect
                    clocks will put you off by a year near the end of
                    each month.  The default is 1.

      basetime      the time tuple to use as a base.  Only the year and
                    month are used, so you can easily build it yourself.
                    The default is the current localtime.  You might set
                    this to the modification time of the log file from
                    which your getting the dates, etc.

      month_names   A list of month names to use as the map keys.  This
                    is None by default, meaning defaults are used.

      use_locale    If true, the current locale will be used to generate
                    the default month abbreviations.  Otherwise the "C"
                    locale values ("Jan", "Feb", etc.) are used.

    """
    
    if month_names is None: # must generate defaults
        if use_locale: # use the current locale
            months = []
            for i in range(0, 12):
                months.append(time.strftime("%b", (0, i+1, 0, 0,
                                                   0, 0, 0, 0, 0)))
        else: # use the C locale
            months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
                      'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
    else: # use the provided list
        months = month_names

    if basetime is None:
        basetime = time.localtime(time.time())
    now_year = basetime[0]
    now_month = basetime[1] # number from 1 to 12
    pad_month = now_month + pad

    monthmap = {}
    # m can be larger than 12 or smaller than 0
    for m in range(pad_month - 12, pad_month):
        monthname = months[m % 12]
        year = now_year + (m / 12) 
        monthmap[monthname] = year
        #print "   ", monthname, year
    return monthmap

def test_make_monthmap():
    import string

    year = 2002
    months = string.split('Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec')

    for i in range(1, 13):
        basetime=(year, i, 0, 0,   0, 0, 0, 0,  0)
        print "now =", time.strftime("%b", basetime), year
        monthmap =  make_monthmap(basetime=basetime)
        for m in months:
            print "   %s %s" % (m, monthmap[m])
            
if __name__ == '__main__':
    test_make_monthmap()