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