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 برای حالت بدون کدگذاری
Noneاست، یا نام برنامهی استفادهشده برای کدگذاری (برای مثال compress یا gzip). این کدگذاری برای استفاده بهعنوان سرآیند Content-Encoding مناسب است، نه بهعنوان سرآیند Content-Transfer-Encoding. نگاشتها جدولمحور هستند. پسوندهای کدگذاری به بزرگی و کوچکی حروف حساس هستند؛ پسوندهای نوع ابتدا با حساسیت به بزرگی و کوچکی حروف آزمایش میشوند، سپس بدون حساسیت به بزرگی و کوچکی حروف.آرگومان اختیاری 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)¶
یک نگاشت از نوع MIME type به پسوند ext اضافه میکند. هنگامی که پسوند از قبل شناختهشده باشد، نوع جدید جایگزین نوع قدیمی میشود. هنگامی که نوع از قبل شناختهشده باشد، پسوند به فهرست پسوندهای شناختهشده اضافه میشود.
هنگامی که strict برابر
Trueباشد (حالت پیشفرض)، نگاشت به انواع MIME رسمی اضافه خواهد شد؛ در غیر این صورت به انواع غیراستاندارد اضافه میشود.
- 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)¶
This class represents a MIME-types database. By default, it provides access to the same database as the rest of this module. The initial database is created from Python's built-in MIME type tables. It may be extended by loading additional
mime.types-style files into the database using theread()orreadfp()methods. The mapping dictionaries may also be cleared before loading additional data if the default data is not desired.پارامتر اختیاری filenames میتواند برای بارگذاری پروندههای اضافی «روی» پایگاه داده پیشفرض استفاده شود.
- suffix_map¶
Dictionary mapping suffixes to suffixes. This is used to allow recognition of encoded files for which the encoding and the type are indicated by the same extension. For example, the
.tgzextension is mapped to.tar.gzto allow the encoding and type to be recognized separately. This is initialized with some predefined values.
- encodings_map¶
Dictionary mapping filename extensions to encoding types. This is initialized with some predefined values.
- types_map¶
Tuple containing two dictionaries, mapping filename extensions to MIME types: the first dictionary is for the non-standards types and the second one is for the standard types. They are initialized with some predefined values and MIME type information loaded from files specified by the filenames argument.
- types_map_inv¶
Tuple containing two dictionaries, mapping MIME types to a list of filename extensions: the first dictionary is for the non-standards types and the second one is for the standard types. They are initialized with some predefined values and MIME type information loaded from files specified by the filenames argument.
- 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 اضافه کنید. پسوندهای معتبر با '.' شروع میشوند یا خالی هستند. هنگامی که پسوند از قبل شناخته شده باشد، نوع جدید جایگزین نوع قدیمی خواهد شد. هنگامی که نوع از قبل شناخته شده باشد، پسوند به فهرست پسوندهای شناختهشده اضافه خواهد شد.
هنگامی که strict برابر
Trueباشد (حالت پیشفرض)، نگاشت به انواع MIME رسمی اضافه خواهد شد؛ در غیر این صورت به انواع غیراستاندارد اضافه میشود.منسوخ شده از نسخهی 3.14, در نسخهی 3.16 حذف خواهد شد: پسوندهای نامعتبر و بدون نقطه، در پایتون 3.16 باعث پرتاب یک
ValueErrorخواهند شد.
استفاده از خط فرمان¶
ماژول mimetypes میتواند بهعنوان یک اسکریپت از خط فرمان اجرا شود.
python -m mimetypes [-h] [-e] [-l] type [type ...]
گزینههای زیر پذیرفته میشوند:
بهطور پیشفرض، اسکریپت انواع 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