1:mod:`calendar` --- General calendar-related functions
2======================================================
3
4.. module:: calendar
5   :synopsis: Functions for working with calendars, including some emulation
6              of the Unix cal program.
7
8.. sectionauthor:: Drew Csillag <drew_csillag@geocities.com>
9
10**Source code:** :source:`Lib/calendar.py`
11
12--------------
13
14This module allows you to output calendars like the Unix :program:`cal` program,
15and provides additional useful functions related to the calendar. By default,
16these calendars have Monday as the first day of the week, and Sunday as the last
17(the European convention). Use :func:`setfirstweekday` to set the first day of
18the week to Sunday (6) or to any other weekday.  Parameters that specify dates
19are given as integers. For related
20functionality, see also the :mod:`datetime` and :mod:`time` modules.
21
22Most of these functions and classes rely on the :mod:`datetime` module which
23uses an idealized calendar, the current Gregorian calendar extended
24in both directions.  This matches the definition of the "proleptic Gregorian"
25calendar in Dershowitz and Reingold's book "Calendrical Calculations", where
26it's the base calendar for all computations.
27
28
29.. class:: Calendar(firstweekday=0)
30
31   Creates a :class:`Calendar` object. *firstweekday* is an integer specifying the
32   first day of the week. ``0`` is Monday (the default), ``6`` is Sunday.
33
34   A :class:`Calendar` object provides several methods that can be used for
35   preparing the calendar data for formatting. This class doesn't do any formatting
36   itself. This is the job of subclasses.
37
38
39   :class:`Calendar` instances have the following methods:
40
41   .. method:: iterweekdays()
42
43      Return an iterator for the week day numbers that will be used for one
44      week.  The first value from the iterator will be the same as the value of
45      the :attr:`firstweekday` property.
46
47
48   .. method:: itermonthdates(year, month)
49
50      Return an iterator for the month *month* (1--12) in the year *year*. This
51      iterator will return all days (as :class:`datetime.date` objects) for the
52      month and all days before the start of the month or after the end of the
53      month that are required to get a complete week.
54
55
56   .. method:: itermonthdays2(year, month)
57
58      Return an iterator for the month *month* in the year *year* similar to
59      :meth:`itermonthdates`. Days returned will be tuples consisting of a day
60      number and a week day number.
61
62
63   .. method:: itermonthdays(year, month)
64
65      Return an iterator for the month *month* in the year *year* similar to
66      :meth:`itermonthdates`. Days returned will simply be day numbers.
67
68
69   .. method:: monthdatescalendar(year, month)
70
71      Return a list of the weeks in the month *month* of the *year* as full
72      weeks.  Weeks are lists of seven :class:`datetime.date` objects.
73
74
75   .. method:: monthdays2calendar(year, month)
76
77      Return a list of the weeks in the month *month* of the *year* as full
78      weeks.  Weeks are lists of seven tuples of day numbers and weekday
79      numbers.
80
81
82   .. method:: monthdayscalendar(year, month)
83
84      Return a list of the weeks in the month *month* of the *year* as full
85      weeks.  Weeks are lists of seven day numbers.
86
87
88   .. method:: yeardatescalendar(year, width=3)
89
90      Return the data for the specified year ready for formatting. The return
91      value is a list of month rows. Each month row contains up to *width*
92      months (defaulting to 3). Each month contains between 4 and 6 weeks and
93      each week contains 1--7 days. Days are :class:`datetime.date` objects.
94
95
96   .. method:: yeardays2calendar(year, width=3)
97
98      Return the data for the specified year ready for formatting (similar to
99      :meth:`yeardatescalendar`). Entries in the week lists are tuples of day
100      numbers and weekday numbers. Day numbers outside this month are zero.
101
102
103   .. method:: yeardayscalendar(year, width=3)
104
105      Return the data for the specified year ready for formatting (similar to
106      :meth:`yeardatescalendar`). Entries in the week lists are day numbers. Day
107      numbers outside this month are zero.
108
109
110.. class:: TextCalendar(firstweekday=0)
111
112   This class can be used to generate plain text calendars.
113
114   :class:`TextCalendar` instances have the following methods:
115
116   .. method:: formatmonth(theyear, themonth, w=0, l=0)
117
118      Return a month's calendar in a multi-line string. If *w* is provided, it
119      specifies the width of the date columns, which are centered. If *l* is
120      given, it specifies the number of lines that each week will use. Depends
121      on the first weekday as specified in the constructor or set by the
122      :meth:`setfirstweekday` method.
123
124
125   .. method:: prmonth(theyear, themonth, w=0, l=0)
126
127      Print a month's calendar as returned by :meth:`formatmonth`.
128
129
130   .. method:: formatyear(theyear, w=2, l=1, c=6, m=3)
131
132      Return a *m*-column calendar for an entire year as a multi-line string.
133      Optional parameters *w*, *l*, and *c* are for date column width, lines per
134      week, and number of spaces between month columns, respectively. Depends on
135      the first weekday as specified in the constructor or set by the
136      :meth:`setfirstweekday` method.  The earliest year for which a calendar
137      can be generated is platform-dependent.
138
139
140   .. method:: pryear(theyear, w=2, l=1, c=6, m=3)
141
142      Print the calendar for an entire year as returned by :meth:`formatyear`.
143
144
145.. class:: HTMLCalendar(firstweekday=0)
146
147   This class can be used to generate HTML calendars.
148
149
150   :class:`HTMLCalendar` instances have the following methods:
151
152   .. method:: formatmonth(theyear, themonth, withyear=True)
153
154      Return a month's calendar as an HTML table. If *withyear* is true the year
155      will be included in the header, otherwise just the month name will be
156      used.
157
158
159   .. method:: formatyear(theyear, width=3)
160
161      Return a year's calendar as an HTML table. *width* (defaulting to 3)
162      specifies the number of months per row.
163
164
165   .. method:: formatyearpage(theyear, width=3, css='calendar.css', encoding=None)
166
167      Return a year's calendar as a complete HTML page. *width* (defaulting to
168      3) specifies the number of months per row. *css* is the name for the
169      cascading style sheet to be used. :const:`None` can be passed if no style
170      sheet should be used. *encoding* specifies the encoding to be used for the
171      output (defaulting to the system default encoding).
172
173
174.. class:: LocaleTextCalendar(firstweekday=0, locale=None)
175
176   This subclass of :class:`TextCalendar` can be passed a locale name in the
177   constructor and will return month and weekday names in the specified locale.
178   If this locale includes an encoding all strings containing month and weekday
179   names will be returned as unicode.
180
181
182.. class:: LocaleHTMLCalendar(firstweekday=0, locale=None)
183
184   This subclass of :class:`HTMLCalendar` can be passed a locale name in the
185   constructor and will return month and weekday names in the specified
186   locale. If this locale includes an encoding all strings containing month and
187   weekday names will be returned as unicode.
188
189.. note::
190
191   The :meth:`formatweekday` and :meth:`formatmonthname` methods of these two
192   classes temporarily change the current locale to the given *locale*.  Because
193   the current locale is a process-wide setting, they are not thread-safe.
194
195
196For simple text calendars this module provides the following functions.
197
198.. function:: setfirstweekday(weekday)
199
200   Sets the weekday (``0`` is Monday, ``6`` is Sunday) to start each week. The
201   values :const:`MONDAY`, :const:`TUESDAY`, :const:`WEDNESDAY`, :const:`THURSDAY`,
202   :const:`FRIDAY`, :const:`SATURDAY`, and :const:`SUNDAY` are provided for
203   convenience. For example, to set the first weekday to Sunday::
204
205      import calendar
206      calendar.setfirstweekday(calendar.SUNDAY)
207
208
209.. function:: firstweekday()
210
211   Returns the current setting for the weekday to start each week.
212
213
214.. function:: isleap(year)
215
216   Returns :const:`True` if *year* is a leap year, otherwise :const:`False`.
217
218
219.. function:: leapdays(y1, y2)
220
221   Returns the number of leap years in the range from *y1* to *y2* (exclusive),
222   where *y1* and *y2* are years.
223
224   This function works for ranges spanning a century change.
225
226
227.. function:: weekday(year, month, day)
228
229   Returns the day of the week (``0`` is Monday) for *year* (``1970``--...),
230   *month* (``1``--``12``), *day* (``1``--``31``).
231
232
233.. function:: weekheader(n)
234
235   Return a header containing abbreviated weekday names. *n* specifies the width in
236   characters for one weekday.
237
238
239.. function:: monthrange(year, month)
240
241   Returns weekday of first day of the month and number of days in month,  for the
242   specified *year* and *month*.
243
244
245.. function:: monthcalendar(year, month)
246
247   Returns a matrix representing a month's calendar.  Each row represents a week;
248   days outside of the month a represented by zeros. Each week begins with Monday
249   unless set by :func:`setfirstweekday`.
250
251
252.. function:: prmonth(theyear, themonth, w=0, l=0)
253
254   Prints a month's calendar as returned by :func:`month`.
255
256
257.. function:: month(theyear, themonth, w=0, l=0)
258
259   Returns a month's calendar in a multi-line string using the :meth:`formatmonth`
260   of the :class:`TextCalendar` class.
261
262
263.. function:: prcal(year, w=0, l=0, c=6, m=3)
264
265   Prints the calendar for an entire year as returned by  :func:`calendar`.
266
267
268.. function:: calendar(year, w=2, l=1, c=6, m=3)
269
270   Returns a 3-column calendar for an entire year as a multi-line string using
271   the :meth:`formatyear` of the :class:`TextCalendar` class.
272
273
274.. function:: timegm(tuple)
275
276   An unrelated but handy function that takes a time tuple such as returned by
277   the :func:`~time.gmtime` function in the :mod:`time` module, and returns the
278   corresponding Unix timestamp value, assuming an epoch of 1970, and the POSIX
279   encoding.  In fact, :func:`time.gmtime` and :func:`timegm` are each others'
280   inverse.
281
282
283The :mod:`calendar` module exports the following data attributes:
284
285.. data:: day_name
286
287   An array that represents the days of the week in the current locale.
288
289
290.. data:: day_abbr
291
292   An array that represents the abbreviated days of the week in the current locale.
293
294
295.. data:: month_name
296
297   An array that represents the months of the year in the current locale.  This
298   follows normal convention of January being month number 1, so it has a length of
299   13 and  ``month_name[0]`` is the empty string.
300
301
302.. data:: month_abbr
303
304   An array that represents the abbreviated months of the year in the current
305   locale.  This follows normal convention of January being month number 1, so it
306   has a length of 13 and  ``month_abbr[0]`` is the empty string.
307
308
309.. seealso::
310
311   Module :mod:`datetime`
312      Object-oriented interface to dates and times with similar functionality to the
313      :mod:`time` module.
314
315   Module :mod:`time`
316      Low-level time related functions.
317