# `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`，或者为 `'type/subtype'` 形式的字符串，可以作为 MIME content-type 标头。

  encoding 在无编码格式时为 `None`，或者为程序所用的编码格式 (例如 compress 或 gzip)。 它可以作为 Content-Encoding 标头，但 不可 作为 Content-Transfer-Encoding 标头。 映射是表格驱动的。 编码格式前缀对大小写敏感；类型前缀会先以大小写敏感方式检测再以大小写不敏感方式检测。

  可选的 strict 参数是一个旗标，指明要将已知 MIME 类型限制在 IANA 已注册的 官方类型之内。 但是，此模块的行为也取决于底层操作系统。只能识别操作系统识别的或在Python内部数据库中明确注册的文件类型。当 strict 为 `True` 时（默认值），则仅支持 IANA 类型；当 strict 为 `False` 时，则还支持某些附加的非标准但常用的 MIME 类型。

  在 3.8 版本发生变更: 增加了对于 url 使用 path-like object 的支持。

  自 3.13 版本弃用: 传入文件路径而非 URL 的做法已经 soft deprecated。 此种情况改用 `guess_file_type()`。

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

  根据由 path 给出的文件路径猜测其类型。 类似于 `guess_type()` 函数，但可接受路径而非 URL。 路径可以是字符串、字节串对象或 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 如果给出则必须是一个文件名序列，它应当被用于协助默认的类型映射。 如果省略则要使用的文件名会从 `knownfiles` 中获取； 在 Windows 上，将会载入当前注册表设置。 在 files 或 `knownfiles` 中指定的每个文件名的优先级将高于在它之前的文件名。 `init()` 允许被重复调用。

  为 files 指定一个空列表将防止应用系统默认选项：将只保留来自内置列表的常用值。

  如果 files 为 `None` 则内部数据结构会完全重建为其初始默认值。 这是一个稳定操作并将在多次调用时产生相同的结果。

  在 3.2 版本发生变更: 在之前版本中，Windows 注册表设置会被忽略。

mimetypes.read_mime_types(filename)

  载入在文件 filename 中给定的类型映射，如果文件存在的话。 返回的类型映射会是一个字典，其中的键值对为文件扩展名包括开头的点号 (`'.'`) 与 `'type/subtype'` 形式的字符串。 如果文件 filename 不存在或无法被读取，则返回 `None`。

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

  添加一个从 MIME 类型 type 到扩展名 ext 的映射。 当扩展名已知时，新类型将替代旧类型。 当类型已知时，扩展名将被添加到已知扩展名列表。

  当 strict 为 `True` 时（默认值），映射将被添加到官方 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 对象

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 类型数据库。 默认情况下，它提供了对与此模块其余部分一致的数据库的访问权限。 这个初始数据库是此模块所提供数据库的一个副本，并可以通过使用 `read()` 或 `readfp()` 方法将附加的 `mime.types` 样式文载入到数据库中来进行扩展。 如果不需要默认数据的话这个映射字典也可以在载入附加数据之前先被清空。

  可选的 filenames 形参可被用来让附加文件被载入到默认数据库“之上”。

  suffix_map

    将后缀映射到其他后缀的字典。 它被用来允许识别已编码的文件，其编码格式和类型是由相同的扩展名来指明的。 例如，`.tgz` 扩展名被映射到 `.tar.gz` 以允许编码格式和类型被分别识别。 这是在模块中定义的全局 `suffix_map` 的一个副本。

  encodings_map

    映射文件扩展名到编码格式类型的字典。 这是在模块中定义的全局 `encodings_map` 的一个副本。

  types_map

    包含两个字典的元组，将文件扩展名映射到 MIME 类型：第一个字典针对非标准类型而第二个字典针对标准类型。 它们会由 `common_types` 和 `types_map` 来初始化。

  types_map_inv

    包含两个字典的元组，将 MIME 类型映射到文件扩展名列表：第一个字典针对非标准类型而第二个字典针对标准类型。 它们会由 `common_types` 和 `types_map` 来初始化。

  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)

    从名称为 filename 的文件载入 MIME 信息。 此方法使用 `readfp()` 来解析文件。

    如果 strict 为 `True`，信息将被添加到标准类型列表，否则添加到非标准类型列表。

  readfp(fp, strict=True)

    从打开的文件 fp 载入 MIME 类型信息。 文件必须具有标准 `mime.types` 文件的格式。

    如果 strict 为 `True`，信息将被添加到标准类型列表，否则添加到非标准类型列表。

  read_windows_registry(strict=True)

    从 Windows 注册表载入 MIME 类型信息。

    Availability: Windows.

    如果 strict 为 `True`，信息将被添加到标准类型列表，否则添加到非标准类型列表。

    Added in version 3.2.

  add_type(type, ext, strict=True)

    添加一个从 MIME 类型 type 到扩展名 ext 的映射。有效的扩展名以“.”开头或为空。 当扩展名已知时，新类型将替代旧类型。 当类型已知时，扩展名将被添加到已知扩展名列表。

    当 strict 为 `True` 时（默认值），映射将被添加到官方 MIME 类型，否则添加到非标准类型。

    从 3.14 版起已弃用，将在 3.16 版中移除: 无效的、未点分隔的扩展名在 Python 3.16 中将引发 `ValueError`。

## 命令行用法

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

  猜测扩展名而不是类型。

-l
--lenient

  此外，还可以搜索一些常见但非标准的类型。

默认情况下，脚本将MIME类型转换为文件扩展名。但是，如果指定了``--extension``，它会将文件扩展名转换为MIME类型。

对于每个``type``条目，脚本将一行写入标准输出流。如果出现未知类型，则将错误消息写入标准错误流，并返回代码``1``退出。

## 命令行示例

以下是一些 `mimetypes` 命令行界面的典型用法示例：

    $ # 通过文件名获取MIME类型
    $ python -m mimetypes filename.png
    type: image/png encoding: None

    $ # 通过URL获取MIME类型
    $ python -m mimetypes https://example.com/filename.txt
    type: text/plain encoding: None

    $ # 获取一个复杂的MIME类型
    $ python -m mimetypes filename.tar.gz
    type: application/x-tar encoding: gzip

    $ # 获取罕见文件扩展名的MIME类型
    $ python -m mimetypes filename.pict
    error: unknown extension of filename.pict

    $ # 现在看看Python内置的扩展数据库
    $ python -m mimetypes --lenient filename.pict
    type: image/pict encoding: None

    $ # 通过MIME类型获取文件扩展名
    $ python -m mimetypes --extension text/javascript
    .js

    $ # 通过罕见的MIME类型获取文件扩展名
    $ python -m mimetypes --extension text/xul
    error: unknown type text/xul

    $ # 现在再次查看扩展数据库
    $ python -m mimetypes --extension --lenient text/xul
    .xul

    $ # 尝试输入未知的文件扩展名
    $ 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

    $ # 尝试输入未知的MIME类型
    $ python -m mimetypes --extension audio/aac audio/opus audio/future audio/x-wav
    .aac
    .opus
    error: unknown type audio/future