| \section{\module{calendar} --- |
| General calendar-related functions} |
| |
| \declaremodule{standard}{calendar} |
| \modulesynopsis{Functions for working with calendars, |
| including some emulation of the \UNIX\ \program{cal} |
| program.} |
| \sectionauthor{Drew Csillag}{drew_csillag@geocities.com} |
| |
| This module allows you to output calendars like the \UNIX{} |
| \program{cal} program, and provides additional useful functions |
| related to the calendar. By default, these calendars have Monday as |
| the first day of the week, and Sunday as the last (the European |
| convention). Use \function{setfirstweekday()} to set the first day of the |
| week to Sunday (6) or to any other weekday. Parameters that specify |
| dates are given as integers. |
| |
| Most of these functions and classses rely on the \module{datetime} |
| module which uses an idealized calendar, the current Gregorian |
| calendar indefinitely extended in both directions. This matches |
| the definition of the "proleptic Gregorian" calendar in Dershowitz |
| and Reingold's book "Calendrical Calculations", where it's the |
| base calendar for all computations. |
| |
| \begin{classdesc}{Calendar}{\optional{firstweekday}} |
| Creates a \class{Calendar} object. \var{firstweekday} is an integer |
| specifying the first day of the week. \code{0} is Monday (the default), |
| \code{6} is Sunday. |
| |
| A \class{Calendar} object provides several methods that can |
| be used for preparing the calendar data for formatting. This |
| class doesn't do any formatting itself. This is the job of |
| subclasses. |
| \versionadded{2.5} |
| \end{classdesc} |
| |
| \class{Calendar} instances have the following methods: |
| |
| \begin{methoddesc}{iterweekdays}{weekday} |
| Return an iterator for the week day numbers that will be used |
| for one week. The first number from the iterator will be the |
| same as the number returned by \method{firstweekday()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{itermonthdates}{year, month} |
| Return an iterator for the month \var{month} (1-12) in the |
| year \var{year}. This iterator will return all days (as |
| \class{datetime.date} objects) for the month and all days |
| before the start of the month or after the end of the month |
| that are required to get a complete week. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{itermonthdays2}{year, month} |
| Return an iterator for the month \var{month} in the year |
| \var{year} similar to \method{itermonthdates()}. Days returned |
| will be tuples consisting of a day number and a week day |
| number. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{itermonthdays}{year, month} |
| Return an iterator for the month \var{month} in the year |
| \var{year} similar to \method{itermonthdates()}. Days returned |
| will simply be day numbers. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{monthdatescalendar}{year, month} |
| Return a list of the weeks in the month \var{month} of |
| the \var{year} as full weeks. Weeks are lists of seven |
| \class{datetime.date} objects. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{monthdays2calendar}{year, month} |
| Return a list of the weeks in the month \var{month} of |
| the \var{year} as full weeks. Weeks are lists of seven |
| tuples of day numbers and weekday numbers. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{monthdayscalendar}{year, month} |
| Return a list of the weeks in the month \var{month} of |
| the \var{year} as full weeks. Weeks are lists of seven |
| day numbers. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{yeardatescalendar}{year, month\optional{, width}} |
| Return the data for the specified year ready for formatting. The return |
| value is a list of month rows. Each month row contains up to \var{width} |
| months (defaulting to 3). Each month contains between 4 and 6 weeks and |
| each week contains 1--7 days. Days are \class{datetime.date} objects. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{yeardays2calendar}{year, month\optional{, width}} |
| Return the data for the specified year ready for formatting (similar to |
| \method{yeardatescalendar()}). Entries in the week lists are tuples of |
| day numbers and weekday numbers. Day numbers outside this month are zero. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{yeardayscalendar}{year, month\optional{, width}} |
| Return the data for the specified year ready for formatting (similar to |
| \method{yeardatescalendar()}). Entries in the week lists are day numbers. |
| Day numbers outside this month are zero. |
| \end{methoddesc} |
| |
| |
| \begin{classdesc}{TextCalendar}{\optional{firstweekday}} |
| This class can be used to generate plain text calendars. |
| |
| \versionadded{2.5} |
| \end{classdesc} |
| |
| \class{TextCalendar} instances have the following methods: |
| |
| \begin{methoddesc}{formatmonth}{theyear, themonth\optional{, w\optional{, l}}} |
| Return a month's calendar in a multi-line string. If \var{w} is |
| provided, it specifies the width of the date columns, which are |
| centered. If \var{l} is given, it specifies the number of lines that |
| each week will use. Depends on the first weekday as set by |
| \function{setfirstweekday()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{prmonth}{theyear, themonth\optional{, w\optional{, l}}} |
| Print a month's calendar as returned by \method{formatmonth()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{formatyear}{theyear, themonth\optional{, w\optional{, |
| l\optional{, c\optional{, m}}}}} |
| Return a \var{m}-column calendar for an entire year as a multi-line string. |
| Optional parameters \var{w}, \var{l}, and \var{c} are for date column |
| width, lines per week, and number of spaces between month columns, |
| respectively. Depends on the first weekday as set by |
| \method{setfirstweekday()}. The earliest year for which a calendar can |
| be generated is platform-dependent. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{pryear}{theyear\optional{, w\optional{, l\optional{, |
| c\optional{, m}}}}} |
| Print the calendar for an entire year as returned by \method{formatyear()}. |
| \end{methoddesc} |
| |
| |
| \begin{classdesc}{HTMLCalendar}{\optional{firstweekday}} |
| This class can be used to generate HTML calendars. |
| |
| \versionadded{2.5} |
| \end{classdesc} |
| |
| \class{HTMLCalendar} instances have the following methods: |
| |
| \begin{methoddesc}{formatmonth}{theyear, themonth\optional{, withyear}} |
| Return a month's calendar as an HTML table. If \var{withyear} is |
| true the year will be included in the header, otherwise just the |
| month name will be used. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{formatyear}{theyear, themonth\optional{, width}} |
| Return a year's calendar as an HTML table. \var{width} (defaulting to 3) |
| specifies the number of months per row. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{formatyearpage}{theyear, themonth\optional{, |
| width\optional{, css\optional{, encoding}}}} |
| Return a year's calendar as a complete HTML page. \var{width} |
| (defaulting to 3) specifies the number of months per row. \var{css} |
| is the name for the cascading style sheet to be used. \constant{None} |
| can be passed if no style sheet should be used. \var{encoding} |
| specifies the encoding to be used for the output (defaulting |
| to the system default encoding). |
| \end{methoddesc} |
| |
| |
| \begin{classdesc}{LocaleTextCalendar}{\optional{firstweekday\optional{, locale}}} |
| This subclass of \class{TextCalendar} can be passed a locale name in the |
| constructor and will return month and weekday names in the specified locale. |
| If this locale includes an encoding all strings containing month and weekday |
| names will be returned as unicode. |
| \versionadded{2.5} |
| \end{classdesc} |
| |
| |
| \begin{classdesc}{LocaleHTMLCalendar}{\optional{firstweekday\optional{, locale}}} |
| This subclass of \class{HTMLCalendar} can be passed a locale name in the |
| constructor and will return month and weekday names in the specified locale. |
| If this locale includes an encoding all strings containing month and weekday |
| names will be returned as unicode. |
| \versionadded{2.5} |
| \end{classdesc} |
| |
| |
| For simple text calendars this module provides the following functions. |
| |
| \begin{funcdesc}{setfirstweekday}{weekday} |
| Sets the weekday (\code{0} is Monday, \code{6} is Sunday) to start |
| each week. The values \constant{MONDAY}, \constant{TUESDAY}, |
| \constant{WEDNESDAY}, \constant{THURSDAY}, \constant{FRIDAY}, |
| \constant{SATURDAY}, and \constant{SUNDAY} are provided for |
| convenience. For example, to set the first weekday to Sunday: |
| |
| \begin{verbatim} |
| import calendar |
| calendar.setfirstweekday(calendar.SUNDAY) |
| \end{verbatim} |
| \versionadded{2.0} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{firstweekday}{} |
| Returns the current setting for the weekday to start each week. |
| \versionadded{2.0} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{isleap}{year} |
| Returns \constant{True} if \var{year} is a leap year, otherwise |
| \constant{False}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{leapdays}{y1, y2} |
| Returns the number of leap years in the range |
| [\var{y1}\ldots\var{y2}), where \var{y1} and \var{y2} are years. |
| \versionchanged[This function didn't work for ranges spanning |
| a century change in Python 1.5.2]{2.0} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{weekday}{year, month, day} |
| Returns the day of the week (\code{0} is Monday) for \var{year} |
| (\code{1970}--\ldots), \var{month} (\code{1}--\code{12}), \var{day} |
| (\code{1}--\code{31}). |
| \end{funcdesc} |
| |
| \begin{funcdesc}{weekheader}{n} |
| Return a header containing abbreviated weekday names. \var{n} specifies |
| the width in characters for one weekday. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{monthrange}{year, month} |
| Returns weekday of first day of the month and number of days in month, |
| for the specified \var{year} and \var{month}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{monthcalendar}{year, month} |
| Returns a matrix representing a month's calendar. Each row represents |
| a week; days outside of the month a represented by zeros. |
| Each week begins with Monday unless set by \function{setfirstweekday()}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{prmonth}{theyear, themonth\optional{, w\optional{, l}}} |
| Prints a month's calendar as returned by \function{month()}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{month}{theyear, themonth\optional{, w\optional{, l}}} |
| Returns a month's calendar in a multi-line string using the |
| \method{formatmonth} of the \class{TextCalendar} class. |
| \versionadded{2.0} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{prcal}{year\optional{, w\optional{, l\optional{c}}}} |
| Prints the calendar for an entire year as returned by |
| \function{calendar()}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{calendar}{year\optional{, w\optional{, l\optional{c}}}} |
| Returns a 3-column calendar for an entire year as a multi-line string |
| using the \method{formatyear} of the \class{TextCalendar} class. |
| \versionadded{2.0} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{timegm}{tuple} |
| An unrelated but handy function that takes a time tuple such as |
| returned by the \function{gmtime()} function in the \refmodule{time} |
| module, and returns the corresponding \UNIX{} timestamp value, assuming |
| an epoch of 1970, and the POSIX encoding. In fact, |
| \function{time.gmtime()} and \function{timegm()} are each others' inverse. |
| \versionadded{2.0} |
| \end{funcdesc} |
| |
| The \module{calendar} module exports the following data attributes: |
| |
| \begin{datadesc}{day_name} |
| An array that represents the days of the week in the |
| current locale. |
| \end{datadesc} |
| |
| \begin{datadesc}{day_abbr} |
| An array that represents the abbreviated days of the week |
| in the current locale. |
| \end{datadesc} |
| |
| \begin{datadesc}{month_name} |
| An array that represents the months of the year in the |
| current locale. This follows normal convention |
| of January being month number 1, so it has a length of 13 and |
| \code{month_name[0]} is the empty string. |
| \end{datadesc} |
| |
| \begin{datadesc}{month_abbr} |
| An array that represents the abbreviated months of the year |
| in the current locale. This follows normal convention |
| of January being month number 1, so it has a length of 13 and |
| \code{month_abbr[0]} is the empty string. |
| \end{datadesc} |
| |
| \begin{seealso} |
| \seemodule{datetime}{Object-oriented interface to dates and times |
| with similar functionality to the |
| \refmodule{time} module.} |
| \seemodule{time}{Low-level time related functions.} |
| \end{seealso} |