1:mod:`calendar` --- General calendar-related functions 2====================================================== 3 4.. module:: calendar 5 :synopsis: Functions for working with calendars, including some emulation 6 of the Unix cal program. 7 8.. sectionauthor:: Drew Csillag <drew_csillag@geocities.com> 9 10**Source code:** :source:`Lib/calendar.py` 11 12-------------- 13 14This module allows you to output calendars like the Unix :program:`cal` program, 15and provides additional useful functions related to the calendar. By default, 16these calendars have Monday as the first day of the week, and Sunday as the last 17(the European convention). Use :func:`setfirstweekday` to set the first day of 18the week to Sunday (6) or to any other weekday. Parameters that specify dates 19are given as integers. For related 20functionality, see also the :mod:`datetime` and :mod:`time` modules. 21 22The functions and classes defined in this module 23use an idealized calendar, the current Gregorian calendar extended indefinitely 24in both directions. This matches the definition of the "proleptic Gregorian" 25calendar in Dershowitz and Reingold's book "Calendrical Calculations", where 26it's the base calendar for all computations. Zero and negative years are 27interpreted as prescribed by the ISO 8601 standard. Year 0 is 1 BC, year -1 is 282 BC, and so on. 29 30 31.. class:: Calendar(firstweekday=0) 32 33 Creates a :class:`Calendar` object. *firstweekday* is an integer specifying the 34 first day of the week. ``0`` is Monday (the default), ``6`` is Sunday. 35 36 A :class:`Calendar` object provides several methods that can be used for 37 preparing the calendar data for formatting. This class doesn't do any formatting 38 itself. This is the job of subclasses. 39 40 41 :class:`Calendar` instances have the following methods: 42 43 .. method:: iterweekdays() 44 45 Return an iterator for the week day numbers that will be used for one 46 week. The first value from the iterator will be the same as the value of 47 the :attr:`firstweekday` property. 48 49 50 .. method:: itermonthdates(year, month) 51 52 Return an iterator for the month *month* (1--12) in the year *year*. This 53 iterator will return all days (as :class:`datetime.date` objects) for the 54 month and all days before the start of the month or after the end of the 55 month that are required to get a complete week. 56 57 58 .. method:: itermonthdays(year, month) 59 60 Return an iterator for the month *month* in the year *year* similar to 61 :meth:`itermonthdates`, but not restricted by the :class:`datetime.date` 62 range. Days returned will simply be day of the month numbers. For the 63 days outside of the specified month, the day number is ``0``. 64 65 66 .. method:: itermonthdays2(year, month) 67 68 Return an iterator for the month *month* in the year *year* similar to 69 :meth:`itermonthdates`, but not restricted by the :class:`datetime.date` 70 range. Days returned will be tuples consisting of a day of the month 71 number and a week day number. 72 73 74 .. method:: itermonthdays3(year, month) 75 76 Return an iterator for the month *month* in the year *year* similar to 77 :meth:`itermonthdates`, but not restricted by the :class:`datetime.date` 78 range. Days returned will be tuples consisting of a year, a month and a day 79 of the month numbers. 80 81 .. versionadded:: 3.7 82 83 84 .. method:: itermonthdays4(year, month) 85 86 Return an iterator for the month *month* in the year *year* similar to 87 :meth:`itermonthdates`, but not restricted by the :class:`datetime.date` 88 range. Days returned will be tuples consisting of a year, a month, a day 89 of the month, and a day of the week numbers. 90 91 .. versionadded:: 3.7 92 93 94 .. method:: monthdatescalendar(year, month) 95 96 Return a list of the weeks in the month *month* of the *year* as full 97 weeks. Weeks are lists of seven :class:`datetime.date` objects. 98 99 100 .. method:: monthdays2calendar(year, month) 101 102 Return a list of the weeks in the month *month* of the *year* as full 103 weeks. Weeks are lists of seven tuples of day numbers and weekday 104 numbers. 105 106 107 .. method:: monthdayscalendar(year, month) 108 109 Return a list of the weeks in the month *month* of the *year* as full 110 weeks. Weeks are lists of seven day numbers. 111 112 113 .. method:: yeardatescalendar(year, width=3) 114 115 Return the data for the specified year ready for formatting. The return 116 value is a list of month rows. Each month row contains up to *width* 117 months (defaulting to 3). Each month contains between 4 and 6 weeks and 118 each week contains 1--7 days. Days are :class:`datetime.date` objects. 119 120 121 .. method:: yeardays2calendar(year, width=3) 122 123 Return the data for the specified year ready for formatting (similar to 124 :meth:`yeardatescalendar`). Entries in the week lists are tuples of day 125 numbers and weekday numbers. Day numbers outside this month are zero. 126 127 128 .. method:: yeardayscalendar(year, width=3) 129 130 Return the data for the specified year ready for formatting (similar to 131 :meth:`yeardatescalendar`). Entries in the week lists are day numbers. Day 132 numbers outside this month are zero. 133 134 135.. class:: TextCalendar(firstweekday=0) 136 137 This class can be used to generate plain text calendars. 138 139 :class:`TextCalendar` instances have the following methods: 140 141 .. method:: formatmonth(theyear, themonth, w=0, l=0) 142 143 Return a month's calendar in a multi-line string. If *w* is provided, it 144 specifies the width of the date columns, which are centered. If *l* is 145 given, it specifies the number of lines that each week will use. Depends 146 on the first weekday as specified in the constructor or set by the 147 :meth:`setfirstweekday` method. 148 149 150 .. method:: prmonth(theyear, themonth, w=0, l=0) 151 152 Print a month's calendar as returned by :meth:`formatmonth`. 153 154 155 .. method:: formatyear(theyear, w=2, l=1, c=6, m=3) 156 157 Return a *m*-column calendar for an entire year as a multi-line string. 158 Optional parameters *w*, *l*, and *c* are for date column width, lines per 159 week, and number of spaces between month columns, respectively. Depends on 160 the first weekday as specified in the constructor or set by the 161 :meth:`setfirstweekday` method. The earliest year for which a calendar 162 can be generated is platform-dependent. 163 164 165 .. method:: pryear(theyear, w=2, l=1, c=6, m=3) 166 167 Print the calendar for an entire year as returned by :meth:`formatyear`. 168 169 170.. class:: HTMLCalendar(firstweekday=0) 171 172 This class can be used to generate HTML calendars. 173 174 175 :class:`!HTMLCalendar` instances have the following methods: 176 177 .. method:: formatmonth(theyear, themonth, withyear=True) 178 179 Return a month's calendar as an HTML table. If *withyear* is true the year 180 will be included in the header, otherwise just the month name will be 181 used. 182 183 184 .. method:: formatyear(theyear, width=3) 185 186 Return a year's calendar as an HTML table. *width* (defaulting to 3) 187 specifies the number of months per row. 188 189 190 .. method:: formatyearpage(theyear, width=3, css='calendar.css', encoding=None) 191 192 Return a year's calendar as a complete HTML page. *width* (defaulting to 193 3) specifies the number of months per row. *css* is the name for the 194 cascading style sheet to be used. :const:`None` can be passed if no style 195 sheet should be used. *encoding* specifies the encoding to be used for the 196 output (defaulting to the system default encoding). 197 198 199 :class:`!HTMLCalendar` has the following attributes you can override to 200 customize the CSS classes used by the calendar: 201 202 .. attribute:: cssclasses 203 204 A list of CSS classes used for each weekday. The default class list is:: 205 206 cssclasses = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] 207 208 more styles can be added for each day:: 209 210 cssclasses = ["mon text-bold", "tue", "wed", "thu", "fri", "sat", "sun red"] 211 212 Note that the length of this list must be seven items. 213 214 215 .. attribute:: cssclass_noday 216 217 The CSS class for a weekday occurring in the previous or coming month. 218 219 .. versionadded:: 3.7 220 221 222 .. attribute:: cssclasses_weekday_head 223 224 A list of CSS classes used for weekday names in the header row. 225 The default is the same as :attr:`cssclasses`. 226 227 .. versionadded:: 3.7 228 229 230 .. attribute:: cssclass_month_head 231 232 The month's head CSS class (used by :meth:`formatmonthname`). 233 The default value is ``"month"``. 234 235 .. versionadded:: 3.7 236 237 238 .. attribute:: cssclass_month 239 240 The CSS class for the whole month's table (used by :meth:`formatmonth`). 241 The default value is ``"month"``. 242 243 .. versionadded:: 3.7 244 245 246 .. attribute:: cssclass_year 247 248 The CSS class for the whole year's table of tables (used by 249 :meth:`formatyear`). The default value is ``"year"``. 250 251 .. versionadded:: 3.7 252 253 254 .. attribute:: cssclass_year_head 255 256 The CSS class for the table head for the whole year (used by 257 :meth:`formatyear`). The default value is ``"year"``. 258 259 .. versionadded:: 3.7 260 261 262 Note that although the naming for the above described class attributes is 263 singular (e.g. ``cssclass_month`` ``cssclass_noday``), one can replace the 264 single CSS class with a space separated list of CSS classes, for example:: 265 266 "text-bold text-red" 267 268 Here is an example how :class:`!HTMLCalendar` can be customized:: 269 270 class CustomHTMLCal(calendar.HTMLCalendar): 271 cssclasses = [style + " text-nowrap" for style in 272 calendar.HTMLCalendar.cssclasses] 273 cssclass_month_head = "text-center month-head" 274 cssclass_month = "text-center month" 275 cssclass_year = "text-italic lead" 276 277 278.. class:: LocaleTextCalendar(firstweekday=0, locale=None) 279 280 This subclass of :class:`TextCalendar` can be passed a locale name in the 281 constructor and will return month and weekday names in the specified locale. 282 If this locale includes an encoding all strings containing month and weekday 283 names will be returned as unicode. 284 285 286.. class:: LocaleHTMLCalendar(firstweekday=0, locale=None) 287 288 This subclass of :class:`HTMLCalendar` can be passed a locale name in the 289 constructor and will return month and weekday names in the specified 290 locale. If this locale includes an encoding all strings containing month and 291 weekday names will be returned as unicode. 292 293.. note:: 294 295 The :meth:`formatweekday` and :meth:`formatmonthname` methods of these two 296 classes temporarily change the current locale to the given *locale*. Because 297 the current locale is a process-wide setting, they are not thread-safe. 298 299 300For simple text calendars this module provides the following functions. 301 302.. function:: setfirstweekday(weekday) 303 304 Sets the weekday (``0`` is Monday, ``6`` is Sunday) to start each week. The 305 values :const:`MONDAY`, :const:`TUESDAY`, :const:`WEDNESDAY`, :const:`THURSDAY`, 306 :const:`FRIDAY`, :const:`SATURDAY`, and :const:`SUNDAY` are provided for 307 convenience. For example, to set the first weekday to Sunday:: 308 309 import calendar 310 calendar.setfirstweekday(calendar.SUNDAY) 311 312 313.. function:: firstweekday() 314 315 Returns the current setting for the weekday to start each week. 316 317 318.. function:: isleap(year) 319 320 Returns :const:`True` if *year* is a leap year, otherwise :const:`False`. 321 322 323.. function:: leapdays(y1, y2) 324 325 Returns the number of leap years in the range from *y1* to *y2* (exclusive), 326 where *y1* and *y2* are years. 327 328 This function works for ranges spanning a century change. 329 330 331.. function:: weekday(year, month, day) 332 333 Returns the day of the week (``0`` is Monday) for *year* (``1970``--...), 334 *month* (``1``--``12``), *day* (``1``--``31``). 335 336 337.. function:: weekheader(n) 338 339 Return a header containing abbreviated weekday names. *n* specifies the width in 340 characters for one weekday. 341 342 343.. function:: monthrange(year, month) 344 345 Returns weekday of first day of the month and number of days in month, for the 346 specified *year* and *month*. 347 348 349.. function:: monthcalendar(year, month) 350 351 Returns a matrix representing a month's calendar. Each row represents a week; 352 days outside of the month are represented by zeros. Each week begins with Monday 353 unless set by :func:`setfirstweekday`. 354 355 356.. function:: prmonth(theyear, themonth, w=0, l=0) 357 358 Prints a month's calendar as returned by :func:`month`. 359 360 361.. function:: month(theyear, themonth, w=0, l=0) 362 363 Returns a month's calendar in a multi-line string using the :meth:`formatmonth` 364 of the :class:`TextCalendar` class. 365 366 367.. function:: prcal(year, w=0, l=0, c=6, m=3) 368 369 Prints the calendar for an entire year as returned by :func:`calendar`. 370 371 372.. function:: calendar(year, w=2, l=1, c=6, m=3) 373 374 Returns a 3-column calendar for an entire year as a multi-line string using 375 the :meth:`formatyear` of the :class:`TextCalendar` class. 376 377 378.. function:: timegm(tuple) 379 380 An unrelated but handy function that takes a time tuple such as returned by 381 the :func:`~time.gmtime` function in the :mod:`time` module, and returns the 382 corresponding Unix timestamp value, assuming an epoch of 1970, and the POSIX 383 encoding. In fact, :func:`time.gmtime` and :func:`timegm` are each others' 384 inverse. 385 386 387The :mod:`calendar` module exports the following data attributes: 388 389.. data:: day_name 390 391 An array that represents the days of the week in the current locale. 392 393 394.. data:: day_abbr 395 396 An array that represents the abbreviated days of the week in the current locale. 397 398 399.. data:: month_name 400 401 An array that represents the months of the year in the current locale. This 402 follows normal convention of January being month number 1, so it has a length of 403 13 and ``month_name[0]`` is the empty string. 404 405 406.. data:: month_abbr 407 408 An array that represents the abbreviated months of the year in the current 409 locale. This follows normal convention of January being month number 1, so it 410 has a length of 13 and ``month_abbr[0]`` is the empty string. 411 412 413.. seealso:: 414 415 Module :mod:`datetime` 416 Object-oriented interface to dates and times with similar functionality to the 417 :mod:`time` module. 418 419 Module :mod:`time` 420 Low-level time related functions. 421