# 2 `calendar` -- 一般的なカレンダーに関する関数群

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

このモジュールで提供する関数とクラスのほとんどは `datetime` に依存しており、 過去も未来も現代のグレゴリオ暦を利用します。この方式はDershowitzとReingold の書籍「Calendrical Calculations」にある proleptic Gregorian 暦に一致しており、 同書では全ての計算の基礎となる暦としています。
(訳注: proleptic Gregorian 暦とはグレゴリオ暦制定(1582年)以前についても グレゴリオ暦で言い表す暦の方式のことで ISO 8601 などでも採用されています)

クラス `Calendar`( | [firstweekday])

  `Calendar` オブジェクトを作ります。firstweekday は整数で 週の始まりの曜日を指定するものです。`0` が月曜(デフォルト)、 `6` なら日曜です。

  `Calendar` オブジェクトは整形されるカレンダーのデータを準備するために使える いくつかのメソッドを提供しています。しかし整形機能そのものは提供していません。 それはサブクラスの仕事なのです。 バージョン 2.5 で 新たに追加 された仕様です。

`Calendar` インスタンスには以下のメソッドがあります。

`iterweekdays`( | weekday)

  曜日の数字を一週間分生成するイテレータを返します。 イテレータから得られる最初の数字は `firstweekday()` が返す数字と同じになります。

`itermonthdates`( | year, month)

  year 年 month 月に対するイテレータを返します。 このイテレータはその月の全ての日(`datetime.date` オブジェクトとして) およびその前後の日で週に欠けが無いようにするのに必要な日を返します。

`itermonthdays2`( | year, month)

  year 年 month 月に対する `itermonthdates()` と同じような イテレータを返します。生成されるのは日付の数字と曜日を表す数字のタプルです。

`itermonthdays`( | year, month)

  year 年 month 月に対する `itermonthdates()` と同じような イテレータを返します。生成されるのは日付の数字だけです。

`monthdatescalendar`( | year, month)

  year 年 month 月の週のリストを返します。 週は全て七つの `datetime.date` オブジェクトからなるリストです。

`monthdays2calendar`( | year, month)

  year 年 month 月の週のリストを返します。 週は全て七つの日付の数字と曜日を表す数字のタプルからなるリストです。

`monthdayscalendar`( | year, month)

  year 年 month 月の週のリストを返します。 週は全て七つの日付の数字からなるリストです。

`yeardatescalendar`( | year[, width])

  指定された年のデータを整形に向く形で返します。返される値は月の並びのリストです。 月の並びは最大で width ヶ月(デフォルトは3ヶ月)分です。 各月は4ないし6週からなり、各週は1ないし7日からなります。 各日は `datetime.date` オブジェクトです。

`yeardays2calendar`( | year[, width])

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

`yeardayscalendar`( | year[, width])

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

クラス `TextCalendar`( | [firstweekday])

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

  バージョン 2.5 で 新たに追加 された仕様です。

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

`formatmonth`( | theyear, themonth[, w[, l]])

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

`prmonth`( | theyear, themonth[, w[, l]])

  `formatmonth()` で返されるひと月分のカレンダーを出力します。

`formatyear`( | theyear[, w[, l[, c[, m]]]])

  m列からなる一年間のカレンダーを複数行の文字列で返します。 任意の引数 w, l, c はそれぞれ、日付列の表示幅、各週の行数及び 月と月の間のスペースの数を変更するためのものです。 `setfirstweekday()` メソッドでセットされた週の最初の曜日に依存します。 カレンダーを出力できる最初の年はプラットフォームに依存します。

`pryear`( | theyear[, w[, l[, c[, m]]]])

  `formatyear()` で返される一年間のカレンダーを出力します。

クラス `HTMLCalendar`( | [firstweekday])

  このクラスは HTML のカレンダーを生成するのに使えます。

  バージョン 2.5 で 新たに追加 された仕様です。

`HTMLCalendar` インスタンスには以下のメソッドがあります。

`formatmonth`( | theyear, themonth[, withyear])

  ひと月分のカレンダーを HTML のテーブルとして返します。withyear が 真であればヘッダには年も含まれます。そうでなければ月の名前だけが使われます。

`formatyear`( | theyear[, width])

  一年分のカレンダーを HTML のテーブルとして返します。width の値 (デフォルトでは 3 です) は何ヶ月分を一行に収めるかを指定します。

`formatyearpage`( | theyear[, width[, css[, encoding]]])

  一年分のカレンダーを一つの完全な HTML ページとして返します。 width の値(デフォルトでは 3 です) は何ヶ月分を一行 に収めるかを指定します。css は使われるカスケーディング スタイルシートの名前です。スタイルシートを使わないようにするために `None` を渡すこともできます。encoding には 出力に使うエンコーディングを指定します (デフォルトではシステムデフォルトのエンコーディングです)。

クラス `LocaleTextCalendar`( | [firstweekday[, locale]])

  この `TextCalendar` のサブクラスではコンストラクタにロケール名を渡す ことができ、メソッドの返り値で月や曜日が指定されたロケールのものになります。 このロケールがエンコーディングを含む場合には、月や曜日の入った文字列は ユニコードとして返されます。 バージョン 2.5 で 新たに追加 された仕様です。

クラス `LocaleHTMLCalendar`( | [firstweekday[, locale]])

  この `HTMLCalendar` のサブクラスではコンストラクタにロケール名を渡す ことができ、メソッドの返り値で月や曜日が指定されたロケールのものになります。 このロケールがエンコーディングを含む場合には、月や曜日の入った文字列は ユニコードとして返されます。 バージョン 2.5 で 新たに追加 された仕様です。

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

`setfirstweekday`( | weekday)

  週の最初の曜日(`0`は月曜日, `6`は日曜日)を設定します。定数 `MONDAY`, `TUESDAY`, `WEDNESDAY`,`THURSDAY`, `FRIDAY`, `SATURDAY`及び`SUNDAY` は便宜上提供されています。 例えば、日曜日を週の開始日に設定するとき:

      import calendar
      calendar.setfirstweekday(calendar.SUNDAY)

  バージョン 2.0 で 新たに追加 された仕様です。

`firstweekday`( | )

  現在設定されている週の最初の曜日を返します。 バージョン 2.0 で 新たに追加 された仕様です。

`isleap`( | year)

  yearが閏年なら`True`を、そうでなければ`False`を返します。

`leapdays`( | y1, y2)

  範囲(y1...y2)指定された期間の閏年の回数を返します。 ここでy1やy2は年を表します。 バージョン 2.0 で 変更 された仕様: Python 1.5.2では、この関数は世紀をまたがった範囲では動作 しません。

`weekday`( | year, month, day)

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

`weekheader`( | n)

  短縮された曜日名を含むヘッダを返します。n は各曜日を何文字で表すかを 指定します。

`monthrange`( | year, month)

  yearとmonthで指定された月の一日の曜日と日数を返します。

`monthcalendar`( | year, month)

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

`prmonth`( | theyear, themonth[, w[, l]])

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

`month`( | theyear, themonth[, w[, l]])

  `TextCalendar` の `formatmonth` メソッドを利用して、 ひと月分のカレンダーを複数行の文字列で返します。 バージョン 2.0 で 新たに追加 された仕様です。

`prcal`( | year[, w[, l[c]]])

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

`calendar`( | year[, w[, l[c]]])

  `TextCalendar` の `formatyear` メソッドを利用して、 3列からなる一年間のカレンダーを複数行の文字列で返します。 バージョン 2.0 で 新たに追加 された仕様です。

`timegm`( | tuple)

  関連はありませんが便利な関数で、`time`モジュールの `gmtime()`関数の戻値のような時間のタプルを受け取り、 1970年を 起点とし、POSIX規格のエンコードによるUnixのタイムスタンプに相当する 値を返します。実際、`time.gmtime()`と`timegm()`は反対 の動作をします。 バージョン 2.0 で 新たに追加 された仕様です。

`calendar` モジュールの以下のデータ属性を利用することができます:

`day_name`
  現在のロケールでの曜日を表す配列です。

`day_abbr`
  現在のロケールでの短縮された曜日を表す配列です。

`month_name`
  現在のロケールでの月の名を表す配列です。この配列は通常の約束事に従って、 1月を数字の 1 で表しますので、長さが 13 ある代わりに `month_name[0]` が空文字列になります。

`month_abbr`
  現在のロケールでの短縮された月の名を表す配列です。この配列は通常の約束事に従って、 1月を数字の 1 で表しますので、長さが 13 ある代わりに `month_name[0]` が空文字列になります。

参考:

`datetime`:モジュール
  `time` モジュールと似た機能を持った 日付と時間用のオブジェクト指向インタフェース。.

`time`:モジュール
  低レベルの時間に関連した関数群。.