"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 に登録された 正
   式な型だけに限定するかどうかを指定するフラグです。 ただし、このモジ
   ュールの動作は、使用しているオペレーティングシステムにも依存します
   。 OS が認識するファイル型か、Python 内部のデータベースに明示的に登
   録されたファイル型だけを識別できます。 *strict* が "True" (デフォル
   ト) の場合は IANA の型だけをサポートします。 "False" の場合は、非標
   準ですが一般的に使われている MIME 型の一部も認識します。

   バージョン 3.8 で変更: *url* に *path-like object* を指定できるよう
   になりました。

   バージョン 3.13 で ソフト非推奨 <Soft deprecated>: URL の代わりにフ
   ァイルパスを渡すことは非推奨です。 ファイルパスには
   "guess_file_type()" を使ってください。

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

   *path* で指定されたパスに基づき、ファイルの型を推定します。
   "guess_type()" に似ていますが、URL ではなくパスを受け付けます。 パ
   スには文字列、bytes オブジェクト、*path-like object* を指定できます
   。

   Added in version 3.13.

mimetypes.guess_all_extensions(type, strict=True)

   *type* で指定された MIME 型に基づき、ファイルの拡張子を推定します。
   戻り値は、先頭のドット ("'.'") を含む、候補となるすべてのファイル拡
   張子の文字列リストです。 拡張子が特定のデータストリームに関連付けら
   れていたことは保証されませんが、"guess_type()" と
   "guess_file_type()" に渡すと MIME 型 *type* に対応付けられます。

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

mimetypes.guess_extension(type, strict=True)

   *type* で指定された MIME 型に基づき、ファイルの拡張子を推定します。
   戻り値は、先頭のドット ("'.'") を含むファイル拡張子の文字列です。
   拡張子が特定のデータストリームに関連付けられていたことは保証されま
   せんが、"guess_type()" と "guess_file_type()" に渡すと MIME 型
   *type* に対応付けられます。 *type* の拡張子を推定できなければ
   "None" を返します。

   省略可能な *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(file)

   *file* で指定された名前のファイルが存在する場合、そこから型マップを
   読み込みます。 *file* は読み込むファイル名を指定する文字列でなけれ
   ばなりません。 型マップは、先頭のドット ("'.'") を含むファイル拡張
   子から "'type/subtype'" 形式の文字列へのマッピングである辞書として
   返されます。 ファイルが存在しないか読み取れない場合は "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'


MimeTypes オブジェクト
======================

"MimeTypes" クラスは、複数の MIME 型データベースを必要とするアプリケー
ションに便利です。 "mimetypes" モジュールと似たインターフェースを提供
します。

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

   このクラスは MIME 型のデータベースを表します。 デフォルトでは、この
   モジュールの他の部分と同じデータベースにアクセスできます。 初期デー
   タベースは Python 組み込みの MIME 型テーブルから作成します。
   "read()" や "readfp()" メソッドで、"mime.types" 形式のファイルを追
   加で読み込み、データベースを拡張できます。 デフォルトのデータが不要
   な場合は、追加データを読み込む前にマッピングの辞書を空にすることも
   できます。

   オプションの *filenames* 引数を使うと、デフォルトのデータベースに追
   加のファイルを読み込ませることができます。

   suffix_map

      拡張子から拡張子へのマッピングを持つ辞書です。 符号化方式と型を
      同じ拡張子で示す、符号化されたファイルを認識するために使います。
      例えば ".tgz" は ".tar.gz" に対応付けられ、符号化方式と型を別々
      に認識できるようにします。 あらかじめ定められた値で初期化されま
      す。

   encodings_map

      ファイル拡張子から符号化方式へのマッピングを持つ辞書です。 あら
      かじめ定められた値で初期化されます。

   types_map

      ファイル拡張子から MIME 型へのマッピングを持つ 2 つの辞書のタプ
      ルです。 最初の辞書は非標準の型、2 番目の辞書は標準の型を扱いま
      す。 あらかじめ定められた値と、*filenames* 引数で指定されたファ
      イルから読み込んだ MIME 型情報で初期化されます。

   types_map_inv

      MIME 型からファイル拡張子のリストへのマッピングを持つ 2 つの辞書
      のタプルです。 最初の辞書は非標準の型、2 番目の辞書は標準の型を
      扱います。 あらかじめ定められた値と、*filenames* 引数で指定され
      たファイルから読み込んだ MIME 型情報で初期化されます。

   guess_extension(type, strict=True)

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

   guess_type(url, strict=True)

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

   guess_file_type(path, *, strict=True)

      "guess_file_type()" 関数に似ていますが、オブジェクト内に保存され
      たテーブルを使います。

      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 型に追加されます。

      バージョン 3.14 で非推奨、バージョン 3.16 で削除予定: ドットで始
      まらない無効な拡張子は、Python 3.16 で "ValueError" を送出するよ
      うになります。


コマンドラインでの使用
======================

"mimetypes" モジュールは、コマンドラインからスクリプトとして実行できま
す。

   python -m mimetypes [-h] [-e] [-l] type [type ...]

以下のオプションが使用できます:

-h
--help

   ヘルプメッセージを表示して終了します。

-e
--extension

   型の代わりに拡張子を推定します。

-l
--lenient

   非標準ですが一般的に使われている型も検索します。

By default the script converts MIME types to file extensions. However,
if "--extension" is specified, it converts file extensions to MIME
types.

スクリプトは各 "type" について、標準出力ストリームに 1 行を書き出しま
す。 不明な型があれば、標準出力ストリームにエラーメッセージを書き出し
、終了コード "1" で終了します。


コマンドラインの例
==================

"mimetypes" のコマンドラインインターフェースの一般的な使用例を示します
。

   $ # get a MIME type by a file name
   $ python -m mimetypes filename.png
   type: image/png encoding: None

   $ # get a MIME type by a URL
   $ python -m mimetypes https://example.com/filename.txt
   type: text/plain encoding: None

   $ # get a complex MIME type
   $ python -m mimetypes filename.tar.gz
   type: application/x-tar encoding: gzip

   $ # get a MIME type for a rare file extension
   $ python -m mimetypes filename.pict
   error: media type unknown for filename.pict

   $ # now look in the extended database built into Python
   $ python -m mimetypes --lenient filename.pict
   type: image/pict encoding: None

   $ # get a file extension by a MIME type
   $ python -m mimetypes --extension text/javascript
   .js

   $ # get a file extension by a rare MIME type
   $ python -m mimetypes --extension text/xul
   error: unknown type text/xul

   $ # now look in the extended database again
   $ python -m mimetypes --extension --lenient text/xul
   .xul

   $ # try to feed an unknown file extension
   $ python -m mimetypes filename.sh filename.nc filename.xxx filename.txt
   type: application/x-sh encoding: None
   type: application/x-netcdf encoding: None
   error: media type unknown for filename.xxx
   type: text/plain encoding: None

   $ # try to feed an unknown MIME type
   $ python -m mimetypes --extension audio/aac audio/opus audio/future audio/x-wav
   .aac
   .opus
   error: unknown type audio/future
