"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* ヘッダには適して **いませ
   ん** 。マッピングはテーブル駆動です。符号化方式のサフィックスは大/
   小文字を区別します; データ型サフィックスは、最初大/小文字を区別して
   試し、それから大/小文字を区別せずに試します。

   The optional *strict* argument is a flag specifying whether the
   list of known MIME types is limited to only the official types
   registered with IANA. However, the behavior of this module also
   depends on the underlying operating system. Only file types
   recognized by the OS or explicitly registered with Python's
   internal database can be identified. When *strict* is "True" (the
   default), only the IANA types are supported; when *strict* is
   "False", some additional non-standard but commonly used MIME types
   are also recognized.

   バージョン 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'


MimeTypes objects
=================

"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 のレジストリから読み込みます。

      Availability: Windows.

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

      Added in version 3.2.

   add_type(type, ext, strict=True)

      Add a mapping from the MIME type *type* to the extension *ext*.
      Valid extensions start with a '.' or are empty. When the
      extension is already known, the new type will replace the old
      one. When the type is already known the extension will be added
      to the list of known extensions.

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

      Deprecated since version 3.14, will be removed in version 3.16:
      Invalid, undotted extensions will raise a "ValueError" in Python
      3.16.


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

The "mimetypes" module can be executed as a script from the command
line.

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

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

-h
--help

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

-e
--extension

   Guess extension instead of type.

-l
--lenient

   Additionally search for some common, but non-standard types.

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

For each "type" entry, the script writes a line into the standard
output stream. If an unknown type occurs, it writes an error message
into the standard error stream and exits with the return code "1".


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

Here are some examples of typical usage of the "mimetypes" command-
line interface:

   $ # 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: unknown extension of 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: unknown extension of filename.xxx

   $ # 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
