Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{calendar} --- |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 2 | General calendar-related functions} |
| 3 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{calendar} |
Fred Drake | 1a670c8 | 2001-11-06 22:14:35 +0000 | [diff] [blame] | 5 | \modulesynopsis{Functions for working with calendars, |
Fred Drake | c116b82 | 2001-05-09 15:50:17 +0000 | [diff] [blame] | 6 | including some emulation of the \UNIX\ \program{cal} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 7 | program.} |
| 8 | \sectionauthor{Drew Csillag}{drew_csillag@geocities.com} |
Fred Drake | 1c127e7 | 1998-04-28 14:28:57 +0000 | [diff] [blame] | 9 | |
| 10 | This module allows you to output calendars like the \UNIX{} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 11 | \program{cal} program, and provides additional useful functions |
Skip Montanaro | 7b828a6 | 2000-08-30 14:02:25 +0000 | [diff] [blame] | 12 | related to the calendar. By default, these calendars have Monday as |
| 13 | the first day of the week, and Sunday as the last (the European |
| 14 | convention). Use \function{setfirstweekday()} to set the first day of the |
Fred Drake | 1529ef8 | 2001-12-12 05:40:46 +0000 | [diff] [blame] | 15 | week to Sunday (6) or to any other weekday. Parameters that specify |
| 16 | dates are given as integers. |
Skip Montanaro | 7b828a6 | 2000-08-30 14:02:25 +0000 | [diff] [blame] | 17 | |
Raymond Hettinger | e11b510 | 2002-12-25 16:37:19 +0000 | [diff] [blame] | 18 | Most of these functions rely on the \module{datetime} module which |
| 19 | uses an idealized calendar, the current Gregorian calendar indefinitely |
| 20 | extended in both directions. This matches the definition of the |
| 21 | "proleptic Gregorian" calendar in Dershowitz and Reingold's book |
| 22 | "Calendrical Calculations", where it's the base calendar for all |
| 23 | computations. |
Neal Norwitz | 034c749 | 2002-11-03 00:13:42 +0000 | [diff] [blame] | 24 | |
Skip Montanaro | 7b828a6 | 2000-08-30 14:02:25 +0000 | [diff] [blame] | 25 | \begin{funcdesc}{setfirstweekday}{weekday} |
| 26 | Sets the weekday (\code{0} is Monday, \code{6} is Sunday) to start |
| 27 | each week. The values \constant{MONDAY}, \constant{TUESDAY}, |
| 28 | \constant{WEDNESDAY}, \constant{THURSDAY}, \constant{FRIDAY}, |
| 29 | \constant{SATURDAY}, and \constant{SUNDAY} are provided for |
| 30 | convenience. For example, to set the first weekday to Sunday: |
| 31 | |
| 32 | \begin{verbatim} |
| 33 | import calendar |
| 34 | calendar.setfirstweekday(calendar.SUNDAY) |
| 35 | \end{verbatim} |
Fred Drake | e9996c6 | 2002-06-13 01:34:50 +0000 | [diff] [blame] | 36 | \versionadded{2.0} |
Skip Montanaro | 7b828a6 | 2000-08-30 14:02:25 +0000 | [diff] [blame] | 37 | \end{funcdesc} |
| 38 | |
| 39 | \begin{funcdesc}{firstweekday}{} |
| 40 | Returns the current setting for the weekday to start each week. |
Fred Drake | e9996c6 | 2002-06-13 01:34:50 +0000 | [diff] [blame] | 41 | \versionadded{2.0} |
Skip Montanaro | 7b828a6 | 2000-08-30 14:02:25 +0000 | [diff] [blame] | 42 | \end{funcdesc} |
Fred Drake | 1c127e7 | 1998-04-28 14:28:57 +0000 | [diff] [blame] | 43 | |
| 44 | \begin{funcdesc}{isleap}{year} |
Fred Drake | ceb1fd2 | 2003-12-31 04:51:56 +0000 | [diff] [blame] | 45 | Returns \constant{True} if \var{year} is a leap year, otherwise |
| 46 | \constant{False}. |
Fred Drake | 1c127e7 | 1998-04-28 14:28:57 +0000 | [diff] [blame] | 47 | \end{funcdesc} |
| 48 | |
Skip Montanaro | 7b828a6 | 2000-08-30 14:02:25 +0000 | [diff] [blame] | 49 | \begin{funcdesc}{leapdays}{y1, y2} |
| 50 | Returns the number of leap years in the range |
Fred Drake | 1529ef8 | 2001-12-12 05:40:46 +0000 | [diff] [blame] | 51 | [\var{y1}\ldots\var{y2}), where \var{y1} and \var{y2} are years. |
Fred Drake | e9996c6 | 2002-06-13 01:34:50 +0000 | [diff] [blame] | 52 | \versionchanged[This function didn't work for ranges spanning |
| 53 | a century change in Python 1.5.2]{2.0} |
Fred Drake | 1c127e7 | 1998-04-28 14:28:57 +0000 | [diff] [blame] | 54 | \end{funcdesc} |
| 55 | |
| 56 | \begin{funcdesc}{weekday}{year, month, day} |
| 57 | Returns the day of the week (\code{0} is Monday) for \var{year} |
Fred Drake | 02379fa | 1998-05-08 15:39:40 +0000 | [diff] [blame] | 58 | (\code{1970}--\ldots), \var{month} (\code{1}--\code{12}), \var{day} |
Fred Drake | 1c127e7 | 1998-04-28 14:28:57 +0000 | [diff] [blame] | 59 | (\code{1}--\code{31}). |
| 60 | \end{funcdesc} |
| 61 | |
Walter Dörwald | e208412 | 2004-12-06 07:58:14 +0000 | [diff] [blame] | 62 | \begin{funcdesc}{weekheader}{n} |
| 63 | Return a header containing abbreviated weekday names. \var{n} specifies |
| 64 | the width in characters for one weekday. |
| 65 | \end{funcdesc} |
| 66 | |
Fred Drake | 1c127e7 | 1998-04-28 14:28:57 +0000 | [diff] [blame] | 67 | \begin{funcdesc}{monthrange}{year, month} |
| 68 | Returns weekday of first day of the month and number of days in month, |
| 69 | for the specified \var{year} and \var{month}. |
| 70 | \end{funcdesc} |
| 71 | |
| 72 | \begin{funcdesc}{monthcalendar}{year, month} |
| 73 | Returns a matrix representing a month's calendar. Each row represents |
| 74 | a week; days outside of the month a represented by zeros. |
Skip Montanaro | 7b828a6 | 2000-08-30 14:02:25 +0000 | [diff] [blame] | 75 | Each week begins with Monday unless set by \function{setfirstweekday()}. |
Fred Drake | 1c127e7 | 1998-04-28 14:28:57 +0000 | [diff] [blame] | 76 | \end{funcdesc} |
| 77 | |
Skip Montanaro | 7b828a6 | 2000-08-30 14:02:25 +0000 | [diff] [blame] | 78 | \begin{funcdesc}{prmonth}{theyear, themonth\optional{, w\optional{, l}}} |
| 79 | Prints a month's calendar as returned by \function{month()}. |
Fred Drake | 1c127e7 | 1998-04-28 14:28:57 +0000 | [diff] [blame] | 80 | \end{funcdesc} |
| 81 | |
Skip Montanaro | 7b828a6 | 2000-08-30 14:02:25 +0000 | [diff] [blame] | 82 | \begin{funcdesc}{month}{theyear, themonth\optional{, w\optional{, l}}} |
| 83 | Returns a month's calendar in a multi-line string. If \var{w} is |
| 84 | provided, it specifies the width of the date columns, which are |
| 85 | centered. If \var{l} is given, it specifies the number of lines that |
| 86 | each week will use. Depends on the first weekday as set by |
| 87 | \function{setfirstweekday()}. |
Fred Drake | e9996c6 | 2002-06-13 01:34:50 +0000 | [diff] [blame] | 88 | \versionadded{2.0} |
Skip Montanaro | 7b828a6 | 2000-08-30 14:02:25 +0000 | [diff] [blame] | 89 | \end{funcdesc} |
| 90 | |
| 91 | \begin{funcdesc}{prcal}{year\optional{, w\optional{, l\optional{c}}}} |
| 92 | Prints the calendar for an entire year as returned by |
| 93 | \function{calendar()}. |
| 94 | \end{funcdesc} |
| 95 | |
| 96 | \begin{funcdesc}{calendar}{year\optional{, w\optional{, l\optional{c}}}} |
| 97 | Returns a 3-column calendar for an entire year as a multi-line string. |
| 98 | Optional parameters \var{w}, \var{l}, and \var{c} are for date column |
| 99 | width, lines per week, and number of spaces between month columns, |
| 100 | respectively. Depends on the first weekday as set by |
Skip Montanaro | 5ff41d1 | 2001-08-22 12:43:38 +0000 | [diff] [blame] | 101 | \function{setfirstweekday()}. The earliest year for which a calendar can |
| 102 | be generated is platform-dependent. |
Fred Drake | e9996c6 | 2002-06-13 01:34:50 +0000 | [diff] [blame] | 103 | \versionadded{2.0} |
Fred Drake | 1c127e7 | 1998-04-28 14:28:57 +0000 | [diff] [blame] | 104 | \end{funcdesc} |
Guido van Rossum | 4727456 | 1999-06-09 15:11:58 +0000 | [diff] [blame] | 105 | |
| 106 | \begin{funcdesc}{timegm}{tuple} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 107 | An unrelated but handy function that takes a time tuple such as |
| 108 | returned by the \function{gmtime()} function in the \refmodule{time} |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 109 | module, and returns the corresponding \UNIX{} timestamp value, assuming |
Guido van Rossum | 4727456 | 1999-06-09 15:11:58 +0000 | [diff] [blame] | 110 | an epoch of 1970, and the POSIX encoding. In fact, |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 111 | \function{time.gmtime()} and \function{timegm()} are each others' inverse. |
Fred Drake | e9996c6 | 2002-06-13 01:34:50 +0000 | [diff] [blame] | 112 | \versionadded{2.0} |
Guido van Rossum | 4727456 | 1999-06-09 15:11:58 +0000 | [diff] [blame] | 113 | \end{funcdesc} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 114 | |
Skip Montanaro | b80bad4 | 2005-01-05 07:13:32 +0000 | [diff] [blame] | 115 | The \module{calendar} module exports the following data attributes: |
| 116 | |
| 117 | \begin{datadesc}{day_name} |
| 118 | An array that represents the days of the week in the |
| 119 | current locale. |
| 120 | \end{datadesc} |
| 121 | |
| 122 | \begin{datadesc}{day_abbr} |
| 123 | An array that represents the abbreviated days of the week |
| 124 | in the current locale. |
| 125 | \end{datadesc} |
| 126 | |
| 127 | \begin{datadesc}{month_name} |
| 128 | An array that represents the months of the year in the |
| 129 | current locale. This follows normal convention |
| 130 | of January being month number 1, so it has a length of 13 and |
| 131 | \code{month_name[0]} is the empty string. |
| 132 | \end{datadesc} |
| 133 | |
| 134 | \begin{datadesc}{month_abbr} |
| 135 | An array that represents the abbreviated months of the year |
| 136 | in the current locale. This follows normal convention |
| 137 | of January being month number 1, so it has a length of 13 and |
| 138 | \code{month_abbr[0]} is the empty string. |
| 139 | \end{datadesc} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 140 | |
| 141 | \begin{seealso} |
Fred Drake | ceb1fd2 | 2003-12-31 04:51:56 +0000 | [diff] [blame] | 142 | \seemodule{datetime}{Object-oriented interface to dates and times |
| 143 | with similar functionality to the |
| 144 | \refmodule{time} module.} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 145 | \seemodule{time}{Low-level time related functions.} |
| 146 | \end{seealso} |