mimetypes — сопоставление имен файлов с типами MIME

Исходный код: Lib/mimetypes.py

Модуль mimetypes преобразует имя файла или URL в тип MIME, связанный с расширением файла, и наоборот. Предусмотрено преобразование имени файла в тип MIME и типа MIME в расширение файла; кодировки не поддерживаются при последнем преобразовании.

Модуль предоставляет один класс и ряд вспомогательных функций. Функции являются обычным интерфейсом к этому модулю, но некоторым приложениям может быть полезен и класс.

Описанные ниже функции предоставляют основной интерфейс этого модуля. Если модуль не был инициализирован, они вызовут init(), если используют данные, которые подготавливает init().

mimetypes.guess_type(url, strict=True)

Определяет тип файла по его имени, пути или URL, заданному параметром url. URL может быть строкой или объектом, подобным пути.

Возвращаемое значение — кортеж (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 в виде объекта, подобного пути.

Устарело без удаления с версии 3.13: Передача пути к файлу вместо URL. Используйте для этого guess_file_type().

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

Определяет тип файла по его пути, заданному параметром path. Функция похожа на guess_type(), но принимает путь вместо URL. Путь может быть строкой, объектом bytes или объектом, подобным пути.

Добавлено в версии 3.13.

mimetypes.guess_all_extensions(type, strict=True)

Определяет расширения файла по его типу MIME, заданному параметром type. Возвращаемое значение — список строк со всеми возможными расширениями имен файлов, включая начальную точку ('.'). Не гарантируется, что расширения были связаны с каким-либо конкретным потоком данных, но функции guess_type() и guess_file_type() сопоставят их с типом MIME type.

Необязательный аргумент strict имеет то же значение, что и в функции guess_type().

mimetypes.guess_extension(type, strict=True)

Определяет расширение файла по его типу MIME, заданному параметром type. Возвращаемое значение — строка с расширением имени файла, включая начальную точку ('.'). Не гарантируется, что расширение было связано с каким-либо конкретным потоком данных, но функции 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(file)

Загружает карту типов из файла с именем file, если такой файл существует. file должен быть строкой с именем файла для чтения. Карта типов возвращается в виде словаря, сопоставляющего расширения файлов, включая начальную точку ('.'), со строками вида 'type/subtype'. Если файл не существует или его не удается прочитать, возвращается 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'

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

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