Bug #947906: An object oriented interface has been added to the calendar

module. It's possible to generate HTML calendar now and the module can be
called as a script (e.g. via ``python -mcalendar``).

Doc/lib/libcalendar.tex

@@ -15,12 +15,137 @@ convention). Use \function{setfirstweekday()} to set the first day of the
 week to Sunday (6) or to any other weekday.  Parameters that specify
 dates are given as integers.
 
-Most of these functions rely on the \module{datetime} module which
-uses an idealized calendar, the current Gregorian calendar indefinitely
-extended in both directions.  This matches the definition of the
-"proleptic Gregorian" calendar in Dershowitz and Reingold's book
-"Calendrical Calculations", where it's the base calendar for all
-computations.
+Most of these functions and classses rely on the \module{datetime}
+module which uses an idealized calendar, the current Gregorian
+calendar indefinitely extended in both directions.  This matches
+the definition of the "proleptic Gregorian" calendar in Dershowitz
+and Reingold's book "Calendrical Calculations", where it's the
+base calendar for all computations.
+
+\begin{classdesc}{Calendar}{\optional{firstweekday}}
+Creates a \class{Calendar} object. \var{firstweekday} is an integer
+specifying the first day of the week. 0 is Monday, 6 is Sunday.
+
+A \class{Calendar} object provides several method that can
+be used for preparing the calendar data for formatting. This
+class doesn't do any formatting itself. This is the job of
+subclasses.
+\versionadded{2.5}
+
+\begin{methoddesc}{firstweekday}{}
+Return the first day of the week (as specified in the constructor
+or changed via \method{setfirstweekday()}.
+
+\begin{methoddesc}{setfirstweekday}{weekday}
+Set the first day of the week.
+
+\begin{methoddesc}{iterweekdays}{weekday}
+Return an iterator for the week day numbers that will be used
+for one week. The first number from the iterator will be the
+same as the number return by \method{firstweekday()}.
+
+\begin{methoddesc}{itermonthdates}{year, month}
+Return an iterator for the month \var{month} (1-12) in the
+year \var{year}. This iterator will return all days (as
+\class{datetime.date} objects) for the month and all days
+before the start of the month or after the end of the month
+that are required to get a complete week.
+
+\begin{methoddesc}{itermonthdays2}{year, month}
+Return an iterator for the month \var{month} in the year
+\var{year} similar to \method{itermonthdates()}. Days returned
+will be tuple consisting of a day number and a week day
+number.
+
+\begin{methoddesc}{itermonthdays}{year, month}
+Return an iterator for the month \var{month} in the year
+\var{year} similar to \method{itermonthdates()}. Days returned
+will simply be day numbers.
+
+\begin{methoddesc}{monthdatescalendar}{year, month}
+Return a list of the weeks in the month \var{month} of
+the \var{year} as full weeks. Weeks are lists of seven
+\class{datetime.date} objects.
+
+\begin{methoddesc}{monthdays2calendar}{year, month}
+Return a list of the weeks in the month \var{month} of
+the \var{year} as full weeks. Weeks are lists of seven
+tuples of day numbers and weekday numbers.
+
+\begin{methoddesc}{monthdayscalendar}{year, month}
+Return a list of the weeks in the month \var{month} of
+the \var{year} as full weeks. Weeks are lists of seven
+day numbers.
+
+\begin{methoddesc}{yeardatescalendar}{year, month\optional{, width}}
+Return the data for the specified year ready for formatting. The return
+value is a list of month rows. Each month row contains upto \var{width}
+months (defaulting to 3). Each month contains between 4 and 6 weeks and
+each week contains 1-7 days. Days are \class{datetime.date} objects.
+
+\begin{methoddesc}{yeardays2calendar}{year, month\optional{, width}}
+Return the data for the specified year ready for formatting (similar to
+\method{yeardatescalendar()}). Entries in the week lists are tuples of
+day numbers and weekday numbers. Day numbers outside this month are zero.
+
+\begin{methoddesc}{yeardayscalendar}{year, month\optional{, width}}
+Return the data for the specified year ready for formatting (similar to
+\method{yeardatescalendar()}). Entries in the week lists are day numbers.
+Day numbers outside this month are zero.
+
+
+\begin{classdesc}{TextCalendar}{\optional{firstweekday}}
+This class can be used for generating plain text calendars.
+
+\versionadded{2.5}
+
+\begin{methoddesc}{formatmonth}{theyear, themonth\optional{, w\optional{, l}}}
+Returns a month's calendar in a multi-line string. If \var{w} is
+provided, it specifies the width of the date columns, which are
+centered. If \var{l} is given, it specifies the number of lines that
+each week will use. Depends on the first weekday as set by
+\function{setfirstweekday()}.
+
+\begin{methoddesc}{prmonth}{theyear, themonth\optional{, w\optional{, l}}}
+Prints a month's calendar as returned by \method{formatmonth()}.
+
+\begin{methoddesc}{formatyear}{theyear, themonth\optional{, w\optional{, l\optional{, c\optional{, m}}}}}
+Returns a \var{m}-column calendar for an entire year as a multi-line string.
+Optional parameters \var{w}, \var{l}, and \var{c} are for date column
+width, lines per week, and number of spaces between month columns,
+respectively. Depends on the first weekday as set by
+\method{setfirstweekday()}.  The earliest year for which a calendar can
+be generated is platform-dependent.
+
+\begin{methoddesc}{pryear}{theyear\optional{, w\optional{, l\optional{, c\optional{, m}}}}}
+Prints the calendar for an entire year as returned by  \method{formatyear()}.
+\end{funcdesc}
+
+
+\begin{classdesc}{HTMLCalendar}{\optional{firstweekday}}
+This class can be used for generating HTML calendars.
+
+\versionadded{2.5}
+
+\begin{methoddesc}{formatmonth}{theyear, themonth\optional{, withyear}}
+Returns a month's calendar as an HTML table. If \var{withyear} is
+true the year will be included in the header, otherwise just the
+monthname will be used.
+
+\begin{methoddesc}{formatyear}{theyear, themonth\optional{, width}}
+Returns a year's calendar as an HTML table. \var{width} (defaulting to 3)
+specifies the number of months per row.
+
+\begin{methoddesc}{formatyearpage}{theyear, themonth\optional{, width\optional{, css\optional{, encoding}}}}
+Returns a year's calendar as an complete HTML page. \var{width}
+(defaulting to 3) specifies the number of months per row. \var{css}
+is the name for the cascading style sheet to be used. \constant{None}
+can be passed, if no style sheet should be used. \var{encoding}
+specifies the encoding to be used for the output (defaulting
+the the system default encoding).
+
+
+For simple text calendars this module provides the following functions.
 
 \begin{funcdesc}{setfirstweekday}{weekday}
 Sets the weekday (\code{0} is Monday, \code{6} is Sunday) to start
@@ -80,11 +205,8 @@ Prints a month's calendar as returned by \function{month()}.
 \end{funcdesc}
 
 \begin{funcdesc}{month}{theyear, themonth\optional{, w\optional{, l}}}
-Returns a month's calendar in a multi-line string. If \var{w} is
-provided, it specifies the width of the date columns, which are
-centered. If \var{l} is given, it specifies the number of lines that
-each week will use. Depends on the first weekday as set by
-\function{setfirstweekday()}.
+Returns a month's calendar in a multi-line string using the
+\method{formatmonth} of the \class{TextCalendar} class.
 \versionadded{2.0}
 \end{funcdesc}
 
@@ -94,12 +216,8 @@ Prints the calendar for an entire year as returned by
 \end{funcdesc}
 
 \begin{funcdesc}{calendar}{year\optional{, w\optional{, l\optional{c}}}}
-Returns a 3-column calendar for an entire year as a multi-line string.
-Optional parameters \var{w}, \var{l}, and \var{c} are for date column
-width, lines per week, and number of spaces between month columns,
-respectively. Depends on the first weekday as set by
-\function{setfirstweekday()}.  The earliest year for which a calendar can
-be generated is platform-dependent.
+Returns a 3-column calendar for an entire year as a multi-line string
+using the \method{formatyear} of the \class{TextCalendar} class.
 \versionadded{2.0}
 \end{funcdesc}
 

Lib/test/test_calendar.py

@@ -4,6 +4,64 @@ import unittest
 from test import test_support
 
 
+result_2004 = """
+                                  2004
+
+      January                   February                   March
+Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
+          1  2  3  4                         1       1  2  3  4  5  6  7
+ 5  6  7  8  9 10 11       2  3  4  5  6  7  8       8  9 10 11 12 13 14
+12 13 14 15 16 17 18       9 10 11 12 13 14 15      15 16 17 18 19 20 21
+19 20 21 22 23 24 25      16 17 18 19 20 21 22      22 23 24 25 26 27 28
+26 27 28 29 30 31         23 24 25 26 27 28 29      29 30 31
+
+       April                      May                       June
+Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
+          1  2  3  4                      1  2          1  2  3  4  5  6
+ 5  6  7  8  9 10 11       3  4  5  6  7  8  9       7  8  9 10 11 12 13
+12 13 14 15 16 17 18      10 11 12 13 14 15 16      14 15 16 17 18 19 20
+19 20 21 22 23 24 25      17 18 19 20 21 22 23      21 22 23 24 25 26 27
+26 27 28 29 30            24 25 26 27 28 29 30      28 29 30
+                          31
+
+        July                     August                  September
+Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
+          1  2  3  4                         1             1  2  3  4  5
+ 5  6  7  8  9 10 11       2  3  4  5  6  7  8       6  7  8  9 10 11 12
+12 13 14 15 16 17 18       9 10 11 12 13 14 15      13 14 15 16 17 18 19
+19 20 21 22 23 24 25      16 17 18 19 20 21 22      20 21 22 23 24 25 26
+26 27 28 29 30 31         23 24 25 26 27 28 29      27 28 29 30
+                          30 31
+
+      October                   November                  December
+Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
+             1  2  3       1  2  3  4  5  6  7             1  2  3  4  5
+ 4  5  6  7  8  9 10       8  9 10 11 12 13 14       6  7  8  9 10 11 12
+11 12 13 14 15 16 17      15 16 17 18 19 20 21      13 14 15 16 17 18 19
+18 19 20 21 22 23 24      22 23 24 25 26 27 28      20 21 22 23 24 25 26
+25 26 27 28 29 30 31      29 30                     27 28 29 30 31
+"""
+
+
+class OutputTestCase(unittest.TestCase):
+    def normalize_calendar(self, s):
+        def neitherspacenordigit(c):
+            return not c.isspace() and not c.isdigit()
+
+        lines = []
+        for line in s.splitlines(False):
+            # Drop texts, as they are locale dependent
+            if line and not filter(neitherspacenordigit, line):
+                lines.append(line)
+        return lines
+
+    def test_output(self):
+        self.assertEqual(
+            self.normalize_calendar(calendar.calendar(2004)),
+            self.normalize_calendar(result_2004)
+        )
+
+
 class CalendarTestCase(unittest.TestCase):
     def test_isleap(self):
         # Make sure that the return is right for a few years, and
@@ -72,57 +130,57 @@ class MondayTestCase(MonthCalendarTestCase):
     firstweekday = calendar.MONDAY
 
     def test_february(self):
-        # A 28-day february starting of monday (7+7+7+7 days)
+        # A 28-day february starting on monday (7+7+7+7 days)
         self.check_weeks(1999, 2, (7, 7, 7, 7))
 
-        # A 28-day february starting of tuesday (6+7+7+7+1 days)
+        # A 28-day february starting on tuesday (6+7+7+7+1 days)
         self.check_weeks(2005, 2, (6, 7, 7, 7, 1))
 
-        # A 28-day february starting of sunday (1+7+7+7+6 days)
+        # A 28-day february starting on sunday (1+7+7+7+6 days)
         self.check_weeks(1987, 2, (1, 7, 7, 7, 6))
 
-        # A 29-day february starting of monday (7+7+7+7+1 days)
+        # A 29-day february starting on monday (7+7+7+7+1 days)
         self.check_weeks(1988, 2, (7, 7, 7, 7, 1))
 
-        # A 29-day february starting of tuesday (6+7+7+7+2 days)
+        # A 29-day february starting on tuesday (6+7+7+7+2 days)
         self.check_weeks(1972, 2, (6, 7, 7, 7, 2))
 
-        # A 29-day february starting of sunday (1+7+7+7+7 days)
+        # A 29-day february starting on sunday (1+7+7+7+7 days)
         self.check_weeks(2004, 2, (1, 7, 7, 7, 7))
 
     def test_april(self):
-        # A 30-day april starting of monday (7+7+7+7+2 days)
+        # A 30-day april starting on monday (7+7+7+7+2 days)
         self.check_weeks(1935, 4, (7, 7, 7, 7, 2))
 
-        # A 30-day april starting of tuesday (6+7+7+7+3 days)
+        # A 30-day april starting on tuesday (6+7+7+7+3 days)
         self.check_weeks(1975, 4, (6, 7, 7, 7, 3))
 
-        # A 30-day april starting of sunday (1+7+7+7+7+1 days)
+        # A 30-day april starting on sunday (1+7+7+7+7+1 days)
         self.check_weeks(1945, 4, (1, 7, 7, 7, 7, 1))
 
-        # A 30-day april starting of saturday (2+7+7+7+7 days)
+        # A 30-day april starting on saturday (2+7+7+7+7 days)
         self.check_weeks(1995, 4, (2, 7, 7, 7, 7))
 
-        # A 30-day april starting of friday (3+7+7+7+6 days)
+        # A 30-day april starting on friday (3+7+7+7+6 days)
         self.check_weeks(1994, 4, (3, 7, 7, 7, 6))
 
     def test_december(self):
-        # A 31-day december starting of monday (7+7+7+7+3 days)
+        # A 31-day december starting on monday (7+7+7+7+3 days)
         self.check_weeks(1980, 12, (7, 7, 7, 7, 3))
 
-        # A 31-day december starting of tuesday (6+7+7+7+4 days)
+        # A 31-day december starting on tuesday (6+7+7+7+4 days)
         self.check_weeks(1987, 12, (6, 7, 7, 7, 4))
 
-        # A 31-day december starting of sunday (1+7+7+7+7+2 days)
+        # A 31-day december starting on sunday (1+7+7+7+7+2 days)
         self.check_weeks(1968, 12, (1, 7, 7, 7, 7, 2))
 
-        # A 31-day december starting of thursday (4+7+7+7+6 days)
+        # A 31-day december starting on thursday (4+7+7+7+6 days)
         self.check_weeks(1988, 12, (4, 7, 7, 7, 6))
 
-        # A 31-day december starting of friday (3+7+7+7+7 days)
+        # A 31-day december starting on friday (3+7+7+7+7 days)
         self.check_weeks(2017, 12, (3, 7, 7, 7, 7))
 
-        # A 31-day december starting of saturday (2+7+7+7+7+1 days)
+        # A 31-day december starting on saturday (2+7+7+7+7+1 days)
         self.check_weeks(2068, 12, (2, 7, 7, 7, 7, 1))
 
 
@@ -130,62 +188,63 @@ class SundayTestCase(MonthCalendarTestCase):
     firstweekday = calendar.SUNDAY
 
     def test_february(self):
-        # A 28-day february starting of sunday (7+7+7+7 days)
+        # A 28-day february starting on sunday (7+7+7+7 days)
         self.check_weeks(2009, 2, (7, 7, 7, 7))
 
-        # A 28-day february starting of monday (6+7+7+7+1 days)
+        # A 28-day february starting on monday (6+7+7+7+1 days)
         self.check_weeks(1999, 2, (6, 7, 7, 7, 1))
 
-        # A 28-day february starting of saturday (1+7+7+7+6 days)
+        # A 28-day february starting on saturday (1+7+7+7+6 days)
         self.check_weeks(1997, 2, (1, 7, 7, 7, 6))
 
-        # A 29-day february starting of sunday (7+7+7+7+1 days)
+        # A 29-day february starting on sunday (7+7+7+7+1 days)
         self.check_weeks(2004, 2, (7, 7, 7, 7, 1))
 
-        # A 29-day february starting of monday (6+7+7+7+2 days)
+        # A 29-day february starting on monday (6+7+7+7+2 days)
         self.check_weeks(1960, 2, (6, 7, 7, 7, 2))
 
-        # A 29-day february starting of saturday (1+7+7+7+7 days)
+        # A 29-day february starting on saturday (1+7+7+7+7 days)
         self.check_weeks(1964, 2, (1, 7, 7, 7, 7))
 
     def test_april(self):
-        # A 30-day april starting of sunday (7+7+7+7+2 days)
+        # A 30-day april starting on sunday (7+7+7+7+2 days)
         self.check_weeks(1923, 4, (7, 7, 7, 7, 2))
 
-        # A 30-day april starting of monday (6+7+7+7+3 days)
+        # A 30-day april starting on monday (6+7+7+7+3 days)
         self.check_weeks(1918, 4, (6, 7, 7, 7, 3))
 
-        # A 30-day april starting of saturday (1+7+7+7+7+1 days)
+        # A 30-day april starting on saturday (1+7+7+7+7+1 days)
         self.check_weeks(1950, 4, (1, 7, 7, 7, 7, 1))
 
-        # A 30-day april starting of friday (2+7+7+7+7 days)
+        # A 30-day april starting on friday (2+7+7+7+7 days)
         self.check_weeks(1960, 4, (2, 7, 7, 7, 7))
 
-        # A 30-day april starting of thursday (3+7+7+7+6 days)
+        # A 30-day april starting on thursday (3+7+7+7+6 days)
         self.check_weeks(1909, 4, (3, 7, 7, 7, 6))
 
     def test_december(self):
-        # A 31-day december starting of sunday (7+7+7+7+3 days)
+        # A 31-day december starting on sunday (7+7+7+7+3 days)
         self.check_weeks(2080, 12, (7, 7, 7, 7, 3))
 
-        # A 31-day december starting of monday (6+7+7+7+4 days)
+        # A 31-day december starting on monday (6+7+7+7+4 days)
         self.check_weeks(1941, 12, (6, 7, 7, 7, 4))
 
-        # A 31-day december starting of saturday (1+7+7+7+7+2 days)
+        # A 31-day december starting on saturday (1+7+7+7+7+2 days)
         self.check_weeks(1923, 12, (1, 7, 7, 7, 7, 2))
 
-        # A 31-day december starting of wednesday (4+7+7+7+6 days)
+        # A 31-day december starting on wednesday (4+7+7+7+6 days)
         self.check_weeks(1948, 12, (4, 7, 7, 7, 6))
 
-        # A 31-day december starting of thursday (3+7+7+7+7 days)
+        # A 31-day december starting on thursday (3+7+7+7+7 days)
         self.check_weeks(1927, 12, (3, 7, 7, 7, 7))
 
-        # A 31-day december starting of friday (2+7+7+7+7+1 days)
+        # A 31-day december starting on friday (2+7+7+7+7+1 days)
         self.check_weeks(1995, 12, (2, 7, 7, 7, 7, 1))
 
 
 def test_main():
     test_support.run_unittest(
+        OutputTestCase,
         CalendarTestCase,
         MondayTestCase,
         SundayTestCase

Misc/NEWS

@@ -895,6 +895,10 @@ Library
 - Patch #1413711: Certain patterns of differences were making difflib
   touch the recursion limit.
 
+- Bug #947906: An object oriented interface has been added to the calendar
+  module. It's possible to generate HTML calendar now and the module can be
+  called as a script (e.g. via ``python -mcalendar``).
+
 Build
 -----