rest25/library/calendar.rst => rest262/library/calendar.rst
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
n16-are given as integers.
n16+are given as integers. For related
17+functionality, see also the :mod:`datetime` and :mod:`time` modules.
17
18Most of these functions and classses rely on the :mod:`datetime` module which
19uses an idealized calendar, the current Gregorian calendar indefinitely extended
20in both directions.  This matches the definition of the "proleptic Gregorian"
21calendar in Dershowitz and Reingold's book "Calendrical Calculations", where
22it's the base calendar for all computations.
23
24
28   first day of the week. ``0`` is Monday (the default), ``6`` is Sunday.
29
30   A :class:`Calendar` object provides several methods that can be used for
31   preparing the calendar data for formatting. This class doesn't do any formatting
32   itself. This is the job of subclasses.
33
34   .. versionadded:: 2.5
35
n36-:class:`Calendar` instances have the following methods:
n37+   :class:`Calendar` instances have the following methods:
37
38
n39-.. method:: Calendar.iterweekdays(weekday)
n40+   .. method:: iterweekdays()
40
n41-   Return an iterator for the week day numbers that will be used for one week. The
n42+      Return an iterator for the week day numbers that will be used for one
42-   first number from the iterator will be the same as the number returned by
43+      week.  The first value from the iterator will be the same as the value of
43-   :meth:`firstweekday`.
44+      the :attr:`firstweekday` property.
44
45
n46-.. method:: Calendar.itermonthdates(year, month)
n47+   .. method:: itermonthdates(year, month)
47
n48-   Return an iterator for the month *month* (1-12) in the year *year*. This
n49+      Return an iterator for the month *month* (1-12) in the year *year*. This
49-   iterator will return all days (as :class:`datetime.date` objects) for the month
50+      iterator will return all days (as :class:`datetime.date` objects) for the
50-   and all days before the start of the month or after the end of the month that
51+      month and all days before the start of the month or after the end of the
51-   are required to get a complete week.
52+      month that are required to get a complete week.
52
53
n54-.. method:: Calendar.itermonthdays2(year, month)
n55+   .. method:: itermonthdays2(year, month)
55
n56-   Return an iterator for the month *month* in the year *year* similar to
n57+      Return an iterator for the month *month* in the year *year* similar to
57-   :meth:`itermonthdates`. Days returned will be tuples consisting of a day number
58+      :meth:`itermonthdates`. Days returned will be tuples consisting of a day
58-   and a week day number.
59+      number and a week day number.
59
60
n61-.. method:: Calendar.itermonthdays(year, month)
n62+   .. method:: itermonthdays(year, month)
62
n63-   Return an iterator for the month *month* in the year *year* similar to
n64+      Return an iterator for the month *month* in the year *year* similar to
64-   :meth:`itermonthdates`. Days returned will simply be day numbers.
65+      :meth:`itermonthdates`. Days returned will simply be day numbers.
65
66
n67-.. method:: Calendar.monthdatescalendar(year, month)
n68+   .. method:: monthdatescalendar(year, month)
68
n69-   Return a list of the weeks in the month *month* of the *year* as full weeks.
n70+      Return a list of the weeks in the month *month* of the *year* as full
70-   Weeks are lists of seven :class:`datetime.date` objects.
71+      weeks.  Weeks are lists of seven :class:`datetime.date` objects.
71
72
n73-.. method:: Calendar.monthdays2calendar(year, month)
n74+   .. method:: monthdays2calendar(year, month)
74
n75-   Return a list of the weeks in the month *month* of the *year* as full weeks.
n76+      Return a list of the weeks in the month *month* of the *year* as full
76-   Weeks are lists of seven tuples of day numbers and weekday numbers.
77+      weeks.  Weeks are lists of seven tuples of day numbers and weekday
78+      numbers.
77
78
n79-.. method:: Calendar.monthdayscalendar(year, month)
n81+   .. method:: monthdayscalendar(year, month)
80
n81-   Return a list of the weeks in the month *month* of the *year* as full weeks.
n83+      Return a list of the weeks in the month *month* of the *year* as full
82-   Weeks are lists of seven day numbers.
84+      weeks.  Weeks are lists of seven day numbers.
83
84
n85-.. method:: Calendar.yeardatescalendar(year, month[, width])
n87+   .. method:: yeardatescalendar(year[, width])
86
n87-   Return the data for the specified year ready for formatting. The return value is
n89+      Return the data for the specified year ready for formatting. The return
88-   a list of month rows. Each month row contains up to *width* months (defaulting
90+      value is a list of month rows. Each month row contains up to *width*
89-   to 3). Each month contains between 4 and 6 weeks and each week contains 1--7
91+      months (defaulting to 3). Each month contains between 4 and 6 weeks and
90-   days. Days are :class:`datetime.date` objects.
92+      each week contains 1--7 days. Days are :class:`datetime.date` objects.
91
92
n93-.. method:: Calendar.yeardays2calendar(year, month[, width])
n95+   .. method:: yeardays2calendar(year[, width])
94
n95-   Return the data for the specified year ready for formatting (similar to
n97+      Return the data for the specified year ready for formatting (similar to
96-   :meth:`yeardatescalendar`). Entries in the week lists are tuples of day numbers
98+      :meth:`yeardatescalendar`). Entries in the week lists are tuples of day
97-   and weekday numbers. Day numbers outside this month are zero.
99+      numbers and weekday numbers. Day numbers outside this month are zero.
98
99
n100-.. method:: Calendar.yeardayscalendar(year, month[, width])
n102+   .. method:: yeardayscalendar(year[, width])
101
n102-   Return the data for the specified year ready for formatting (similar to
n104+      Return the data for the specified year ready for formatting (similar to
103-   :meth:`yeardatescalendar`). Entries in the week lists are day numbers. Day
105+      :meth:`yeardatescalendar`). Entries in the week lists are day numbers. Day
104-   numbers outside this month are zero.
106+      numbers outside this month are zero.
105
106
107.. class:: TextCalendar([firstweekday])
108
109   This class can be used to generate plain text calendars.
110
111   .. versionadded:: 2.5
112
n113-:class:`TextCalendar` instances have the following methods:
n115+   :class:`TextCalendar` instances have the following methods:
114
115
n116-.. method:: TextCalendar.formatmonth(theyear, themonth[, w[, l]])
n118+   .. method:: formatmonth(theyear, themonth[, w[, l]])
117
n118-   Return a month's calendar in a multi-line string. If *w* is provided, it
n120+      Return a month's calendar in a multi-line string. If *w* is provided, it
119-   specifies the width of the date columns, which are centered. If *l* is given, it
121+      specifies the width of the date columns, which are centered. If *l* is
120-   specifies the number of lines that each week will use. Depends on the first
122+      given, it specifies the number of lines that each week will use. Depends
121-   weekday as set by :func:`setfirstweekday`.
123+      on the first weekday as specified in the constructor or set by the
124+      :meth:`setfirstweekday` method.
122
123
n124-.. method:: TextCalendar.prmonth(theyear, themonth[, w[, l]])
n127+   .. method:: prmonth(theyear, themonth[, w[, l]])
125
n126-   Print a month's calendar as returned by :meth:`formatmonth`.
n129+      Print a month's calendar as returned by :meth:`formatmonth`.
127
128
n129-.. method:: TextCalendar.formatyear(theyear, themonth[, w[, l[, c[, m]]]])
n132+   .. method:: formatyear(theyear, themonth[, w[, l[, c[, m]]]])
130
n131-   Return a *m*-column calendar for an entire year as a multi-line string. Optional
n134+      Return a *m*-column calendar for an entire year as a multi-line string.
132-   parameters *w*, *l*, and *c* are for date column width, lines per week, and
135+      Optional parameters *w*, *l*, and *c* are for date column width, lines per
133-   number of spaces between month columns, respectively. Depends on the first
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
134-   weekday as set by :meth:`setfirstweekday`.  The earliest year for which a
138+      :meth:`setfirstweekday` method.  The earliest year for which a calendar
135-   calendar can be generated is platform-dependent.
139+      can be generated is platform-dependent.
136
137
n138-.. method:: TextCalendar.pryear(theyear[, w[, l[, c[, m]]]])
n142+   .. method:: pryear(theyear[, w[, l[, c[, m]]]])
139
n140-   Print the calendar for an entire year as returned by :meth:`formatyear`.
n144+      Print the calendar for an entire year as returned by :meth:`formatyear`.
141
142
143.. class:: HTMLCalendar([firstweekday])
144
145   This class can be used to generate HTML calendars.
146
147   .. versionadded:: 2.5
148
n149-:class:`HTMLCalendar` instances have the following methods:
n153+   :class:`HTMLCalendar` instances have the following methods:
150
151
n152-.. method:: HTMLCalendar.formatmonth(theyear, themonth[, withyear])
n156+   .. method:: formatmonth(theyear, themonth[, withyear])
153
n154-   Return a month's calendar as an HTML table. If *withyear* is true the year will
n158+      Return a month's calendar as an HTML table. If *withyear* is true the year
155-   be included in the header, otherwise just the month name will be used.
159+      will be included in the header, otherwise just the month name will be
160+      used.
156
157
n158-.. method:: HTMLCalendar.formatyear(theyear, themonth[, width])
n163+   .. method:: formatyear(theyear, themonth[, width])
159
n160-   Return a year's calendar as an HTML table. *width* (defaulting to 3) specifies
n165+      Return a year's calendar as an HTML table. *width* (defaulting to 3)
161-   the number of months per row.
166+      specifies the number of months per row.
162
163
n164-.. method:: HTMLCalendar.formatyearpage(theyear, themonth[, width[, css[, encoding]]])
n169+   .. method:: formatyearpage(theyear[, width[, css[, encoding]]])
165
n166-   Return a year's calendar as a complete HTML page. *width* (defaulting to 3)
n171+      Return a year's calendar as a complete HTML page. *width* (defaulting to
167-   specifies the number of months per row. *css* is the name for the cascading
172+      3) specifies the number of months per row. *css* is the name for the
168-   style sheet to be used. :const:`None` can be passed if no style sheet should be
173+      cascading style sheet to be used. :const:`None` can be passed if no style
169-   used. *encoding* specifies the encoding to be used for the output (defaulting to
174+      sheet should be used. *encoding* specifies the encoding to be used for the
170-   the system default encoding).
175+      output (defaulting to the system default encoding).
171
172
173.. class:: LocaleTextCalendar([firstweekday[, locale]])
174
175   This subclass of :class:`TextCalendar` can be passed a locale name in the
n176-   constructor and will return month and weekday names in the specified locale. If
n181+   constructor and will return month and weekday names in the specified
177-   this locale includes an encoding all strings containing month and weekday names
182+   locale. If this locale includes an encoding all strings containing month and
178-   will be returned as unicode.
183+   weekday names will be returned as unicode.
179
180   .. versionadded:: 2.5
181
182
183.. class:: LocaleHTMLCalendar([firstweekday[, locale]])
184
185   This subclass of :class:`HTMLCalendar` can be passed a locale name in the
n186-   constructor and will return month and weekday names in the specified locale. If
n191+   constructor and will return month and weekday names in the specified
187-   this locale includes an encoding all strings containing month and weekday names
192+   locale. If this locale includes an encoding all strings containing month and
188-   will be returned as unicode.
193+   weekday names will be returned as unicode.
189
190   .. versionadded:: 2.5
191
192For simple text calendars this module provides the following functions.
193
194
195.. function:: setfirstweekday(weekday)
196
214
215.. function:: isleap(year)
216
217   Returns :const:`True` if *year* is a leap year, otherwise :const:`False`.
218
219
220.. function:: leapdays(y1, y2)
221
n222-   Returns the number of leap years in the range [*y1*...*y2*), where *y1* and *y2*
n227+   Returns the number of leap years in the range from *y1* to *y2* (exclusive),
223-   are years.
228+   where *y1* and *y2* are years.
224
225   .. versionchanged:: 2.0
n226-      This function didn't work for ranges spanning  a century change in Python 1.5.2.
n231+      This function didn't work for ranges spanning a century change in Python
232+      1.5.2.
227
228
229.. function:: weekday(year, month, day)
230
t231-   Returns the day of the week (``0`` is Monday) for *year* (``1970``--...),
t237+   Returns the day of the week (``0`` is Monday) for *year* (``1970``--...),
232-   *month* (``1``--``12``), *day* (``1``--``31``).
238+   *month* (``1``--``12``), *day* (``1``--``31``).
233
234
235.. function:: weekheader(n)
236
237   Return a header containing abbreviated weekday names. *n* specifies the width in
238   characters for one weekday.
239
240
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op