"mimetypes" --- ファイル名を MIME タイプへマップする
****************************************************

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

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

"mimetypes" モジュールは、ファイル名あるいは URL と、ファイル名拡張子
に関連付けられた MIME 型とを変換します。ファイル名から MIME 型へと、
MIME 型からファイル名拡張子への変換が提供されます; 後者の変換では符号
化方式はサポートされていません。

このモジュールは、一つのクラスと多くの便利な関数を提供します。これらの
関数がこのモジュールへの標準のインターフェースですが、アプリケーション
によっては、そのクラスにも関係するかもしれません。

以下で説明されている関数は、このモジュールへの主要なインターフェースを
提供します。たとえモジュールが初期化されていなくても、もしこれらの関数
が、 "init()" がセットアップする情報に依存していれば、これらの関数は、
"init()" を呼びます。

mimetypes.guess_type(url, strict=True)

   *url* で与えられるファイル名あるいは URL に基づいて、ファイルの型を
   推定します。URL は文字列または *path-like object* です。

   戻り値は、タプル "(type, encoding)" です、ここで  *type* は、もし型
   が(拡張子がないあるいは未定義のため)推定できない場合は、 "None" を
   、あるいは、 MIME *content-type* ヘッダ  に利用できる、
   "'type/subtype'" の形の文字列です。

   *encoding* は、符合化方式がない場合は "None" を、あるいは、符号化に
   使われるプログラムの名前 (たとえば、 **compress** あるいは
   **gzip**)です。符号化方式は *Content-Encoding* ヘッダとして使うのに
   適しており、 *Content-Transfer-Encoding* ヘッダには適して **いませ
   ん** 。マッピングはテーブル駆動です。符号化方式のサフィックスは大/
   小文字を区別します; データ型サフィックスは、最初大/小文字を区別して
   試し、それから大/小文字を区別せずに試します。

   省略可能な *strict* 引数は、既知の MIME 型のリストとして認識される
   ものが、IANAに登録された 正式な型のみに限定されるかどうかを指定する
   フラグです。*strict* が "True" (デフォルト)の時は、IANA 型のみがサ
   ポートされます; *strict* が "False" のときは、いくつかの追加の、非
   標準ではあるが、一般的に使用される MIME 型も認識されます。

   バージョン 3.8 で変更: Added support for *url* being a *path-like
   object*.

   バージョン 3.13 で非推奨: Passing a file path instead of URL is
   *soft deprecated*. Use "guess_file_type()" for this.

mimetypes.guess_file_type(path, *, strict=True)

   Guess the type of a file based on its path, given by *path*.
   Similar to the "guess_type()" function, but accepts a path instead
   of URL. Path can be a string, a bytes object or a *path-like
   object*.

   Added in version 3.13.

mimetypes.guess_all_extensions(type, strict=True)

   Guess the extensions for a file based on its MIME type, given by
   *type*. The return value is a list of strings giving all possible
   filename extensions, including the leading dot ("'.'").  The
   extensions are not guaranteed to have been associated with any
   particular data stream, but would be mapped to the MIME type *type*
   by "guess_type()" and "guess_file_type()".

   省略可能な *strict* 引数は "guess_type()" 関数のものと同じ意味を持
   ちます。

mimetypes.guess_extension(type, strict=True)

   Guess the extension for a file based on its MIME type, given by
   *type*. The return value is a string giving a filename extension,
   including the leading dot ("'.'").  The extension is not guaranteed
   to have been associated with any particular data stream, but would
   be mapped to the MIME type *type* by "guess_type()" and
   "guess_file_type()". If no extension can be guessed for *type*,
   "None" is returned.

   省略可能な *strict* 引数は "guess_type()" 関数のものと同じ意味を持
   ちます。

モジュールの動作を制御するために、いくつかの追加の関数とデータ項目が利
用できます。

mimetypes.init(files=None)

   内部のデータ構造を初期化します。もし  *files* が与えられていれば、
   これはデフォルトの type map を増やすために使われる、一連のファイル
   名でなければなりません。もし省略されていれば、使われるファイル名は
   "knownfiles" から取られます。 Windows であれば、現在のレジストリの
   設定が読み込まれます。 *files* あるいは "knownfiles" 内の各ファイル
   名は、それ以前に現れる名前より優先されます。繰り返し "init()" を呼
   び出すことは許されています。

   *files* に空リストを与えることで、システムのデフォルトが適用される
   のを避けることが出来ます; 組み込みのリストから well-known な値だけ
   が取り込まれます。

   *files* が "None" の場合、内部のデータ構造は初期のデフォルト値に完
   全に再構築されます。 これは安定な操作であり、複数回呼び出されたとき
   は同じ結果になります。

   バージョン 3.2 で変更: 前のバージョンでは、 Windows のレジストリの
   設定は無視されていました。

mimetypes.read_mime_types(filename)

   ファイル *filename* で与えられた型のマップが、もしあればロードしま
   す。型のマップは、先頭の dot ("'.'") を含むファイル名拡張子を、
   "'type/subtype'" の形の文字列にマッピングする辞書として返されます。
   もしファイル *filename* が存在しないか、読み込めなければ、"None" が
   返されます。

mimetypes.add_type(type, ext, strict=True)

   MIME 型 *type* からのマッピングを拡張子 *ext* に追加します。拡張子
   がすでに既知であれば、新しい型が古いものに置き替わります。その型が
   すでに既知であれば、その拡張子が、既知の拡張子のリストに追加されま
   す。

   *strict* が "True" の時(デフォルト)は、そのマッピングは正式な MIME
   型に、そうでなければ、非標準の MIME 型に追加されます。

mimetypes.inited

   グローバルなデータ構造が初期化されているかどうかを示すフラグ。これ
   は "init()" により "True" に設定されます。

mimetypes.knownfiles

   共通にインストールされた型マップファイル名のリスト。これらのファイ
   ルは、普通 "mime.types" という名前であり、パッケージごとに異なる場
   所にインストールされます。

mimetypes.suffix_map

   サフィックスをサフィックスにマップする辞書。これは、符号化方式と型
   が同一拡張子で示される符号化ファイルが認識できるように使用されます
   。例えば、 ".tgz" 拡張子は、符号化と型が別個に認識できるように
   ".tar.gz" にマップされます。

mimetypes.encodings_map

   ファイル名拡張子を符号化方式型にマッピングする辞書。

mimetypes.types_map

   ファイル名拡張子を MIME 型にマップする辞書。

mimetypes.common_types

   ファイル名拡張子を非標準ではあるが、一般に使われている MIME 型にマ
   ップする辞書。

モジュールの使用例:

   >>> import mimetypes
   >>> mimetypes.init()
   >>> mimetypes.knownfiles
   ['/etc/mime.types', '/etc/httpd/mime.types', ... ]
   >>> mimetypes.suffix_map['.tgz']
   '.tar.gz'
   >>> mimetypes.encodings_map['.gz']
   'gzip'
   >>> mimetypes.types_map['.tgz']
   'application/x-tar-gz'


Mime 型オブジェクト
===================

"MimeTypes" クラスは一つ以上の MIME 型データベースが欲しいアプリケーシ
ョンにとって有用でしょう。これは "mimetypes" モジュールのそれと似たイ
ンターフェースを提供します。

class mimetypes.MimeTypes(filenames=(), strict=True)

   このクラスは、MIME 型データベースを表現します。デフォルトでは、この
   モジュールの他のものと同じデータベースへのアクセスを提供します。初
   期データベースは、このモジュールによって提供されるもののコピーで、
   追加の "mime.types" 形式のファイルを、 "read()" あるいは "readfp()"
   メソッドを使って、データベースにロードすることで拡張されます。マッ
   ピング辞書も、もしデフォルトのデータが望むものでなければ、追加のデ
   ータをロードする前にクリアされます。

   省略可能な *filenames* パラメータは、追加のファイルを、デフォルトデ
   ータベースの"トップに"ロードさせるのに使うことができます。

   suffix_map

      サフィックスをサフィックスにマップする辞書。これは、符号化方式と
      型が同一拡張子で示されるような符号化ファイルが認識できるように使
      用されます。例えば、 ".tgz" 拡張子は、符号化方式と型が別個に認識
      できるように ".tar.gz" に対応づけられます。これは、最初はモジュ
      ールで定義されたグローバルな "suffix_map" のコピーです。

   encodings_map

      ファイル名拡張子を符号化型にマッピングする辞書。これは、最初はモ
      ジュールで定義されたグローバルな "encodings_map" のコピーです。

   types_map

      ファイル名拡張子を MIME 型にマッピングする 2 種類の辞書のタプル;
      最初の辞書は非標準型、二つ目は標準型の辞書です。初期状態ではそれ
      ぞれ "common_types" と "types_map" です。

   types_map_inv

      MIME 型をファイル名拡張子のリストにマッピングする 2 種類の辞書の
      タプル; 最初の辞書は非標準型、二つ目は標準型の辞書です。初期状態
      ではそれぞれ "common_types" と "types_map" です。

   guess_extension(type, strict=True)

      "guess_extension()" 関数と同様ですが、オブジェクトに保存されたテ
      ーブルを使用します。

   guess_type(url, strict=True)

      "guess_type()" 関数と同様ですが、オブジェクトに保存されたテーブ
      ルを使用します。

   guess_file_type(path, *, strict=True)

      Similar to the "guess_file_type()" function, using the tables
      stored as part of the object.

      Added in version 3.13.

   guess_all_extensions(type, strict=True)

      "guess_all_extensions()" と同様ですが、オブジェクトに保存された
      テーブルを参照します。

   read(filename, strict=True)

      MIME 情報を、 *filename* という名のファイルからロードします。こ
      れはファイルを解析するのに "readfp()" を使用します。

      *strict* が "True" の時 (デフォルト) は、そのマッピングは標準
      MIME 型のリストに、そうでなければ、非標準 MIME 型のリストに追加
      されます。

   readfp(fp, strict=True)

      MIME 型情報を、オープンしたファイル *fp* からロードします。ファ
      イルは、標準の "mime.types" ファイルの形式でなければなりません。

      *strict* が "True" の時 (デフォルト) は、そのマッピングは標準
      MIME 型のリストに、そうでなければ、非標準 MIME 型のリストに追加
      されます。

   read_windows_registry(strict=True)

      MIME type 情報を Windows のレジストリから読み込みます。

      利用可能な環境: Windows 。

      *strict* が "True" の時 (デフォルト) は、そのマッピングは標準
      MIME 型のリストに、そうでなければ、非標準 MIME 型のリストに追加
      されます。

      Added in version 3.2.

   add_type(type, ext, strict=True)

      MIME 型 *type* からのマッピングを拡張子 *ext* に追加します。拡張
      子がすでに既知であれば、新しい型が古いものに置き替わります。その
      型がすでに既知であれば、その拡張子が、既知の拡張子のリストに追加
      されます。

      *strict* が "True" の時(デフォルト)は、そのマッピングは正式な
      MIME 型に、そうでなければ、非標準の MIME 型に追加されます。
