"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"，或者为 "'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 版起已处于 Soft deprecated 状态: Passing a file path
   instead of URL. Use "guess_file_type()" for this.

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)

   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 类型，
   否则添加到非标准类型。

   自 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 对象
==============

"MimeTypes" 类可以被用于那些需要多个 MIME 类型数据库的应用程序；它提供
了 "mimetypes" 模块所提供的类似接口。

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 类型信息。

      适用范围: Windows.

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

      Added in version 3.2.

   add_type(type, ext, strict=True)

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

      当 *strict* 为 "True" 时（默认值），映射将被添加到官方 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" 模块可以在命令行下作为脚本来执行。

   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
