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
  11 This module allows you to output calendars like the Unix :program:`cal` program,
  12 and provides additional useful functions related to the calendar. By default,
  13 these 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
  15 the week to Sunday (6) or to any other weekday.  Parameters that specify dates
  16 are given as integers. For related
  17 functionality, see also the :mod:`datetime` and :mod:`time` modules.
  18
  19 Most of these functions and classses rely on the :mod:`datetime` module which
  20 uses an idealized calendar, the current Gregorian calendar indefinitely extended
  21 in both directions.  This matches the definition of the "proleptic Gregorian"
  22 calendar in Dershowitz and Reingold's book "Calendrical Calculations", where
  23 it'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
 197 For 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
 295 The :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