base64 --- کدگذاریهای Base16، Base32، Base64 و Base85 برای داده¶
کد منبع: Lib/base64.py
این ماژول توابعی برای کدگذاری دادههای دودویی به نویسههای قابلچاپ ASCII و کدگشایی چنین کدگذاریهایی به دادههای دودویی فراهم میکند. این ماژول شامل کدگذاریهای مشخصشده در RFC 4648 (Base64، Base32 و Base16)، کدگذاری Base85 مشخصشده در PDF 2.0، و گونههای غیراستاندارد Base85 است که در جاهای دیگر استفاده میشوند.
این ماژول دو رابط ارائه میدهد. رابط مدرن از کدگذاری اشیاء شبهبایت به bytes ASCII، و کدگشایی اشیاء شبهبایت یا رشتههای حاوی ASCII به bytes پشتیبانی میکند. هر دو الفبای base-64 تعریفشده در RFC 4648 (معمولی، و امن برای URL و سامانه فایلبندی) پشتیبانی میشوند.
رابط قدیمی از کدگشایی از رشتهها پشتیبانی نمیکند، اما توابعی برای کدگذاری و کدگشایی به و از اشیای پرونده ارائه میدهد. این رابط فقط از الفبای استاندارد Base64 پشتیبانی میکند و مطابق RFC 2045 هر ۷۶ نویسه یک خط جدید اضافه میکند. توجه داشته باشید که اگر به دنبال پشتیبانی از RFC 2045 هستید، احتمالاً بهتر است در عوض به بسته email نگاه کنید.
تغییر یافته در نسخهی 3.3: توابع کدگشایی رابط مدرن اکنون رشتههای یونیکود فقط ASCII را میپذیرند.
تغییر یافته در نسخهی 3.4: اکنون تمامی توابع کدگذاری و کدگشایی این ماژول، هر شیء شبهبایت را میپذیرند. پشتیبانی از Ascii85/Base85 افزوده شد.
کدگذاریهای RFC 4648¶
کدگذاریهای RFC 4648 برای کدگذاری دادههای دودویی مناسب هستند، بهطوری که بتوان آنها را بهصورت امن از طریق ایمیل ارسال کرد، بهعنوان بخشهایی از URLها استفاده کرد، یا بهعنوان بخشی از یک درخواست HTTP POST قرار داد.
- base64.b64encode(s, altchars=None, *, padded=True, wrapcol=0)¶
bytes-like object s را با استفاده از Base64 کدگذاری میکند و
bytesکدگذاریشده را برمیگرداند.altchars اختیاری باید یک شیء شبهبایت به طول ۲ باشد که الفبای جایگزین را برای نویسههای
+و/مشخص میکند. این به یک برنامه اجازه میدهد که برای مثال، رشتههای Base64 امن برای URL یا سیستم پرونده تولید کند. پیشفرضNoneاست، که در این صورت از الفبای استاندارد Base64 استفاده میشود.If padded is true (default), pad the encoded data with the '=' character to a size multiple of 4. If padded is false, do not add the pad characters.
If wrapcol is non-zero, insert a newline (
b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not insert any newlines.تغییر یافته در نسخهی 3.15: Added the padded and wrapcol parameters.
- base64.b64decode(s, altchars=None, validate=False, *, padded=True, canonical=False)¶
- base64.b64decode(s, altchars=None, validate=True, *, ignorechars, padded=True, canonical=False)
bytes-like object یا رشتهی ASCII کدگذاریشده با Base64 s را کدگشایی میکند و
bytesکدگشاییشده را برمیگرداند.altchars اختیاری باید یک bytes-like object یا رشتهی ASCII به طول ۲ باشد که الفبای جایگزینی را که بهجای نویسههای
+و/استفاده میشود، مشخص میکند.If padded is true, the last group of 4 base 64 alphabet characters must be padded with the '=' character. If padded is false, padding is neither required nor recognized: the '=' character is not treated as padding but as a non-alphabet character, which means it is silently discarded when validate is false, or causes an
Errorwhen validate is true unless b'=' is included in ignorechars.اگر s بهدرستی پدینگ (padding) نشده باشد، استثنای
binascii.Errorپرتاب میشود.If ignorechars is specified, it should be a bytes-like object containing characters to ignore from the input when validate is true. If ignorechars contains the pad character
'=', the pad characters presented before the end of the encoded data and the excess pad characters will be ignored. The default value of validate isTrueif ignorechars is specified,Falseotherwise.If validate is false, characters that are neither in the normal base-64 alphabet nor (if ignorechars is not specified) the alternative alphabet are discarded prior to the padding check, but the
+and/characters keep their meaning if they are not in altchars (they will be discarded in future Python versions).If validate is true, these non-alphabet characters in the input result in a
binascii.Error.If canonical is true, non-zero padding bits are rejected. See
binascii.a2b_base64()for details.برای اطلاعات بیشتر درباره بررسی سختگیرانه base64،
binascii.a2b_base64()را ببینیدتغییر یافته در نسخهی 3.15: Added the canonical, ignorechars, and padded parameters.
منسوخ شده از نسخهی 3.15: Accepting the
+and/characters with an alternative alphabet is now deprecated.
- base64.standard_b64encode(s)¶
bytes-like object s را با استفاده از الفبای استاندارد Base64 کدگذاری میکند و
bytesکدگذاریشده را برمیگرداند.
- base64.standard_b64decode(s)¶
bytes-like object یا رشته ASCII s را با استفاده از الفبای استاندارد Base64 کدگشایی میکند و
bytesکدگشاییشده را برمیگرداند.
- base64.urlsafe_b64encode(s, *, padded=True)¶
Encode bytes-like object s using the URL- and filesystem-safe alphabet, which substitutes
-instead of+and_instead of/in the standard Base64 alphabet, and return the encodedbytes. The result can still contain=if padded is true (default).تغییر یافته در نسخهی 3.15: Added the padded parameter.
- base64.urlsafe_b64decode(s, *, padded=False)¶
با استفاده از الفبای امن برای URL و سامانه فایلبندی، که در الفبای استاندارد Base64 بهجای
+از-و بهجای/از_استفاده میکند، bytes-like object یا رشتهی ASCII s را کدگشایی کنید وbytesکدگشاییشده را برگردانید.تغییر یافته در نسخهی 3.15: Added the padded parameter. Padding of input is no longer required by default.
منسوخ شده از نسخهی 3.15: Accepting the
+and/characters is now deprecated.
- base64.b32encode(s, *, padded=True, wrapcol=0)¶
bytes-like object s را با استفاده از Base32 کدگذاری میکند و
bytesکدگذاریشده را برمیگرداند.If padded is true (default), pad the encoded data with the '=' character to a size multiple of 8. If padded is false, do not add the pad characters.
If wrapcol is non-zero, insert a newline (
b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not add any newlines.تغییر یافته در نسخهی 3.15: Added the padded and wrapcol parameters.
- base64.b32decode(s, casefold=False, map01=None, *, padded=True, ignorechars=b'', canonical=False)¶
bytes-like object یا رشته ASCII s را که با Base32 کدگذاریشده است، کدگشایی میکند و
bytesکدگشاییشده را برمیگرداند.casefold اختیاری پرچمی است که مشخص میکند آیا الفبای کوچک بهعنوان ورودی قابلقبول است یا خیر. به دلایل امنیتی، مقدار پیشفرض
Falseاست.RFC 4648 امکان نگاشت اختیاری رقم ۰ (صفر) به حرف O (اوه) و نگاشت اختیاری رقم ۱ (یک) به حرف I (آی) یا حرف L (اِل) را فراهم میکند. آرگومان اختیاری map01، هنگامی که
Noneنباشد، مشخص میکند که رقم ۱ باید به کدام حرف نگاشت شود (هنگامی که map01Noneنباشد، رقم ۰ همیشه به حرف O نگاشت میشود). بهدلایل امنیتی، مقدار پیشفرضNoneاست، تا ۰ و ۱ در ورودی مجاز نباشند.If padded is true, the last group of 8 base 32 alphabet characters must be padded with the '=' character. If padded is false, padding is neither required nor recognized: the '=' character is not treated as padding but as a non-alphabet character, which means it raises an
Errorunless b'=' is included in ignorechars.ignorechars should be a bytes-like object containing characters to ignore from the input.
If canonical is true, non-zero padding bits are rejected. See
binascii.a2b_base32()for details.اگر s بهدرستی پد (padding) نشده باشد یا نویسههای خارج از الفبا در ورودی وجود داشته باشند، یک
binascii.Errorپرتاب میشود.تغییر یافته در نسخهی 3.15: Added the canonical, ignorechars, and padded parameters.
- base64.b32hexencode(s, *, padded=True, wrapcol=0)¶
مشابه
b32encode()است، اما از الفبای مبنای شانزده توسعهیافته (Extended Hex Alphabet) استفاده میکند، همانطور که در RFC 4648 تعریف شده است.اضافه شده در نسخهی 3.10.
تغییر یافته در نسخهی 3.15: Added the padded and wrapcol parameters.
- base64.b32hexdecode(s, casefold=False, *, padded=True, ignorechars=b'', canonical=False)¶
مشابه
b32decode()است، اما از الفبای مبنای شانزده توسعهیافته (Extended Hex Alphabet) تعریفشده در RFC 4648 استفاده میکند.این نسخه اجازهی نگاشت رقم ۰ (صفر) به حرف O (اوه) و نگاشت رقم ۱ (یک) به حرف I (آی) یا حرف L (اِل) را نمیدهد؛ همهی این نویسهها در الفبای مبنای شانزده توسعهیافته (Extended Hex Alphabet) گنجانده شدهاند و قابل تعویض با یکدیگر نیستند.
اضافه شده در نسخهی 3.10.
تغییر یافته در نسخهی 3.15: Added the canonical, ignorechars, and padded parameters.
- base64.b16encode(s, *, wrapcol=0)¶
شیء bytes-like object s را با استفاده از Base16 کدگذاری کنید و
bytesکدگذاریشده را برگردانید.If wrapcol is non-zero, insert a newline (
b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not add any newlines.تغییر یافته در نسخهی 3.15: Added the wrapcol parameter.
- base64.b16decode(s, casefold=False, *, ignorechars=b'')¶
کدگشایی bytes-like object یا رشتهی ASCII s کدگذاریشده با Base16 و برگرداندن
bytesکدگشاییشده.casefold اختیاری پرچمی است که مشخص میکند آیا الفبای کوچک بهعنوان ورودی قابلقبول است یا خیر. به دلایل امنیتی، مقدار پیشفرض
Falseاست.ignorechars should be a bytes-like object containing characters to ignore from the input.
اگر s بهدرستی پد (padding) نشده باشد یا نویسههای خارج از الفبا در ورودی وجود داشته باشند، یک
binascii.Errorپرتاب میشود.تغییر یافته در نسخهی 3.15: Added the ignorechars parameter.
کدگذاریهای Base85¶
کدگذاری Base85 خانوادهای از الگوریتمها است که ۴ بایت را با ۵ نویسهی ASCII بازنمایی میکنند. این کدگذاری در ابتدا در ابزار btoa(1) یونیکس پیادهسازی شد؛ نسخهای از آن بعداً توسط Adobe در زبان PostScript پذیرفته شد و در PDF 2.0 (ISO 32000-2) استاندارد شده است. این نسخه، در هر دو گونهی btoa و PDF خود، توسط a85encode() پیادهسازی شده است.
نسخهای جداگانه، با استفاده از مجموعه نویسه خروجی متفاوت، بهعنوان شوخی روز اول آوریل در RFC 1924 تعریف شد، اما اکنون توسط Git و سایر نرمافزارها استفاده میشود. این نسخه توسط b85encode() پیادهسازی شده است.
در نهایت، نسخه سومی، با استفاده از مجموعهی نویسهی خروجی دیگری که برای درج امن در رشتههای زبان برنامهنویسی طراحی شده است، توسط ZeroMQ تعریف شده و در اینجا توسط z85encode() پیادهسازی شده است.
توابع موجود در این ماژول در نحوهی مدیریت موارد زیر تفاوت دارند:
اینکه آیا باید نشانگرهای دربرگیرندهی
<~و~>را گنجاند و انتظار داشت.اینکه آیا ورودی به چند خط شکسته شود یا خیر.
مجموعهای از نویسههای ASCII که برای کدگذاری استفاده میشوند.
کدگذاریهای فشرده برای دنبالههایی از فاصلهها و بایتهای null.
کدگذاری بایتهای پدینگ صفر (zero-padding) اعمالشده بر ورودی.
برای اطلاعات بیشتر، به مستندات هر یک از توابع مراجعه کنید.
- base64.a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)¶
bytes-like object b را با استفاده از Ascii85 کدگذاری میکند و
bytesکدگذاریشده را برمیگرداند.foldspaces یک پرچم اختیاری است که بهجای ۴ فاصلهی متوالی (ASCII 0x20)، از دنبالهی کوتاه ویژهی 'y' استفاده میکند؛ همانطور که توسط 'btoa' پشتیبانی میشود. این قابلیت توسط کدگذاری استاندارد استفادهشده در PDF پشتیبانی نمیشود.
If wrapcol is non-zero, insert a newline (
b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not insert any newlines.pad مشخص میکند که آیا پدینگ صفر (zero-padding) اعمالشده به انتهای ورودی بهطور کامل در کدگذاری خروجی حفظ میشوند، همانطور که
btoaاین کار را انجام میدهد و خروجیای تولید میکند که دقیقاً مضربی از ۵ بایت است. این بخشی از کدگذاری استاندارد استفادهشده در PDF نیست، زیرا طول داده را حفظ نمیکند.adobe تعیین میکند که آیا دنبالهی بایتی کدگذاریشده با
<~و~>محصور شود یا خیر، همانگونه که در یک لفظی رشتهای PostScript base-85 وجود دارد. توجه داشته باشید که جریانهای ASCII85Decode در اسناد PDF باید با~>پایان یابند، اما نباید با<~آغاز شوند.اضافه شده در نسخهی 3.4.
- base64.a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\x0b', canonical=False)¶
bytes-like object یا رشتهی ASCII b را که با Ascii85 کدگذاریشده است، کدگشایی میکند و
bytesکدگشاییشده را برمیگرداند.foldspaces پرچمی است که مشخص میکند آیا دنبالهی کوتاه 'y' باید بهعنوان مخففی برای ۴ فاصلهی متوالی (ASCII 0x20) پذیرفته شود یا خیر. این قابلیت در کدگذاری استاندارد Ascii85 که در PDF و PostScript استفاده میشود، پشتیبانی نمیشود.
adobe تعیین میکند که نشانگرهای
<~و~>وجود داشته باشند. اگرچه نشانگر ابتدایی<~الزامی نیست، اما ورودی باید با~>پایان یابد، در غیر این صورت یکValueErrorپرتاب میشود.ignorechars should be a bytes-like object containing characters to ignore from the input. This should only contain whitespace characters, and by default contains all whitespace characters in ASCII.
If canonical is true, non-canonical encodings are rejected. See
binascii.a2b_ascii85()for details.اضافه شده در نسخهی 3.4.
تغییر یافته در نسخهی 3.15: Added the canonical parameter. Single-character final groups are now always rejected as encoding violations.
- base64.b85encode(b, pad=False, *, wrapcol=0)¶
شیء شبهبایت (bytes-like object) b را با استفاده از base85 (که برای مثال در diffهای دودویی بهسبک git استفاده میشود) کدگذاری میکند و
bytesکدگذاریشده را برمیگرداند.ورودی با
b'\0'پر میشود تا طول آن پیش از کدگذاری مضربی از ۴ بایت باشد. اگر pad درست باشد، تمام نویسههای حاصل در خروجی نگه داشته میشوند؛ خروجی همیشه مضربی از ۵ بایت خواهد بود، و بنابراین ممکن است طول داده هنگام کدگشایی حفظ نشود.If wrapcol is non-zero, insert a newline (
b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not add any newlines.اضافه شده در نسخهی 3.4.
تغییر یافته در نسخهی 3.15: Added the wrapcol parameter.
- base64.b85decode(b, *, ignorechars=b'', canonical=False)¶
bytes-like object یا رشتهی ASCII b را که با base85 کدگذاریشده است، کدگشایی میکند و
bytesکدگشاییشده را برمیگرداند.ignorechars should be a bytes-like object containing characters to ignore from the input.
If canonical is true, non-canonical encodings are rejected. See
binascii.a2b_base85()for details.اضافه شده در نسخهی 3.4.
تغییر یافته در نسخهی 3.15: Added the canonical and ignorechars parameters. Single-character final groups are now always rejected as encoding violations.
- base64.z85encode(s, pad=False, *, wrapcol=0)¶
bytes-like object s را با استفاده از Z85 (همانطور که در ZeroMQ استفاده میشود) کدگذاری کنید و
bytesکدگذاریشده را برگردانید.The input is padded with
b'\0'so its length is a multiple of 4 bytes before encoding. If pad is true, all the resulting characters are retained in the output, which will always be a multiple of 5 bytes, as required by the ZeroMQ standard.If wrapcol is non-zero, insert a newline (
b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not add any newlines.اضافه شده در نسخهی 3.13.
تغییر یافته در نسخهی 3.15: The pad parameter was added.
تغییر یافته در نسخهی 3.15: Added the wrapcol parameter.
- base64.z85decode(s, *, ignorechars=b'', canonical=False)¶
bytes-like object یا رشته ASCII s کدگذاریشده با Z85 را کدگشایی میکند و
bytesکدگشاییشده را برمیگرداند.ignorechars should be a bytes-like object containing characters to ignore from the input.
If canonical is true, non-canonical encodings are rejected. See
binascii.a2b_base85()for details.اضافه شده در نسخهی 3.13.
تغییر یافته در نسخهی 3.15: Added the canonical and ignorechars parameters. Single-character final groups are now always rejected as encoding violations.
رابط قدیمی¶
- base64.decode(input, output)¶
محتوای پرونده دودویی input را کدگشایی کنید و دادههای دودویی حاصل را در پرونده output بنویسید. input و output باید اشیای پرونده باشند. input تا زمانی خوانده میشود که
input.readline()یک شیء bytes خالی برگرداند.
- base64.decodebytes(s)¶
bytes-like object s را، که باید شامل یک یا چند خط دادهی کدگذاریشده به base64 باشد، کدگشایی میکند و
bytesکدگشاییشده را برمیگرداند.اضافه شده در نسخهی 3.1.
- base64.encode(input, output)¶
محتویات پرونده دودویی input را کدگذاری کنید و دادههای حاصل کدگذاریشده با base64 را در پرونده output بنویسید. input و output باید اشیای پرونده باشند. input تا زمانی خوانده میشود که
input.read()یک شیء بایت خالی برگرداند.encode()یک نویسه خط جدید (b'\n') را پس از هر ۷۶ بایت از خروجی درج میکند و همچنین اطمینان حاصل میکند که خروجی همیشه با یک خط جدید پایان مییابد، مطابق RFC 2045 (MIME).
- base64.encodebytes(s)¶
شیء شبهبایت s را، که میتواند حاوی دادههای دودویی دلخواه باشد، کدگذاری میکند و
bytesحاوی دادههای کدگذاریشده با base64 را برمیگرداند؛ بهگونهای که سطرهای جدید (b'\n') پس از هر ۷۶ بایت از خروجی درج شوند و اطمینان حاصل شود که یک خط جدید پایانی وجود دارد، مطابق RFC 2045 (MIME).اضافه شده در نسخهی 3.1.
نمونهای از استفاده از ماژول:
>>> import base64
>>> encoded = base64.b64encode(b'data to be encoded')
>>> encoded
b'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
b'data to be encoded'
ملاحظات امنیتی¶
بخش ملاحظات امنیتی جدیدی به RFC 4648 (بخش ۱۲) افزوده شده است؛ توصیه میشود بخش امنیتی را برای هر کدی که در محیط عملیاتی مستقر شده است، بازبینی کنید.
همچنین ملاحظه نمائید
- ماژول
binascii ماژول پشتیبانی شامل تبدیلهای ASCII به دودویی و دودویی به ASCII.
- RFC 1521 - MIME (Multipurpose Internet Mail Extensions) بخش یکم: سازوکارهایی برای تعیین و توصیف قالب بدنههای پیام اینترنتی
بخش ۵.۲، «Base64 Content-Transfer-Encoding»، تعریف کدگذاری base64 را ارائه میدهد.
- ISO 32000-2 قالب سند قابلحمل - بخش ۲: PDF 2.0
بخش 7.4.3، «ASCII85Decode Filter»، تعریف کدگذاری Ascii85 استفادهشده در PDF و PostScript را ارائه میدهد، از جمله مجموعه نویسههای خروجی و جزئیات حفظ طول داده با استفاده از پدینگ صفر (zero-padding) و گروههای خروجی جزئی.
- ZeroMQ RFC 32/Z85
بخش «مشخصات رسمی» مجموعه نویسههای مورد استفاده در Z85 را ارائه میدهد.