/Doc/library/calendar.rst

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