mimetypes — Map filenames to MIME types

Вихідний код: Lib/mimetypes.py

---

Модуль mimetypes перетворює назву файлу або URL-адресу на тип MIME, пов’язаний із розширенням назви файлу. Передбачено перетворення імені файлу в тип MIME та типу MIME у розширення імені файла; кодування не підтримуються для останнього перетворення.

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

Описані нижче функції забезпечують основний інтерфейс для цього модуля. Якщо модуль не було ініціалізовано, вони викличуть init(), якщо вони покладаються на інформацію, встановлену init().

mimetypes.guess_type(url, strict=True)

Вгадайте тип файлу на основі його назви файлу, шляху або URL-адреси, заданої url. URL-адреса може бути рядком або path-like object.

Поверненим значенням є кортеж (тип, кодування), де type є None, якщо тип неможливо вгадати (відсутній або невідомий суфікс), або рядок у формі 'type/ subtype'', який можна використовувати для заголовка MIME content-type.

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 має бути послідовністю імен файлів, які слід використовувати для доповнення карти типів за замовчуванням. Якщо опущено, імена файлів для використання беруться з knownfiles; у Windows завантажуються поточні параметри реєстру. Кожен файл, названий у files або knownfiles, має пріоритет над файлами, названими перед ним. Повторний виклик init() дозволено.

Якщо вказати порожній список для файлів, системні параметри за замовчуванням не будуть застосовані: із вбудованого списку будуть присутні лише добре відомі значення.

Якщо files має значення None, внутрішня структура даних повністю перебудовується до початкового значення за замовчуванням. Це стабільна операція, яка дає однакові результати при багаторазовому виклику.

Змінено в версії 3.2: Раніше параметри реєстру Windows ігнорувалися.

mimetypes.read_mime_types(filename)

Завантажте карту типів, указану у файлі filename, якщо вона існує. Карта типів повертається як словник, який зіставляє розширення імен файлів, включаючи початкову крапку ('.''), на рядки у формі 'тип/підтип'. Якщо файл 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 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: перший словник призначений для нестандартних типів, а другий — для стандартних типів. Вони ініціалізуються 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)

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, інформацію буде додано до списку стандартних типів, інакше до списку нестандартних типів.

readfp(fp, strict=True)

Завантажте інформацію про тип MIME із відкритого файлу fp. Файл повинен мати формат стандартних файлів mime.types.

Якщо strict має значення True, інформацію буде додано до списку стандартних типів, інакше – до списку нестандартних типів.

read_windows_registry(strict=True)

Завантажте інформацію про тип MIME з реєстру Windows.

Availability: Windows.

Якщо strict має значення True, інформацію буде додано до списку стандартних типів, інакше – до списку нестандартних типів.

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, інакше – до нестандартних.

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

Command-line usage

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

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

The following options are accepted:

-h

--help

Show the help message and exit.

-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.

Command-line example

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