"calendar" --- 通用日历相关函数
*******************************

**源代码：** Lib/calendar.py

======================================================================

这个模块让你可以输出像 Unix **cal** 那样的日历，它还提供了其它与日历相
关的实用函数。 默认情况下，这些日历把星期一作为一周的第一天，星期天作
为一周的最后一天（这是欧洲惯例）。可以使用 "setfirstweekday()" 方法设
置一周的第一天为星期天 (6) 或者其它任意一天。函数全部接收整数类型的参
数用来指定日期。其它相关功能参见 "datetime" 和 "time" 模块。

在这个模块中定义的函数和类都基于一个理想化的日历——向过去和未来两个方向
无限扩展的现行公历。这与 Dershowitz 和 Reingold 的书“历法计算”中所有计
算的基本日历 "proleptic Gregorian" 历的定义相符。0 和负数年份按照 ISO
8601 标准解释：0 年指公元前 1 年，-1 年指公元前 2 年，依此类推。

class calendar.Calendar(firstweekday=0)

   创建一个 "Calendar" 对象。*firstweekday* 是一个用来指定每星期第一天
   的整数。"MONDAY" 是 "0" （默认值），"SUNDAY" 是 "6"。

   "Calendar" 对象提供了一些可用于对日历数据进行格式化的准备的方法。这
   个类本身不执行任何格式化操作。 这部分任务应由子类来完成。

   "Calendar" 实例具有以下方法和属性：

   firstweekday

      以整数 (0--6) 表示的每星期第一天。

      该特征属性也可分别使用 "setfirstweekday()" 和
      "getfirstweekday()" 来设置和读取。

   getfirstweekday()

      返回一个 "int" 表示当前的每周第一天 (0--6)。

      相当于读取 "firstweekday" 特征属性。

   setfirstweekday(firstweekday)

      Set the first weekday to *firstweekday*, passed as an "int" (0--
      6).

      相当于设置 "firstweekday" 特征属性。

   iterweekdays()

      Return an iterator for the weekday numbers that will be used for
      one week.  The first value from the iterator will be the same as
      the value of the "firstweekday" property.

   itermonthdates(year, month)

      为 *year* 年 *month* 月 (1-12) 返回一个迭代器。这个迭代器返回当
      月的所有日期（使用 "datetime.date" 对象），日期包含了本月头尾用
      于组成完整一周的日期。

   itermonthdays(year, month)

      为 *year* 年 *month* 月返回一个与 "itermonthdates()" 类似的迭代
      器，但不会受 "datetime.date" 范围的限制。返回的日期只是月内日期
      序号。对于不在当月的日期，返回数字 "0"。

   itermonthdays2(year, month)

      Return an iterator for the month *month* in the year *year*
      similar to "itermonthdates()", but not restricted by the
      "datetime.date" range. Days returned will be tuples consisting
      of a day of the month number and a weekday number.

   itermonthdays3(year, month)

      为 *year* 年 *month* 月返回一个与 "itermonthdates()" 类似的迭代
      器，但不会受 "datetime.date" 范围的限制。迭代器的元素为一个由年
      、月、日组成的元组。

      Added in version 3.7.

   itermonthdays4(year, month)

      为 *year* 年 *month* 月返回一个与 "itermonthdates()" 类似的迭代
      器，但不会受 "datetime.date" 范围的限制。迭代器的元素为一个由年
      、月、日和代表星期几的数字组成的元组。

      Added in version 3.7.

   monthdatescalendar(year, month)

      返回 *year* 年 *month* 月的周组成的列表。列表中的每一个周是由七
      个 "datetime.date" 对象组成的列表。

   monthdays2calendar(year, month)

      返回 *year* 年 *month* 月的周组成的列表。列表中的每一个周是七个
      由日数和代表星期几的数字组成的元组的列表。

   monthdayscalendar(year, month)

      返回 *year* 年 *month* 月的周组成的列表。列表中的每一个周是由七
      个日数组成的列表。

   yeardatescalendar(year, width=3)

      返回可以用来格式化的指定年月的数据。返回的值是一个列表，列表是月
      份组成的行。每一行包含了最多 *width* 个月(默认为3)。每个月包含了
      4到6周，每周包含1--7天。每一天使用 "datetime.date" 对象。

   yeardays2calendar(year, width=3)

      返回可以用来格式化的指定年月的数据(与 "yeardatescalendar()" 类似
      )。周列表的元素是由表示日期的数字和表示星期几的数字组成的元组。
      不在这个月的日子为0。

   yeardayscalendar(year, width=3)

      返回可以用来格式化的指定年月的数据(与 "yeardatescalendar()" 类似
      )。周列表的元素是表示日期的数字。不在这个月的日子为0。

class calendar.TextCalendar(firstweekday=0)

   可以使用这个类生成纯文本日历。

   "TextCalendar" 实例有以下方法：

   formatday(theday, weekday, width)

      返回一个代表格式化为指定 *width* 的单独日期的字符串表示形式。 如
      果 *theday* 为 "0"，则返回指定宽度的空格字符串，代表一个空日期。
      *weekday* 形参未被使用。

   formatweek(theweek, w=0)

      返回以不带换行符的字符串表示的单个星期。 如果提供了 *w*，它将指
      定日期列的宽度，日期列将居中对齐。 具体内容还依赖于构造器或
      "setfirstweekday()" 方法指定每周的星期几为第一天。

   formatweekday(weekday, width)

      返回一个代表单个周日期名称的格式化为 *width* 所指定宽度的字符串
      。 *weekday* 形参是表示某个周日期的整数，其中 "0" 为星期一而 "6"
      为星期日。

   formatweekheader(width)

      返回一个包含周日期名称标题行的字符串，其中每一列格式化为 *width*
      所给定的宽度。 这些名称依赖于语言区域设置并将被填充至指定的宽度
      。

   formatmonth(theyear, themonth, w=0, l=0)

      返回指定月的用多行字符串表示的月历。*w* 为日期列的宽度，日期列居
      中打印。*l* 指定了周与周之间的行距。返回的日历还依赖于构造器或者
      "setfirstweekday()" 方法指定的每周的第一天是哪一天。

   formatmonthname(theyear, themonth, width=0, withyear=True)

      返回一个代表月份名称的在以 *width* 指定的宽度内居中的字符串。 如
      果 *withyear* 为 "True"，则会在输出中包括年份。 *theyear* 和
      *themonth* 形参指定年份和月份以便其名称可以相应地被格式化。

   prmonth(theyear, themonth, w=0, l=0)

      调用 "formatmonth()" 方法并打印返回的月历。

   formatyear(theyear, w=2, l=1, c=6, m=3)

      返回指定年的用多行字符串表示的 *m* 列年历。可选参数 *w*、*l* 和
      *c* 分别表示日期列宽，周的行距，和月与月之间的纵向间隔。同样依赖
      于构造器或者 "setfirstweekday()" 方法指定的每周的第一天是哪一天
      。可以生成年历的最早的年是哪一年依赖于使用的平台。

   pryear(theyear, w=2, l=1, c=6, m=3)

      调用 "formatyear()" 方法并打印返回的年历。

class calendar.HTMLCalendar(firstweekday=0)

   可以使用这个类生成 HTML 日历。

   "HTMLCalendar" 实例有以下方法：

   formatmonth(theyear, themonth, withyear=True)

      返回一个 HTML 表格作为指定年月的日历。 *withyear* 为真，则年份将
      会包含在表头，否则只显示月份。

   formatyear(theyear, width=3)

      返回一个 HTML 表格作为指定年份的日历。 *width* (默认为3) 用于规
      定每一行显示月份的数量。

   formatyearpage(theyear, width=3, css='calendar.css', encoding=None)

      Return a year's calendar as a complete HTML page. *width*
      (defaulting to 3) specifies the number of months per row. *css*
      is the name for the cascading style sheet to be used. "None" can
      be passed if no style sheet should be used. *encoding* specifies
      the encoding to be used for the output (defaulting to the system
      default encoding).

   formatmonthname(theyear, themonth, withyear=True)

      将一个月份名称以 HTML 表格行的形式返回。 如果 *withyear* 为真值
      则年份将被包括在行中，否则将只使用月份名称。

   "HTMLCalendar" 有以下属性，你可以重写它们来自定义应用日历的样式。

   cssclasses

      一个对应星期一到星期天的 CSS class 列表。默认列表为

         cssclasses = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]

      可以向每天加入其它样式

         cssclasses = ["mon text-bold", "tue", "wed", "thu", "fri", "sat", "sun red"]

      需要注意的是，列表的长度必须为7。

   cssclass_noday

      出现在上个月或下个月的工作日的 CSS 类。

      Added in version 3.7.

   cssclasses_weekday_head

      用于标题行中的工作日名称的 CSS 类列表。默认值与 "cssclasses" 相
      同。

      Added in version 3.7.

   cssclass_month_head

      月份的头 CSS 类（由 "formatmonthname()" 使用）。默认值为
      ""month"" 。

      Added in version 3.7.

   cssclass_month

      某个月的月历的 CSS 类（由 "formatmonth()" 使用）。默认值为
      ""month"" 。

      Added in version 3.7.

   cssclass_year

      某年的年历的 CSS 类（由 "formatyear()" 使用）。默认值为 ""year""
      。

      Added in version 3.7.

   cssclass_year_head

      年历的表头 CSS 类（由 "formatyear()" 使用）。默认值为 ""year""
      。

      Added in version 3.7.

   需要注意的是，尽管上面命名的样式类都是单独出现的(如：
   "cssclass_month" "cssclass_noday"), 但我们可以使用空格将样式类列表
   中的多个元素分隔开，例如:

      "text-bold text-red"

   下面是一个如何自定义  "HTMLCalendar" 的示例

      class CustomHTMLCal(calendar.HTMLCalendar):
          cssclasses = [style + " text-nowrap" for style in
                        calendar.HTMLCalendar.cssclasses]
          cssclass_month_head = "text-center month-head"
          cssclass_month = "text-center month"
          cssclass_year = "text-italic lead"

class calendar.LocaleTextCalendar(firstweekday=0, locale=None)

   可以向这个 "TextCalendar" 的子类的构造器传入一个语言区域名称并将返
   回指定语言区域下的月份和星期名称。

class calendar.LocaleHTMLCalendar(firstweekday=0, locale=None)

   可以向这个 "HTMLCalendar" 的子类的构造器传入一个语言区域名称并将返
   回指定语言区域下的月份和星期名称。

备注:

  这两个类的构造器、"formatweekday()" 和 "formatmonthname()" 方法会临
  时将 "LC_TIME" 语言区域更改为给定的 *locale*。 因为当前语言区域是进
  程级的设置，所以它们不是线程安全的。

这个模块为简单的文本日历提供了下列函数。

calendar.setfirstweekday(weekday)

   设置每一周的开始 ("0" 表示星期一，"6" 表示星期天)。 提供了 "MONDAY"
   、"TUESDAY"、"WEDNESDAY"、"THURSDAY"、"FRIDAY"、"SATURDAY" 和
   "SUNDAY" 几个常量值作为方便。 例如，设置每周的第一天为星期天:

      import calendar
      calendar.setfirstweekday(calendar.SUNDAY)

calendar.firstweekday()

   返回当前设置的每星期的第一天的数值。

calendar.isleap(year)

   如果 *year* 是闰年则返回  "True" ,否则返回 "False"。

calendar.leapdays(y1, y2)

   返回在范围 *y1* 至 *y2* （不包括 y2）之间的闰年的年数，其中 *y1* 和
   *y2* 是年份。

   此函数对于跨越世纪初的范围也适用。

calendar.weekday(year, month, day)

   返回某年（ "1970" -- ...），某月（ "1" -- "12" ），某日（ "1" --
   "31" ）是星期几（ "0" 是星期一）。

calendar.weekheader(n)

   返回一个包含星期几的缩写名的头。 *n* 指定星期几缩写的字符宽度。

calendar.monthrange(year, month)

   Returns weekday of first day of the month and number of days in
   month, for the specified *year* and *month*.

calendar.monthcalendar(year, month)

   返回表示一个月的日历的矩阵。 每一行代表一周；此月份外的日子由零表示
   。 每周从周一开始，除非使用 "setfirstweekday()" 改变设置。

calendar.prmonth(theyear, themonth, w=0, l=0)

   打印由 "month()" 返回的一个月的日历。

calendar.month(theyear, themonth, w=0, l=0)

   使用 "TextCalendar" 类的 "formatmonth()" 返回多行字符串形式的月份日
   历。

calendar.prcal(year, w=0, l=0, c=6, m=3)

   打印由 "calendar()" 返回的整年的日历。

calendar.calendar(year, w=2, l=1, c=6, m=3)

   使用 "TextCalendar" 类的 "formatyear()" 返回一个整年的 3 列日历。

calendar.timegm(tuple)

   An unrelated but handy function that takes a time tuple such as
   returned by the "gmtime()" function in the "time" module, and
   returns the corresponding Unix timestamp value, assuming an epoch
   of 1970, and the POSIX encoding.  In fact, "time.gmtime()" and
   "timegm()" are each other's inverse.

The "calendar" module exports the following data attributes:

calendar.day_name

   在当前语言区域下表示周内日期的序列，其中“星期一”为 0 号日。

   >>> import calendar
   >>> list(calendar.day_name)
   ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']

calendar.day_abbr

   在当前语言区域下简写表示周内日期的序列，其中“一” 为 0 号日。

   >>> import calendar
   >>> list(calendar.day_abbr)
   ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']

calendar.MONDAY
calendar.TUESDAY
calendar.WEDNESDAY
calendar.THURSDAY
calendar.FRIDAY
calendar.SATURDAY
calendar.SUNDAY

   星期内每日序号的别名，其中 "MONDAY" 是 "0" 而 "SUNDAY" 是 "6"。

   Added in version 3.12.

class calendar.Day

   将星期内的每一天定义为整数常量的枚举。 该枚举的成员以 "MONDAY" 至
   "SUNDAY" 的形式导出到模块作用域。

   Added in version 3.12.

calendar.month_name

   在当前语言区域中表示一年中每个月份的序列。 这遵循一月的月序号为 1
   的通常惯例，所以其长度为 13 且 "month_name[0]" 为空字符串。

   >>> import calendar
   >>> list(calendar.month_name)
   ['', 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']

calendar.month_abbr

   在当前语言区域下简写表示一年中月份的序列。 这遵循一月的月份序号为 1
   的通常惯例，所以其长度为 13 且  "month_abbr[0]" 为空字符串。

   >>> import calendar
   >>> list(calendar.month_abbr)
   ['', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']

calendar.JANUARY
calendar.FEBRUARY
calendar.MARCH
calendar.APRIL
calendar.MAY
calendar.JUNE
calendar.JULY
calendar.AUGUST
calendar.SEPTEMBER
calendar.OCTOBER
calendar.NOVEMBER
calendar.DECEMBER

   一年中各个月份的别名，其中 "JANUARY" 是 "1" 而 "DECEMBER" 是 "12"。

   Added in version 3.12.

class calendar.Month

   将一年中各个月份定义为整数常量的枚举。 该枚举的成员以 "JANUARY" 至
   "DECEMBER" 的形式导出到模块作用域。

   Added in version 3.12.

The "calendar" module defines the following exceptions:

exception calendar.IllegalMonthError(month)

   A subclass of "ValueError" and "IndexError", raised when the given
   month number is outside of the range 1-12 (inclusive).

   在 3.12 版本发生变更: "IllegalMonthError" is now also a subclass of
   "ValueError". New code should avoid catching "IndexError".

   month

      无效的月份数字。

exception calendar.IllegalWeekdayError(weekday)

   "ValueError" 的子类，当给定的星期数字超出 0-6 范围（包含边界值）时
   引发。

   weekday

      无效的星期数字。

参见:

  模块 "datetime"
     为日期和时间提供与 "time" 模块相似功能的面向对象接口。

  模块 "time"
     底层时间相关函数。


命令行用法
==========

Added in version 2.5.

The "calendar" module can be executed as a script from the command
line to interactively print a calendar.

   python -m calendar [-h] [-L LOCALE] [-e ENCODING] [-t {text,html}]
                      [-w WIDTH] [-l LINES] [-s SPACING] [-m MONTHS] [-c CSS]
                      [-f FIRST_WEEKDAY] [year] [month]

例如，打印 2000 年的日历：

   $ python -m calendar 2000
                                     2000

         January                   February                   March
   Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
                   1  2          1  2  3  4  5  6             1  2  3  4  5
    3  4  5  6  7  8  9       7  8  9 10 11 12 13       6  7  8  9 10 11 12
   10 11 12 13 14 15 16      14 15 16 17 18 19 20      13 14 15 16 17 18 19
   17 18 19 20 21 22 23      21 22 23 24 25 26 27      20 21 22 23 24 25 26
   24 25 26 27 28 29 30      28 29                     27 28 29 30 31
   31

          April                      May                       June
   Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
                   1  2       1  2  3  4  5  6  7                1  2  3  4
    3  4  5  6  7  8  9       8  9 10 11 12 13 14       5  6  7  8  9 10 11
   10 11 12 13 14 15 16      15 16 17 18 19 20 21      12 13 14 15 16 17 18
   17 18 19 20 21 22 23      22 23 24 25 26 27 28      19 20 21 22 23 24 25
   24 25 26 27 28 29 30      29 30 31                  26 27 28 29 30

           July                     August                  September
   Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
                   1  2          1  2  3  4  5  6                   1  2  3
    3  4  5  6  7  8  9       7  8  9 10 11 12 13       4  5  6  7  8  9 10
   10 11 12 13 14 15 16      14 15 16 17 18 19 20      11 12 13 14 15 16 17
   17 18 19 20 21 22 23      21 22 23 24 25 26 27      18 19 20 21 22 23 24
   24 25 26 27 28 29 30      28 29 30 31               25 26 27 28 29 30
   31

         October                   November                  December
   Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
                      1             1  2  3  4  5                   1  2  3
    2  3  4  5  6  7  8       6  7  8  9 10 11 12       4  5  6  7  8  9 10
    9 10 11 12 13 14 15      13 14 15 16 17 18 19      11 12 13 14 15 16 17
   16 17 18 19 20 21 22      20 21 22 23 24 25 26      18 19 20 21 22 23 24
   23 24 25 26 27 28 29      27 28 29 30               25 26 27 28 29 30 31
   30 31

可以接受以下选项：

--help, -h

   显示帮助信息并退出。

--locale LOCALE, -L LOCALE

   月份和星期名称所使用的语言区域。 默认为英语。

--encoding ENCODING, -e ENCODING

   输出所使用的编码格式。 如果设置了 "--locale" 则 "--encoding" 将是必
   须的。

--type {text,html}, -t {text,html}

   将日历以文本或 HTML 文档的形式打印到终端。

--first-weekday FIRST_WEEKDAY, -f FIRST_WEEKDAY

   每个星期的开始星期序号。 必须为 0 (星期一) 到 6 (星期日) 之间的数字
   。 默认为 0。

   Added in version 3.13.

year

   要打印日历的年份。 默认为当前年份。

month

   The month of the specified "year" to print the calendar for. Must
   be a number between 1 and 12, and may only be used in text mode.
   Defaults to printing a calendar for the full year.

*文本模式选项:*

--width WIDTH, -w WIDTH

   以终端的列数表示的日期列宽度。 日期将打印在列中央。 小于 2 的值将被
   忽略。 默认为 2。

--lines LINES, -l LINES

   以终端的行数表示的每周的行数。 日期将顶端对齐打印。小于 1 的值将被
   忽略。 默认为 1。

--spacing SPACING, -s SPACING

   列中的月份之间的空格。 小于 2 的值将被忽略。 默认为 6。

--months MONTHS, -m MONTHS

   每行打印的月份数。 默认为 3。

在 3.14 版本发生变更: 在默认情况下，当天的日期将以彩色高亮并可以 使用
环境变量来控制。

*HTML 模式选项:*

--css CSS, -c CSS

   日历要使用的 CSS 样式表的路径。 该路径必须是相对于所生成的 HTML，或
   是一个绝对 HTTP 或 "file:///" URL。
