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' است که برای سرآیند content-type در MIME قابل استفاده است.

encoding is None for no encoding or the name of the program used to encode (e.g. compress or gzip). The encoding is suitable for use as a Content-Encoding header, not as a Content-Transfer-Encoding header. The mappings are table driven. Encoding suffixes are case-sensitive. Suffix mappings and type suffixes are first tried case-sensitively, then case-insensitively.

آرگومان اختیاری strict پرچمی است که مشخص می‌کند فهرست انواع MIME شناخته‌شده تنها به انواع رسمی ثبت‌شده در IANA محدود است یا خیر. با این حال، رفتار این ماژول به سیستم‌عامل زیرین نیز وابسته است. تنها انواع پرونده‌ای که سیستم‌عامل آن‌ها را بشناسد یا به‌صراحت در پایگاه داده‌ی داخلی پایتون ثبت شده باشند، قابل شناسایی هستند. هنگامی که strict برابر True باشد (پیش‌فرض)، تنها انواع IANA پشتیبانی می‌شوند؛ هنگامی که strict برابر False باشد، برخی دیگر از انواع MIME غیراستاندارد اما رایج نیز شناسایی می‌شوند.

تغییر یافته در نسخه‌ی 3.8: پشتیبانی از اینکه url یک path-like object باشد، افزوده شد.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.13: ارسال مسیر پرونده به‌جای URL. برای این منظور از guess_file_type() استفاده کنید.

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

نوع یک پرونده را بر اساس مسیر آن، که توسط path داده شده است، حدس می‌زند. مشابه تابع guess_type() است، اما به‌جای URL، یک مسیر را می‌پذیرد. مسیر می‌تواند یک رشته، یک شیء bytes یا یک path-like object باشد.

اضافه شده در نسخه‌ی 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 گرفته می‌شوند؛ در ویندوز، تنظیمات رجیستری جاری بارگذاری می‌شوند. هر پرونده نام‌برده‌شده در files یا knownfiles بر پرونده‌های نام‌برده‌شده پیش از خود اولویت دارد. فراخوانی مکرر init() مجاز است.

مشخص کردن یک فهرست خالی برای files مانع از اعمال پیش‌فرض‌های سیستم می‌شود: تنها مقادیر شناخته‌شده از یک فهرست توکار موجود خواهند بود.

اگر files برابر None باشد، ساختار داده داخلی به‌طور کامل با مقدار پیش‌فرض اولیه خود بازسازی می‌شود. این یک عملیات پایدار است و در صورت فراخوانی چندین بار، نتایج یکسانی تولید می‌کند.

تغییر یافته در نسخه‌ی 3.2: پیش‌تر، تنظیمات رجیستری ویندوز نادیده گرفته می‌شد.

mimetypes.read_mime_types(file)

در صورت وجود، نگاشت نوع (type map) موجود در پرونده‌ای که نامش با file مشخص شده است را بارگذاری می‌کند. file باید یک رشته باشد که نام پرونده برای خواندن را مشخص می‌کند. نگاشت نوع به‌عنوان یک دیکشنری برگردانده می‌شود که پسوندهای پرونده، شامل نقطه آغازین ('.')، را به رشته‌هایی با قالب 'type/subtype' نگاشت می‌کند. اگر پرونده وجود نداشته باشد یا قابل خواندن نباشد، 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 '.'.

Registered lower-case extensions are matched case-insensitively.

هنگامی که 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

فهرستی از نام پرونده‌های نگاشت نوع (type map) که معمولاً نصب می‌شوند. این پرونده‌ها معمولاً 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-type داشته باشند مفید باشد؛ این کلاس رابطی مشابه رابط ماژول mimetypes ارائه می‌دهد.

class mimetypes.MimeTypes(filenames=(), strict=True)

این کلاس یک پایگاه‌داده نوع‌های MIME را نشان می‌دهد. به طور پیش‌فرض، این کلاس دسترسی به همان پایگاه‌داده‌ای را فراهم می‌کند که بقیه این ماژول از آن استفاده می‌کند. پایگاه‌داده اولیه از جداول نوع MIME توکار پایتون ایجاد شده است. می‌توان آن را با بارگذاری پرونده‌های اضافی به سبک mime.types در پایگاه‌داده با استفاده از متدهای read() یا readfp() گسترش داد. دیکشنری‌های نگاشت نیز می‌توانند قبل از بارگذاری داده‌های اضافی پاک شوند، اگر داده‌های پیش‌فرض مورد نظر نباشند.

پارامتر اختیاری filenames می‌تواند برای بارگذاری پرونده‌های اضافی «روی» پایگاه داده پیش‌فرض استفاده شود.

suffix_map

دیکشنری نگاشت پسوندها به پسوندها. این برای امکان شناسایی پرونده‌های کدگذاری‌شده استفاده می‌شود که در آن‌ها کدگذاری و نوع با یک پسوند یکسان نشان داده شده‌اند. برای مثال، پسوند .tgz به .tar.gz نگاشت شده است تا امکان شناسایی جداگانه کدگذاری و نوع فراهم شود. این با چند مقدار از پیش تعریف‌شده مقداردهی اولیه شده است.

encodings_map

دیکشنری نگاشت پسوندهای نام پرونده به نوع‌های کدگذاری. این با چند مقدار از پیش تعریف‌شده مقداردهی اولیه شده است.

types_map

تاپلی حاوی دو دیکشنری، نگاشت پسوندهای نام پرونده به نوع‌های MIME: اولین دیکشنری برای نوع‌های غیراستاندارد و دومین دیکشنری برای نوع‌های استاندارد است. آن‌ها با چند مقدار از پیش تعریف‌شده و اطلاعات نوع MIME بارگذاری شده از پرونده‌هایی که توسط آرگومان filenames مشخص شده‌اند، مقداردهی اولیه شده‌اند.

types_map_inv

تاپلی حاوی دو دیکشنری، نگاشت نوع‌های MIME به یک فهرست از پسوندهای نام پرونده: اولین دیکشنری برای نوع‌های غیراستاندارد و دومین دیکشنری برای نوع‌های استاندارد است. آن‌ها با چند مقدار از پیش تعریف‌شده و اطلاعات نوع MIME بارگذاری شده از پرونده‌هایی که توسط آرگومان filenames مشخص شده‌اند، مقداردهی اولیه شده‌اند.

guess_extension(type, strict=True)

مشابه تابع guess_extension()، با استفاده از جدول‌های ذخیره‌شده به‌عنوان بخشی از شیء.

guess_type(url, strict=True)

مشابه تابع guess_type()، با استفاده از جدول‌های ذخیره‌شده به‌عنوان بخشی از شیء.

guess_file_type(path, *, strict=True)

مشابه تابع guess_file_type()، با استفاده از جدول‌های ذخیره‌شده به‌عنوان بخشی از شیء.

اضافه شده در نسخه‌ی 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.

اگر strict برابر True باشد، اطلاعات به فهرست انواع استاندارد افزوده می‌شود، در غیر این صورت به فهرست انواع غیراستاندارد افزوده می‌شود.

اضافه شده در نسخه‌ی 3.2.

add_type(type, ext, strict=True)

یک نگاشت از نوع MIME type به پسوند ext اضافه کنید. پسوندهای معتبر با '.' شروع می‌شوند یا خالی هستند. هنگامی که پسوند از قبل شناخته شده باشد، نوع جدید جایگزین نوع قدیمی خواهد شد. هنگامی که نوع از قبل شناخته شده باشد، پسوند به فهرست پسوندهای شناخته‌شده اضافه خواهد شد.

Registered lower-case extensions are matched case-insensitively.

هنگامی که 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 آمده است:

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