"calendar" — 一般的なカレンダーに関する関数群
*********************************************

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

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

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

Most of these functions and classes rely on the "datetime" module
which uses an idealized calendar, the current Gregorian calendar
indefinitely extended in both directions.  This matches the definition
of the 「proleptic Gregorian」 calendar in Dershowitz and Reingold’s
book 「Calendrical Calculations」, where it’s the base calendar for
all computations.

class calendar.Calendar([firstweekday])

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

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

   バージョン 2.5 で追加.

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

   iterweekdays()

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

   itermonthdates(year, month)

      *year* 年 *month* (1–12) 月に対するイテレータを返します。 このイ
      テレータはその月の全ての日、およびその月が始まる前の日とその月が
      終わった後の日のうち、週の欠けを埋めるために必要な日を
      ("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()" と同様です)。週のリストの中が日付の数字に
      なります。月の範囲外の日付はゼロです。

class calendar.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()" で返される一年間のカレンダーを出力します。

class calendar.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* には出力に使うエンコーディングを指定し
      ます (デフォルトではシステムデフォルトのエンコーディングです)。

class calendar.LocaleTextCalendar([firstweekday[, locale]])

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

   バージョン 2.5 で追加.

class calendar.LocaleHTMLCalendar([firstweekday[, locale]])

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

   バージョン 2.5 で追加.

注釈: これら2つのクラスの "formatweekday()" と "formatmonthname()"
  メソッ ドは、一時的に現在の locale を指定された *locale* に変更しま
  す。現在 の locale はプロセス全体に影響するので、これらはスレッドセ
  ーフではあ りません。

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

calendar.setfirstweekday(weekday)

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

      import calendar
      calendar.setfirstweekday(calendar.SUNDAY)

   バージョン 2.0 で追加.

calendar.firstweekday()

   現在設定されている週の最初の曜日を返します。

   バージョン 2.0 で追加.

calendar.isleap(year)

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

calendar.leapdays(y1, y2)

   範囲(*y1* … *y2*)指定された期間の閏年の回数を返します。ここで *y1*
   や *y2* は年を表します。

   バージョン 2.0 で変更: This function didn’t work for ranges
   spanning a century change in Python 1.5.2.

calendar.weekday(year, month, day)

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

calendar.weekheader(n)

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

calendar.monthrange(year, month)

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

calendar.monthcalendar(year, month)

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

calendar.prmonth(theyear, themonth[, w[, l]])

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

calendar.month(theyear, themonth[, w[, l]])

   "TextCalendar" の "formatmonth()" メソッドを利用して、ひと月分のカ
   レンダーを複数行の文字列で返します。

   バージョン 2.0 で追加.

calendar.prcal(year[, w[, l[c]]])

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

calendar.calendar(year[, w[, l[c]]])

   "TextCalendar" の "formatyear()" メソッドを利用して、 3列からなる一
   年間のカレンダーを複数行の文字列で返します。

   バージョン 2.0 で追加.

calendar.timegm(tuple)

   カレンダーと直接は関係無いが、 "time" モジュールの "gmtime()" 関数
   が返す形式の時刻を表すタプルを引数に取り、1970 を基点とするエポック
   時刻で POSIX エンコーディングであると仮定して、対応する Unix タイム
   スタンプの値を返します。実際には、 "time.gmtime()" と "timegm()" は
   お互いの逆関数です。

   バージョン 2.0 で追加.

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

calendar.day_name

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

calendar.day_abbr

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

calendar.month_name

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

calendar.month_abbr

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

参考:

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

  "time" モジュール
     時間に関連した低水準の関数群。
