blob: f4952711cb8f592a8f253c85fb0ba9cb7a07668e [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`calendar` --- General calendar-related functions
2======================================================
3
4.. module:: calendar
Georg Brandl0d8f0732009-04-05 22:20:44 +00005 :synopsis: Functions for working with calendars, including some emulation
6 of the Unix cal program.
Georg Brandl116aa622007-08-15 14:28:22 +00007.. sectionauthor:: Drew Csillag <drew_csillag@geocities.com>
8
Raymond Hettinger10480942011-01-10 03:26:08 +00009**Source code:** :source:`Lib/calendar.py`
Georg Brandl116aa622007-08-15 14:28:22 +000010
Raymond Hettinger4f707fd2011-01-10 19:54:11 +000011--------------
12
Georg Brandl116aa622007-08-15 14:28:22 +000013This module allows you to output calendars like the Unix :program:`cal` program,
14and provides additional useful functions related to the calendar. By default,
15these calendars have Monday as the first day of the week, and Sunday as the last
16(the European convention). Use :func:`setfirstweekday` to set the first day of
17the week to Sunday (6) or to any other weekday. Parameters that specify dates
18are given as integers. For related
19functionality, see also the :mod:`datetime` and :mod:`time` modules.
20
Benjamin Petersond7c3ed52010-06-27 22:32:30 +000021Most of these functions and classes rely on the :mod:`datetime` module which
Alexander Belopolskyd4bbab22010-11-22 03:06:56 +000022uses an idealized calendar, the current Gregorian calendar extended
Georg Brandl116aa622007-08-15 14:28:22 +000023in both directions. This matches the definition of the "proleptic Gregorian"
24calendar in Dershowitz and Reingold's book "Calendrical Calculations", where
25it's the base calendar for all computations.
26
27
Georg Brandl0d8f0732009-04-05 22:20:44 +000028.. class:: Calendar(firstweekday=0)
Georg Brandl116aa622007-08-15 14:28:22 +000029
30 Creates a :class:`Calendar` object. *firstweekday* is an integer specifying the
31 first day of the week. ``0`` is Monday (the default), ``6`` is Sunday.
32
33 A :class:`Calendar` object provides several methods that can be used for
34 preparing the calendar data for formatting. This class doesn't do any formatting
35 itself. This is the job of subclasses.
36
Georg Brandl116aa622007-08-15 14:28:22 +000037
Benjamin Petersone41251e2008-04-25 01:59:09 +000038 :class:`Calendar` instances have the following methods:
Georg Brandl116aa622007-08-15 14:28:22 +000039
Alexandre Vassalottibee32532008-05-16 18:15:12 +000040 .. method:: iterweekdays()
Georg Brandl116aa622007-08-15 14:28:22 +000041
Benjamin Petersone41251e2008-04-25 01:59:09 +000042 Return an iterator for the week day numbers that will be used for one
43 week. The first value from the iterator will be the same as the value of
44 the :attr:`firstweekday` property.
Georg Brandl116aa622007-08-15 14:28:22 +000045
46
Benjamin Petersone41251e2008-04-25 01:59:09 +000047 .. method:: itermonthdates(year, month)
Georg Brandl116aa622007-08-15 14:28:22 +000048
Benjamin Petersone41251e2008-04-25 01:59:09 +000049 Return an iterator for the month *month* (1-12) in the year *year*. This
50 iterator will return all days (as :class:`datetime.date` objects) for the
51 month and all days before the start of the month or after the end of the
52 month that are required to get a complete week.
Georg Brandl116aa622007-08-15 14:28:22 +000053
54
Benjamin Petersone41251e2008-04-25 01:59:09 +000055 .. method:: itermonthdays2(year, month)
Georg Brandl116aa622007-08-15 14:28:22 +000056
Benjamin Petersone41251e2008-04-25 01:59:09 +000057 Return an iterator for the month *month* in the year *year* similar to
58 :meth:`itermonthdates`. Days returned will be tuples consisting of a day
59 number and a week day number.
Georg Brandl116aa622007-08-15 14:28:22 +000060
61
Benjamin Petersone41251e2008-04-25 01:59:09 +000062 .. method:: itermonthdays(year, month)
Georg Brandl116aa622007-08-15 14:28:22 +000063
Benjamin Petersone41251e2008-04-25 01:59:09 +000064 Return an iterator for the month *month* in the year *year* similar to
65 :meth:`itermonthdates`. Days returned will simply be day numbers.
Georg Brandl116aa622007-08-15 14:28:22 +000066
67
Benjamin Petersone41251e2008-04-25 01:59:09 +000068 .. method:: monthdatescalendar(year, month)
Georg Brandl116aa622007-08-15 14:28:22 +000069
Benjamin Petersone41251e2008-04-25 01:59:09 +000070 Return a list of the weeks in the month *month* of the *year* as full
71 weeks. Weeks are lists of seven :class:`datetime.date` objects.
Georg Brandl116aa622007-08-15 14:28:22 +000072
73
Benjamin Petersone41251e2008-04-25 01:59:09 +000074 .. method:: monthdays2calendar(year, month)
Georg Brandl116aa622007-08-15 14:28:22 +000075
Benjamin Petersone41251e2008-04-25 01:59:09 +000076 Return a list of the weeks in the month *month* of the *year* as full
77 weeks. Weeks are lists of seven tuples of day numbers and weekday
78 numbers.
Georg Brandl116aa622007-08-15 14:28:22 +000079
80
Benjamin Petersone41251e2008-04-25 01:59:09 +000081 .. method:: monthdayscalendar(year, month)
Georg Brandl116aa622007-08-15 14:28:22 +000082
Benjamin Petersone41251e2008-04-25 01:59:09 +000083 Return a list of the weeks in the month *month* of the *year* as full
84 weeks. Weeks are lists of seven day numbers.
Georg Brandl116aa622007-08-15 14:28:22 +000085
86
Georg Brandl0d8f0732009-04-05 22:20:44 +000087 .. method:: yeardatescalendar(year, width=3)
Georg Brandl116aa622007-08-15 14:28:22 +000088
Benjamin Petersone41251e2008-04-25 01:59:09 +000089 Return the data for the specified year ready for formatting. The return
90 value is a list of month rows. Each month row contains up to *width*
91 months (defaulting to 3). Each month contains between 4 and 6 weeks and
92 each week contains 1--7 days. Days are :class:`datetime.date` objects.
Georg Brandl116aa622007-08-15 14:28:22 +000093
94
Georg Brandl0d8f0732009-04-05 22:20:44 +000095 .. method:: yeardays2calendar(year, width=3)
Georg Brandl116aa622007-08-15 14:28:22 +000096
Benjamin Petersone41251e2008-04-25 01:59:09 +000097 Return the data for the specified year ready for formatting (similar to
98 :meth:`yeardatescalendar`). Entries in the week lists are tuples of day
99 numbers and weekday numbers. Day numbers outside this month are zero.
Georg Brandl116aa622007-08-15 14:28:22 +0000100
101
Georg Brandl0d8f0732009-04-05 22:20:44 +0000102 .. method:: yeardayscalendar(year, width=3)
Georg Brandl116aa622007-08-15 14:28:22 +0000103
Benjamin Petersone41251e2008-04-25 01:59:09 +0000104 Return the data for the specified year ready for formatting (similar to
105 :meth:`yeardatescalendar`). Entries in the week lists are day numbers. Day
106 numbers outside this month are zero.
Georg Brandl116aa622007-08-15 14:28:22 +0000107
108
Georg Brandl0d8f0732009-04-05 22:20:44 +0000109.. class:: TextCalendar(firstweekday=0)
Georg Brandl116aa622007-08-15 14:28:22 +0000110
111 This class can be used to generate plain text calendars.
112
Benjamin Petersone41251e2008-04-25 01:59:09 +0000113 :class:`TextCalendar` instances have the following methods:
Georg Brandl116aa622007-08-15 14:28:22 +0000114
Georg Brandl0d8f0732009-04-05 22:20:44 +0000115 .. method:: formatmonth(theyear, themonth, w=0, l=0)
Georg Brandl116aa622007-08-15 14:28:22 +0000116
Benjamin Petersone41251e2008-04-25 01:59:09 +0000117 Return a month's calendar in a multi-line string. If *w* is provided, it
118 specifies the width of the date columns, which are centered. If *l* is
119 given, it specifies the number of lines that each week will use. Depends
120 on the first weekday as specified in the constructor or set by the
121 :meth:`setfirstweekday` method.
Georg Brandl116aa622007-08-15 14:28:22 +0000122
123
Georg Brandl0d8f0732009-04-05 22:20:44 +0000124 .. method:: prmonth(theyear, themonth, w=0, l=0)
Georg Brandl116aa622007-08-15 14:28:22 +0000125
Benjamin Petersone41251e2008-04-25 01:59:09 +0000126 Print a month's calendar as returned by :meth:`formatmonth`.
Georg Brandl116aa622007-08-15 14:28:22 +0000127
128
Benjamin Peterson20211002009-11-25 18:34:42 +0000129 .. method:: formatyear(theyear, w=2, l=1, c=6, m=3)
Georg Brandl116aa622007-08-15 14:28:22 +0000130
Benjamin Petersone41251e2008-04-25 01:59:09 +0000131 Return a *m*-column calendar for an entire year as a multi-line string.
132 Optional parameters *w*, *l*, and *c* are for date column width, lines per
133 week, and number of spaces between month columns, respectively. Depends on
134 the first weekday as specified in the constructor or set by the
135 :meth:`setfirstweekday` method. The earliest year for which a calendar
136 can be generated is platform-dependent.
Georg Brandl116aa622007-08-15 14:28:22 +0000137
138
Georg Brandl0d8f0732009-04-05 22:20:44 +0000139 .. method:: pryear(theyear, w=2, l=1, c=6, m=3)
Georg Brandl116aa622007-08-15 14:28:22 +0000140
Benjamin Petersone41251e2008-04-25 01:59:09 +0000141 Print the calendar for an entire year as returned by :meth:`formatyear`.
Georg Brandl116aa622007-08-15 14:28:22 +0000142
143
Georg Brandl0d8f0732009-04-05 22:20:44 +0000144.. class:: HTMLCalendar(firstweekday=0)
Georg Brandl116aa622007-08-15 14:28:22 +0000145
146 This class can be used to generate HTML calendars.
147
Georg Brandl116aa622007-08-15 14:28:22 +0000148
Benjamin Petersone41251e2008-04-25 01:59:09 +0000149 :class:`HTMLCalendar` instances have the following methods:
Georg Brandl116aa622007-08-15 14:28:22 +0000150
Georg Brandl0d8f0732009-04-05 22:20:44 +0000151 .. method:: formatmonth(theyear, themonth, withyear=True)
Georg Brandl116aa622007-08-15 14:28:22 +0000152
Benjamin Petersone41251e2008-04-25 01:59:09 +0000153 Return a month's calendar as an HTML table. If *withyear* is true the year
154 will be included in the header, otherwise just the month name will be
155 used.
Georg Brandl116aa622007-08-15 14:28:22 +0000156
157
Benjamin Peterson20211002009-11-25 18:34:42 +0000158 .. method:: formatyear(theyear, width=3)
Georg Brandl116aa622007-08-15 14:28:22 +0000159
Benjamin Petersone41251e2008-04-25 01:59:09 +0000160 Return a year's calendar as an HTML table. *width* (defaulting to 3)
161 specifies the number of months per row.
Georg Brandl116aa622007-08-15 14:28:22 +0000162
163
Georg Brandl0d8f0732009-04-05 22:20:44 +0000164 .. method:: formatyearpage(theyear, width=3, css='calendar.css', encoding=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000165
Benjamin Petersone41251e2008-04-25 01:59:09 +0000166 Return a year's calendar as a complete HTML page. *width* (defaulting to
167 3) specifies the number of months per row. *css* is the name for the
168 cascading style sheet to be used. :const:`None` can be passed if no style
169 sheet should be used. *encoding* specifies the encoding to be used for the
170 output (defaulting to the system default encoding).
Georg Brandl116aa622007-08-15 14:28:22 +0000171
172
Georg Brandl0d8f0732009-04-05 22:20:44 +0000173.. class:: LocaleTextCalendar(firstweekday=0, locale=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000174
175 This subclass of :class:`TextCalendar` can be passed a locale name in the
Georg Brandl7004bd12010-10-19 18:54:25 +0000176 constructor and will return month and weekday names in the specified locale.
177 If this locale includes an encoding all strings containing month and weekday
178 names will be returned as unicode.
Georg Brandl116aa622007-08-15 14:28:22 +0000179
Georg Brandl116aa622007-08-15 14:28:22 +0000180
Georg Brandl0d8f0732009-04-05 22:20:44 +0000181.. class:: LocaleHTMLCalendar(firstweekday=0, locale=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000182
183 This subclass of :class:`HTMLCalendar` can be passed a locale name in the
Benjamin Petersone41251e2008-04-25 01:59:09 +0000184 constructor and will return month and weekday names in the specified
185 locale. If this locale includes an encoding all strings containing month and
186 weekday names will be returned as unicode.
Georg Brandl116aa622007-08-15 14:28:22 +0000187
Georg Brandl7004bd12010-10-19 18:54:25 +0000188.. note::
189
190 The :meth:`formatweekday` and :meth:`formatmonthname` methods of these two
191 classes temporarily change the current locale to the given *locale*. Because
192 the current locale is a process-wide setting, they are not thread-safe.
193
Georg Brandl116aa622007-08-15 14:28:22 +0000194
195For simple text calendars this module provides the following functions.
196
Georg Brandl116aa622007-08-15 14:28:22 +0000197.. function:: setfirstweekday(weekday)
198
199 Sets the weekday (``0`` is Monday, ``6`` is Sunday) to start each week. The
200 values :const:`MONDAY`, :const:`TUESDAY`, :const:`WEDNESDAY`, :const:`THURSDAY`,
201 :const:`FRIDAY`, :const:`SATURDAY`, and :const:`SUNDAY` are provided for
202 convenience. For example, to set the first weekday to Sunday::
203
204 import calendar
205 calendar.setfirstweekday(calendar.SUNDAY)
206
Georg Brandl116aa622007-08-15 14:28:22 +0000207
208.. function:: firstweekday()
209
210 Returns the current setting for the weekday to start each week.
211
Georg Brandl116aa622007-08-15 14:28:22 +0000212
213.. function:: isleap(year)
214
215 Returns :const:`True` if *year* is a leap year, otherwise :const:`False`.
216
217
218.. function:: leapdays(y1, y2)
219
220 Returns the number of leap years in the range from *y1* to *y2* (exclusive),
221 where *y1* and *y2* are years.
222
Georg Brandl55ac8f02007-09-01 13:51:09 +0000223 This function works for ranges spanning a century change.
Georg Brandl116aa622007-08-15 14:28:22 +0000224
225
226.. function:: weekday(year, month, day)
227
228 Returns the day of the week (``0`` is Monday) for *year* (``1970``--...),
229 *month* (``1``--``12``), *day* (``1``--``31``).
230
231
232.. function:: weekheader(n)
233
234 Return a header containing abbreviated weekday names. *n* specifies the width in
235 characters for one weekday.
236
237
238.. function:: monthrange(year, month)
239
240 Returns weekday of first day of the month and number of days in month, for the
241 specified *year* and *month*.
242
243
244.. function:: monthcalendar(year, month)
245
246 Returns a matrix representing a month's calendar. Each row represents a week;
247 days outside of the month a represented by zeros. Each week begins with Monday
248 unless set by :func:`setfirstweekday`.
249
250
Georg Brandl0d8f0732009-04-05 22:20:44 +0000251.. function:: prmonth(theyear, themonth, w=0, l=0)
Georg Brandl116aa622007-08-15 14:28:22 +0000252
253 Prints a month's calendar as returned by :func:`month`.
254
255
Georg Brandl0d8f0732009-04-05 22:20:44 +0000256.. function:: month(theyear, themonth, w=0, l=0)
Georg Brandl116aa622007-08-15 14:28:22 +0000257
258 Returns a month's calendar in a multi-line string using the :meth:`formatmonth`
259 of the :class:`TextCalendar` class.
260
Georg Brandl116aa622007-08-15 14:28:22 +0000261
Georg Brandl0d8f0732009-04-05 22:20:44 +0000262.. function:: prcal(year, w=0, l=0, c=6, m=3)
Georg Brandl116aa622007-08-15 14:28:22 +0000263
264 Prints the calendar for an entire year as returned by :func:`calendar`.
265
266
Georg Brandl0d8f0732009-04-05 22:20:44 +0000267.. function:: calendar(year, w=2, l=1, c=6, m=3)
Georg Brandl116aa622007-08-15 14:28:22 +0000268
Georg Brandl0d8f0732009-04-05 22:20:44 +0000269 Returns a 3-column calendar for an entire year as a multi-line string using
270 the :meth:`formatyear` of the :class:`TextCalendar` class.
Georg Brandl116aa622007-08-15 14:28:22 +0000271
Georg Brandl116aa622007-08-15 14:28:22 +0000272
273.. function:: timegm(tuple)
274
275 An unrelated but handy function that takes a time tuple such as returned by the
276 :func:`gmtime` function in the :mod:`time` module, and returns the corresponding
277 Unix timestamp value, assuming an epoch of 1970, and the POSIX encoding. In
278 fact, :func:`time.gmtime` and :func:`timegm` are each others' inverse.
279
Georg Brandl116aa622007-08-15 14:28:22 +0000280
281The :mod:`calendar` module exports the following data attributes:
282
Georg Brandl116aa622007-08-15 14:28:22 +0000283.. data:: day_name
284
285 An array that represents the days of the week in the current locale.
286
287
288.. data:: day_abbr
289
290 An array that represents the abbreviated days of the week in the current locale.
291
292
293.. data:: month_name
294
295 An array that represents the months of the year in the current locale. This
296 follows normal convention of January being month number 1, so it has a length of
297 13 and ``month_name[0]`` is the empty string.
298
299
300.. data:: month_abbr
301
302 An array that represents the abbreviated months of the year in the current
303 locale. This follows normal convention of January being month number 1, so it
304 has a length of 13 and ``month_abbr[0]`` is the empty string.
305
306
307.. seealso::
308
309 Module :mod:`datetime`
310 Object-oriented interface to dates and times with similar functionality to the
311 :mod:`time` module.
312
313 Module :mod:`time`
314 Low-level time related functions.