=========================== calendar -- Work with dates =========================== .. module:: calendar :synopsis: The calendar module implements classes for working with dates to manage year/month/week oriented values. :Purpose: The calendar module implements classes for working with dates to manage year/month/week oriented values. :Available In: 1.4, with updates in 2.5 The calendar module defines the Calendar class, which encapsulates calculations for values such as the dates of the weeks in a given month or year. In addition, the TextCalendar and HTMLCalendar classes can produce pre-formatted output. Formatting Examples =================== A very simple example which produces formatted text output for a month using TextCalendar might use the prmonth() method. .. include:: calendar_textcalendar.py :literal: :start-after: #end_pymotw_header The example configures TextCalendar to start weeks on Sunday, following the American convention. The default is to use the European convention of starting a week on Monday. The output looks like: .. {{{cog .. cog.out(run_script(cog.inFile, 'calendar_textcalendar.py')) .. }}} :: $ python calendar_textcalendar.py July 2007 Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 .. {{{end}}} The HTML output for the same time period is slightly different, since there is no prmonth() method: .. include:: calendar_htmlcalendar.py :literal: :start-after: #end_pymotw_header The rendered output looks roughly the same, but is wrapped with HTML tags. You can also see that each table cell has a class attribute corresponding to the day of the week. .. {{{cog .. cog.out(run_script(cog.inFile, 'calendar_htmlcalendar.py')) .. }}} :: $ python calendar_htmlcalendar.py
July 2007
SunMonTueWedThuFriSat
1234567
891011121314
15161718192021
22232425262728
293031    
.. {{{end}}} If you need to produce output in a format other than one of the available defaults, you can use :mod:`calendar` to calculate the dates and organize the values into week and month ranges, then iterate over the result yourself. The weekheader(), monthcalendar(), and yeardays2calendar() methods of Calendar are especially useful for that sort of work. Calling yeardays2calendar() produces a sequence of "month row" lists. Each list includes the months as another list of weeks. The weeks are lists of tuples made up of day number (1-31) and weekday number (0-6). Days that fall outside of the month have a day number of 0. .. include:: calendar_yeardays2calendar.py :literal: :start-after: #end_pymotw_header Calling yeardays2calendar(2007, 2) returns data for 2007, organized with 2 months per row. .. {{{cog .. cog.out(run_script(cog.inFile, 'calendar_yeardays2calendar.py')) .. }}} :: $ python calendar_yeardays2calendar.py [[[[(0, 6), (1, 0), (2, 1), (3, 2), (4, 3), (5, 4), (6, 5)], [(7, 6), (8, 0), (9, 1), (10, 2), (11, 3), (12, 4), (13, 5)], [(14, 6), (15, 0), (16, 1), (17, 2), (18, 3), (19, 4), (20, 5)], [(21, 6), (22, 0), (23, 1), (24, 2), (25, 3), (26, 4), (27, 5)], [(28, 6), (29, 0), (30, 1), (31, 2), (0, 3), (0, 4), (0, 5)]], [[(0, 6), (0, 0), (0, 1), (0, 2), (1, 3), (2, 4), (3, 5)], [(4, 6), (5, 0), (6, 1), (7, 2), (8, 3), (9, 4), (10, 5)], [(11, 6), (12, 0), (13, 1), (14, 2), (15, 3), (16, 4), (17, 5)], [(18, 6), (19, 0), (20, 1), (21, 2), (22, 3), (23, 4), (24, 5)], [(25, 6), (26, 0), (27, 1), (28, 2), (0, 3), (0, 4), (0, 5)]]], [[[(0, 6), (0, 0), (0, 1), (0, 2), (1, 3), (2, 4), (3, 5)], [(4, 6), (5, 0), (6, 1), (7, 2), (8, 3), (9, 4), (10, 5)], [(11, 6), (12, 0), (13, 1), (14, 2), (15, 3), (16, 4), (17, 5)], [(18, 6), (19, 0), (20, 1), (21, 2), (22, 3), (23, 4), (24, 5)], [(25, 6), (26, 0), (27, 1), (28, 2), (29, 3), (30, 4), (31, 5)]], [[(1, 6), (2, 0), (3, 1), (4, 2), (5, 3), (6, 4), (7, 5)], [(8, 6), (9, 0), (10, 1), (11, 2), (12, 3), (13, 4), (14, 5)], [(15, 6), (16, 0), (17, 1), (18, 2), (19, 3), (20, 4), (21, 5)], [(22, 6), (23, 0), (24, 1), (25, 2), (26, 3), (27, 4), (28, 5)], [(29, 6), (30, 0), (0, 1), (0, 2), (0, 3), (0, 4), (0, 5)]]], [[[(0, 6), (0, 0), (1, 1), (2, 2), (3, 3), (4, 4), (5, 5)], [(6, 6), (7, 0), (8, 1), (9, 2), (10, 3), (11, 4), (12, 5)], [(13, 6), (14, 0), (15, 1), (16, 2), (17, 3), (18, 4), (19, 5)], [(20, 6), (21, 0), (22, 1), (23, 2), (24, 3), (25, 4), (26, 5)], [(27, 6), (28, 0), (29, 1), (30, 2), (31, 3), (0, 4), (0, 5)]], [[(0, 6), (0, 0), (0, 1), (0, 2), (0, 3), (1, 4), (2, 5)], [(3, 6), (4, 0), (5, 1), (6, 2), (7, 3), (8, 4), (9, 5)], [(10, 6), (11, 0), (12, 1), (13, 2), (14, 3), (15, 4), (16, 5)], [(17, 6), (18, 0), (19, 1), (20, 2), (21, 3), (22, 4), (23, 5)], [(24, 6), (25, 0), (26, 1), (27, 2), (28, 3), (29, 4), (30, 5)]]], [[[(1, 6), (2, 0), (3, 1), (4, 2), (5, 3), (6, 4), (7, 5)], [(8, 6), (9, 0), (10, 1), (11, 2), (12, 3), (13, 4), (14, 5)], [(15, 6), (16, 0), (17, 1), (18, 2), (19, 3), (20, 4), (21, 5)], [(22, 6), (23, 0), (24, 1), (25, 2), (26, 3), (27, 4), (28, 5)], [(29, 6), (30, 0), (31, 1), (0, 2), (0, 3), (0, 4), (0, 5)]], [[(0, 6), (0, 0), (0, 1), (1, 2), (2, 3), (3, 4), (4, 5)], [(5, 6), (6, 0), (7, 1), (8, 2), (9, 3), (10, 4), (11, 5)], [(12, 6), (13, 0), (14, 1), (15, 2), (16, 3), (17, 4), (18, 5)], [(19, 6), (20, 0), (21, 1), (22, 2), (23, 3), (24, 4), (25, 5)], [(26, 6), (27, 0), (28, 1), (29, 2), (30, 3), (31, 4), (0, 5)]]], [[[(0, 6), (0, 0), (0, 1), (0, 2), (0, 3), (0, 4), (1, 5)], [(2, 6), (3, 0), (4, 1), (5, 2), (6, 3), (7, 4), (8, 5)], [(9, 6), (10, 0), (11, 1), (12, 2), (13, 3), (14, 4), (15, 5)], [(16, 6), (17, 0), (18, 1), (19, 2), (20, 3), (21, 4), (22, 5)], [(23, 6), (24, 0), (25, 1), (26, 2), (27, 3), (28, 4), (29, 5)], [(30, 6), (0, 0), (0, 1), (0, 2), (0, 3), (0, 4), (0, 5)]], [[(0, 6), (1, 0), (2, 1), (3, 2), (4, 3), (5, 4), (6, 5)], [(7, 6), (8, 0), (9, 1), (10, 2), (11, 3), (12, 4), (13, 5)], [(14, 6), (15, 0), (16, 1), (17, 2), (18, 3), (19, 4), (20, 5)], [(21, 6), (22, 0), (23, 1), (24, 2), (25, 3), (26, 4), (27, 5)], [(28, 6), (29, 0), (30, 1), (31, 2), (0, 3), (0, 4), (0, 5)]]], [[[(0, 6), (0, 0), (0, 1), (0, 2), (1, 3), (2, 4), (3, 5)], [(4, 6), (5, 0), (6, 1), (7, 2), (8, 3), (9, 4), (10, 5)], [(11, 6), (12, 0), (13, 1), (14, 2), (15, 3), (16, 4), (17, 5)], [(18, 6), (19, 0), (20, 1), (21, 2), (22, 3), (23, 4), (24, 5)], [(25, 6), (26, 0), (27, 1), (28, 2), (29, 3), (30, 4), (0, 5)]], [[(0, 6), (0, 0), (0, 1), (0, 2), (0, 3), (0, 4), (1, 5)], [(2, 6), (3, 0), (4, 1), (5, 2), (6, 3), (7, 4), (8, 5)], [(9, 6), (10, 0), (11, 1), (12, 2), (13, 3), (14, 4), (15, 5)], [(16, 6), (17, 0), (18, 1), (19, 2), (20, 3), (21, 4), (22, 5)], [(23, 6), (24, 0), (25, 1), (26, 2), (27, 3), (28, 4), (29, 5)], [(30, 6), (31, 0), (0, 1), (0, 2), (0, 3), (0, 4), (0, 5)]]]] .. {{{end}}} This is equivalent to the data used by formatyear() .. include:: calendar_formatyear.py :literal: :start-after: #end_pymotw_header which for the same arguments produces output like: .. {{{cog .. cog.out(run_script(cog.inFile, 'calendar_formatyear.py')) .. }}} :: $ python calendar_formatyear.py 2007 January February Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 1 2 3 7 8 9 10 11 12 13 4 5 6 7 8 9 10 14 15 16 17 18 19 20 11 12 13 14 15 16 17 21 22 23 24 25 26 27 18 19 20 21 22 23 24 28 29 30 31 25 26 27 28 March April Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 2 3 1 2 3 4 5 6 7 4 5 6 7 8 9 10 8 9 10 11 12 13 14 11 12 13 14 15 16 17 15 16 17 18 19 20 21 18 19 20 21 22 23 24 22 23 24 25 26 27 28 25 26 27 28 29 30 31 29 30 May June Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 2 3 4 5 1 2 6 7 8 9 10 11 12 3 4 5 6 7 8 9 13 14 15 16 17 18 19 10 11 12 13 14 15 16 20 21 22 23 24 25 26 17 18 19 20 21 22 23 27 28 29 30 31 24 25 26 27 28 29 30 July August Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 7 1 2 3 4 8 9 10 11 12 13 14 5 6 7 8 9 10 11 15 16 17 18 19 20 21 12 13 14 15 16 17 18 22 23 24 25 26 27 28 19 20 21 22 23 24 25 29 30 31 26 27 28 29 30 31 September October Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 1 2 3 4 5 6 2 3 4 5 6 7 8 7 8 9 10 11 12 13 9 10 11 12 13 14 15 14 15 16 17 18 19 20 16 17 18 19 20 21 22 21 22 23 24 25 26 27 23 24 25 26 27 28 29 28 29 30 31 30 November December Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 2 3 1 4 5 6 7 8 9 10 2 3 4 5 6 7 8 11 12 13 14 15 16 17 9 10 11 12 13 14 15 18 19 20 21 22 23 24 16 17 18 19 20 21 22 25 26 27 28 29 30 23 24 25 26 27 28 29 30 31 .. {{{end}}} If you want to format the output yourself for some reason (such as including links in HTML output), you will find the day_name, day_abbr, month_name, and month_abbr module attributes useful. They are automatically configured correctly for the current locale. Calculating Dates ================= Although the calendar module focuses mostly on printing full calendars in various formats, it also provides functions useful for working with dates in other ways, such as calculating dates for a recurring event. For example, the Python Atlanta User's Group meets the 2nd Thursday of every month. To calculate the dates for the meetings for a year, you could use the return value of monthcalendar(). .. include:: calendar_monthcalendar.py :literal: :start-after: #end_pymotw_header Notice that some days are 0. Those are days of the week that overlap with the given month but which are part of another month. .. {{{cog .. cog.out(run_script(cog.inFile, 'calendar_monthcalendar.py')) .. }}} :: $ python calendar_monthcalendar.py [[0, 0, 0, 0, 0, 0, 1], [2, 3, 4, 5, 6, 7, 8], [9, 10, 11, 12, 13, 14, 15], [16, 17, 18, 19, 20, 21, 22], [23, 24, 25, 26, 27, 28, 29], [30, 31, 0, 0, 0, 0, 0]] .. {{{end}}} As mentioned earlier, the first day of the week is Monday. It is possible to change that by calling setfirstweekday(). On the other hand, since the calendar module includes constants for indexing into the date ranges returned by monthcalendar(), it is more convenient to skip that step in this case. To calculate the PyATL meeting dates for 2007, assuming the second Thursday of every month, we can use the 0 values to tell us whether the Thursday of the first week is included in the month (or if the month starts, for example on a Friday). .. include:: calendar_secondthursday.py :literal: :start-after: #end_pymotw_header So the PyATL meeting schedule for the year is: .. {{{cog .. cog.out(run_script(cog.inFile, 'calendar_secondthursday.py')) .. }}} :: $ python calendar_secondthursday.py 1: 11 2: 8 3: 8 4: 12 5: 10 6: 14 7: 12 8: 9 9: 13 10: 11 11: 8 12: 13 .. {{{end}}} .. seealso:: `calendar `_ The standard library documentation for this module. :mod:`time` Lower-level time functions. :mod:`datetime` Manipulate date values, including timestamps and time zones.