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

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

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

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

このモジュールで提供する関数とクラスのほとんどは "datetime" に依存して
おり、過去も未来も現代のグレゴリオ暦を利用します。この方式は
Dershowitz と Reingold の書籍「Calendrical Calculations」にある先発グ
レゴリオ暦に一致しており、同書では全ての計算の基礎となる暦としています
。

class calendar.Calendar(firstweekday=0)

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

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

   "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=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" インスタンスには以下のメソッドがあります:

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

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

   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)

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

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

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

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

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

注釈: これら2つのクラスの "formatweekday()" と "formatmonthname()"
  メソッ ドは、一時的に現在の locale を指定された *locale* に変更しま
  す。現在 の 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*)指定された期間の閏年の回数を返します。ここで
   *y1* や *y2* は年を表します。

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

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=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)

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

"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" モジュール
     時間に関連した低水準の関数群。
