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

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

The `mimetypes` module converts between a filename or URL and the MIME type associated with the filename extension. Conversions are provided from filename to MIME type and from MIME type to filename extension; encodings are not supported for the latter conversion.

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

以下で説明されている関数は、このモジュールへの主要なインターフェースを提供します。たとえモジュールが初期化されていなくても、もしこれらの関数が、 `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.

  Soft deprecated since version 3.13: Passing a file path instead of URL. 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)

  Add a mapping from the MIME type type to the extension ext. 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. Valid extensions are empty or start with a `'.'`.

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

  バージョン 3.14 で非推奨: ext values that do not start with `'.'` are deprecated.

  バージョン 3.16.0a0 (unreleased) で変更: ext now must start with `'.'`. Otherwise `ValueError` is raised.

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

The `MimeTypes` class may be useful for applications which may want more than one MIME-type database; it provides an interface similar to the one of the `mimetypes` module.

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

    バージョン 3.14 で非推奨: ext values that do not start with `'.'` are deprecated.

    バージョン 3.16.0a0 (unreleased) で変更: ext now must start with `'.'`. Otherwise `ValueError` is raised.

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

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