"calendar" --- 一般的なカレンダーに関係する機能群
*************************************************

**ソースコード:** Lib/calendar.py

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

このモジュールは Unix の **cal** プログラムのようなカレンダー出力を行
い、それに加えてカレンダーに関する有益な関数群を提供します。標準ではこ
れらのカレンダーは（ヨーロッパの慣例に従って）月曜日を週の始まりとし、
日曜日を最後の日としています。 "setfirstweekday()" を用いることで、日
曜日(6)や他の曜日を週の始まりに設定することができます。日付を表す引数
は整数値で与えます。関連する機能として、 "datetime" と "time" モジュー
ルも参照してください。

このモジュールに定義された関数やクラスは理想化されたカレンダー、つまり
現在のグレゴリオ暦を過去と未来両方に無限に拡張したものを使っています。
これはすべての計算の基礎のカレンダーとなっている、 Dershowitz と
Reingold の本 "Calendrical Calculations" 中の "proleptic Gregorian" の
カレンダーの定義に合致します。ゼロと負の年は ISO 8601 の基準に定められ
ている通りに扱われます。0 年は 1 BC、-1 年は 2 BC、のように続きます。

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)

      週の最初の曜日を、"int" (0～6) で渡された *firstweekday* に設定
      します。

      "firstweekday" プロパティを設定するのと同じです。

   iterweekdays()

      1 週間に使う曜日番号のイテレーターを返します。 イテレーターの最
      初の値は "firstweekday" プロパティの値と同じです。

   itermonthdates(year, month)

      *year* 年 *month* (1--12) 月に対するイテレータを返します。 この
      イテレータはその月の全ての日、およびその月が始まる前の日とその月
      が終わった後の日のうち、週の欠けを埋めるために必要な日を
      ("datetime.date" オブジェクトとして) 返します。

   itermonthdays(year, month)

      "itermonthdates()" と同様に *year* 年 *month* 月のイテレーターを
      返しますが、"datetime.date" の範囲には制限されません。 各日は単
      に月内の日を表す数値として返されます。 指定した月に含まれない日
      は "0" です。

   itermonthdays2(year, month)

      "itermonthdates()" と同様に *year* 年 *month* 月のイテレーターを
      返しますが、"datetime.date" の範囲には制限されません。 各日は、
      月内の日を表す数値と曜日番号からなるタプルとして返されます。

   itermonthdays3(year, month)

      "itermonthdates()" と同様に *year* 年 *month* 月のイテレーターを
      返しますが、"datetime.date" の範囲には制限されません。 各日は、
      年、月、日を表す数値からなるタプルとして返されます。

      Added in version 3.7.

   itermonthdays4(year, month)

      "itermonthdates()" と同様に *year* 年 *month* 月のイテレーターを
      返しますが、"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()" と同様です)。週のリストの中が日付の数字と
      曜日の数字のタプルになります。月の範囲外の部分の日付はゼロです。

   yeardayscalendar(year, width=3)

      指定された年のデータを整形に向く形で返します
      ("yeardatescalendar()" と同様です)。週のリストの中が日付の数字に
      なります。月の範囲外の日付はゼロです。

class calendar.TextCalendar(firstweekday=0)

   このクラスはプレインテキストのカレンダーを生成するのに使えます。

   "TextCalendar" インスタンスには以下のメソッドがあります:

   prweek(theweek, width)

      "formatweek()" が返す 1 週間分のカレンダーを、末尾に改行を付けず
      に表示します。

   formatday(theday, weekday, width)

      Return a string representing a single day formatted with the
      given *width*. If *theday* is "0", return a string of spaces of
      the specified width, representing an empty day. The *weekday*
      parameter is unused.

   formatweek(theweek, width)

      1 週間分を、改行を含まない文字列で返します。 *width* は、日付を
      中央揃えで表示する列の幅を指定します。 コンストラクターまたは
      "setfirstweekday()" メソッドで指定した週の最初の曜日に従います。

   formatweekday(weekday, width)

      Return a string representing the name of a single weekday
      formatted to the specified *width*. The *weekday* parameter is
      an integer representing the day of the week, where "0" is Monday
      and "6" is Sunday.

   formatweekheader(width)

      曜日名のヘッダー行を、各列の幅が *width* になるよう整形した文字
      列で返します。 曜日名はロケール設定に従い、指定した幅になるよう
      空白を補います。

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

      ひと月分のカレンダーを複数行の文字列で返します。 *w* により日の
      列幅を変えることができ、それらは中央揃えされます。 *l* により各
      週の表示される行数を変えることができます。 "setfirstweekday()"
      メソッドでセットされた週の最初の曜日に依存します。

   formatmonthname(theyear, themonth, width, 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)

      1 年分のカレンダーを完全な HTML ページとして返します。 *width* (
      デフォルトは 3) は、1 行に表示する月の数を指定します。 *css* は
      使用するカスケーディングスタイルシートの名前です。 スタイルシー
      トを使わない場合は "None" を渡せます。 *encoding* は出力のエンコ
      ーディングを指定します (デフォルトは "'utf-8'")。

   formatmonthname(theyear, themonth, withyear=True)

      月名を HTML の表の行として返します。 *withyear* が真の場合は行に
      年も含め、それ以外の場合は月名だけを使います。

   "HTMLCalendar" の次の属性をオーバーライドすると、カレンダーで使う
   CSS クラスを変更できます。

   cssclasses

      各曜日に使う CSS クラスのリストです。 デフォルトのリストは次のと
      おりです。

         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

      1 年分の各月の表をまとめる表に使う CSS クラスです
      ("formatyear()" が使用します)。 デフォルト値は ""year"" です。

      Added in version 3.7.

   cssclass_year_head

      年全体の表の見出しに使う CSS クラスです ("formatyear()" が使用し
      ます)。 デフォルト値は ""year"" です。

      Added in version 3.7.

   これらのクラス属性の名前は単数形 (例えば "cssclass_month" や
   "cssclass_noday") ですが、単一の CSS クラスを、スペースで区切った複
   数の CSS クラスに置き換えることもできます。 例えば次のように指定し
   ます。

      "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" のこのサブクラスは、コンストラクターにロケール名を渡
   せます。 指定したロケールの月名と曜日名を返します。

注釈:

  これら 2 つのクラスのコンストラクターと "formatweekday()"、
  "formatmonthname()" メソッドは、"LC_TIME" ロケールを指定された
  *locale* に一時的に変更します。 現在のロケールはプロセス全体の設定な
  ので、これらはスレッドセーフではありません。

単純なテキストのカレンダーに関して、このモジュールには以下のような関数
が提供されています。

calendar.setfirstweekday(firstweekday)

   週の最初の曜日("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* 未満の年の範囲に含まれる閏年の数を返します。 *y1* と
   *y2* は年を表します。

   この関数は、世紀の境目をまたぐ範囲でも正しく動作します。

calendar.weekday(year, month, day)

   *year* ("1970"--...), *month* ("1"--"12"), *day* ("1"--"31") で与え
   られた日の曜日("0" は月曜日)を返します。

calendar.weekheader(width)

   曜日の略称を含むヘッダーを返します。 *width* は曜日 1 つあたりの幅
   を文字数で指定します。

calendar.monthrange(year, month)

   指定した *year* 年 *month* 月の、最初の日の曜日とその月の日数を返し
   ます。

calendar.monthcalendar(year, month)

   月のカレンダーを行列で返します。各行が週を表し、月の範囲外の日は0に
   なります。それぞれの週は "setfirstweekday()" で設定をしていない限り
   月曜日から始まります。

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

   "month()" 関数によって返される月のカレンダーを出力します。

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

   "TextCalendar" クラスの "formatmonth()" を使い、1 か月分のカレンダ
   ーを複数行の文字列で返します。

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

   "calendar()" 関数で返される一年間のカレンダーを出力します。

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

   "TextCalendar" クラスの "formatyear()" を使い、1 年分の 3 列のカレ
   ンダーを複数行の文字列で返します。

calendar.timegm(tuple)

   カレンダーとは直接関係しませんが、便利な関数です。 "time" モジュー
   ルの "gmtime()" 関数が返すような時刻タプルを受け取り、1970 年をエポ
   ックとする POSIX の表現に従った Unix タイムスタンプを返します。
   "time.gmtime()" と "timegm()" は、互いに逆の変換を行います。

"calendar" モジュールは次のデータ属性を公開します。

calendar.day_name

   現在のロケールの曜日名を表すシーケンスです。 月曜日が曜日番号 0 で
   す。

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

calendar.day_abbr

   現在のロケールの曜日の略称を表すシーケンスです。 月曜日 (Mon) が曜
   日番号 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 月の
   月番号を 1 とするため、長さは 13 で、"month_name[0]" は空文字列です
   。

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

   注意:

     月名に複数の語形があるロケールでは、日付の一部ではなく月名だけを
     単独で表示する場合、"month_name" が適さないことがあります。 例え
     ばギリシャ語や、多くのスラブ系・バルト系の言語では、"month_name"
     は月名の属格を返します。 単独で使うのに適した語形を得るには
     "standalone_month_name" を使ってください。

calendar.month_abbr

   現在のロケールの月名の略称を表すシーケンスです。 通常の慣例どおり 1
   月の月番号を 1 とするため、長さは 13 で、"month_abbr[0]" は空文字列
   です。

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

   注意:

     月名に複数の語形があるロケールでは、日付の一部ではなく月名だけを
     単独で表示する場合、"month_abbr" が適さないことがあります。 単独
     で使うのに適した語形を得るには "standalone_month_abbr" を使ってく
     ださい。

calendar.standalone_month_name

   現在のロケールの月名を表すシーケンスです。 ロケールに単独使用の語形
   があればそれを使い、なければ "month_name" と同じです。

   Added in version 3.15.

calendar.standalone_month_abbr

   現在のロケールの月名の略称を表すシーケンスです。 ロケールに単独使用
   の語形があればそれを使い、なければ "month_abbr" と同じです。

   Added in version 3.15.

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.

"calendar" モジュールは次の例外を定義します。

exception calendar.IllegalMonthError(month)

   "ValueError" と "IndexError" のサブクラスで、指定された月番号が 1～
   12 の範囲外の場合に送出されます。

   バージョン 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.

"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

   "year" で指定した年のうち、カレンダーを表示する月です。 1～12 の数
   値を指定してください。 デフォルトでは 1 年分のカレンダーを表示しま
   す。

*テキストモードのオプション:*

--width WIDTH, -w WIDTH

   日付の列の幅を、端末の桁数で指定します。 日付は列の中央に表示されま
   す。 2 未満の値は無視します。 デフォルトは 2 です。

--lines LINES, -l LINES

   各週に使う行数を、端末の行数で指定します。 日付は上揃えで表示されま
   す。 1 未満の値は無視します。 デフォルトは 1 です。

--spacing SPACING, -s SPACING

   月と月の間隔を桁数で指定します。 2 未満の値は無視します。 デフォル
   トは 6 です。

--months MONTHS, -m MONTHS

   1 行に表示する月の数です。 デフォルトは 3 です。

バージョン 3.14 で変更: デフォルトでは今日の日付を色で強調表示します。
この動作は 環境変数で制御できます。

バージョン 3.15 で変更: デフォルトで月も色で強調表示し、曜日にも色を付
けるようになりました。 この動作は 環境変数で制御できます。

*HTML モードのオプション:*

--css CSS, -c CSS

   カレンダーに使う CSS スタイルシートのパスです。 生成される HTML か
   らの相対パスか、絶対 HTTP URL または "file:///" URL でなければなり
   ません。
