binascii --- تبدیل بین دادههای دودویی و ASCII¶
ماژول binascii شامل تعدادی متد برای تبدیل میان دادههای دودویی و بازنماییهای دودویی مختلف کدگذاریشده با ASCII است. بهطور معمول، شما این توابع را مستقیماً استفاده نمیکنید، بلکه در عوض از ماژولهای پوششی مانند base64 استفاده میکنید. ماژول binascii شامل توابع سطح پایینی است که برای سرعت بیشتر به زبان C نوشته شدهاند و توسط ماژولهای سطح بالاتر استفاده میشوند.
نکته
توابع a2b_* رشتههای یونیکدی را میپذیرند که فقط شامل نویسههای ASCII باشند. سایر توابع فقط اشیاء شبهبایت (مانند bytes، bytearray و اشیاء دیگری که از پروتکل بافر پشتیبانی میکنند) را میپذیرند.
تغییر یافته در نسخهی 3.3: رشتههای یونیکدی که فقط شامل نویسههای ASCII هستند، اکنون توسط توابع a2b_* پذیرفته میشوند.
ماژول binascii توابع زیر را تعریف میکند:
- binascii.a2b_uu(string)¶
یک خط منفرد از دادههای uuencoded را به دادههای دودویی تبدیل میکند و دادههای دودویی را برمیگرداند. سطرها معمولاً حاوی ۴۵ بایت (دودویی) هستند، بهجز خط آخر. ممکن است پس از دادههای خط، فضای سفید وجود داشته باشد.
- binascii.b2a_uu(data, *, backtick=False)¶
دادههای دودویی را به سطری از نویسههای ASCII تبدیل میکند؛ مقدار بازگشتی، خط تبدیلشده بههمراه یک نویسه خط جدید است. طول data باید حداکثر 45 باشد. اگر backtick درست باشد، صفرها بهجای فاصلهها با
'`'نمایش داده میشوند.تغییر یافته در نسخهی 3.7: پارامتر backtick افزوده شد.
- binascii.a2b_base64(string, /, *, padded=True, alphabet=BASE64_ALPHABET, strict_mode=False, canonical=False)¶
- binascii.a2b_base64(string, /, *, ignorechars, padded=True, alphabet=BASE64_ALPHABET, strict_mode=True, canonical=False)
یک بلوک از دادههای base64 را دوباره به دودویی تبدیل میکند و دادههای دودویی را برمیگرداند. شما میتوانید بیش از یک خط را در هر بار ارسال کنید.
پارامتر اختیاری alphabet باید یک
bytesبه طول ۶۴ باشد که الفبای جایگزینی را مشخص میکند.اگر padded مقدار درست باشد، آخرین گروه از ۴ نویسهی الفبای base 64 باید با نویسهی '=' پُر شود. اگر padded مقدار نادرست باشد، پُرکننده نه الزامی است و نه شناخته میشود: نویسهی '=' به عنوان پُرکننده در نظر گرفته نمیشود، بلکه به عنوان یک نویسهی غیرالفبایی در نظر گرفته میشود؛ به این معنا که اگر strict_mode نادرست باشد، بهطور صامت کنار گذاشته میشود، یا اگر strict_mode درست باشد، خطای
Errorرا ایجاد میکند، مگر اینکه b'=' در ignorechars گنجانده شده باشد.اگر ignorechars مشخص شده باشد، باید یک شیء شبهبایت باشد که شامل نویسههایی است که وقتی strict_mode درست است، باید از ورودی نادیده گرفته شوند. اگر ignorechars شامل نویسهی پُرکنندهی
'='باشد، نویسههای پُرکنندهای که قبل از انتهای دادههای کدگذاریشده ارائه شدهاند و نویسههای پُرکنندهی اضافی نادیده گرفته خواهند شد. اگر ignorechars مشخص شده باشد، مقدار پیشفرض strict_mode برابر باTrueو در غیراینصورت برابر باFalseاست.اگر strict_mode درست باشد، فقط دادههای معتبر base64 تبدیل میشوند. دادههای نامعتبر base64 باعث پرتاب
binascii.Errorمیشوند.base64 معتبر:
مطابق با استاندارد RFC 4648.
فقط شامل نویسههای الفبای base64 است.
فاقد داده اضافی پس از پدینگ (padding) است (از جمله پدینگ اضافی، سطرهای جدید و غیره).
با یک پرکننده (padding) شروع نمیشود.
اگر canonical مقدار درست باشد، بیتهای پُرکنندهی غیرصفر در آخرین گروه با خطای
binascii.Errorرد میشوند و کدگذاری کانونیکال همانطور که در بخش ۳.۵ استاندارد RFC 4648 تعریف شده است، اعمال میشود. این بررسی مستقل از strict_mode است.تغییر یافته در نسخهی 3.11: پارامتر strict_mode اضافه شد.
تغییر یافته در نسخهی 3.15: پارامترهای alphabet، canonical، ignorechars و padded اضافه شدند.
- binascii.b2a_base64(data, *, padded=True, alphabet=BASE64_ALPHABET, wrapcol=0, newline=True)¶
دادههای دودویی را به یک یا چند سطر از نویسههای اسکی در کدگذاری base64 تبدیل میکند، همانطور که در RFC 4648 مشخص شده است.
اگر padded مقدار درست باشد (پیشفرض)، دادههای کدگذاریشده را با نویسهی '=' تا اندازهای که ضریبی از ۴ باشد پُر کنید. اگر padded مقدار نادرست باشد، نویسههای پُرکننده را اضافه نکنید.
اگر wrapcol غیرصفر باشد، پس از حداکثر هر wrapcol نویسه، یک نویسهی خط جدید (
b'\n') درج کنید. اگر wrapcol صفر باشد (پیشفرض)، هیچ خط جدیدی درج نکنید.اگر newline درست باشد (پیشفرض)، یک نویسهی خط جدید در انتهای خروجی اضافه خواهد شد.
تغییر یافته در نسخهی 3.6: پارامتر newline افزوده شد.
تغییر یافته در نسخهی 3.15: پارامترهای alphabet، padded و wrapcol اضافه شدند.
- binascii.a2b_ascii85(string, /, *, foldspaces=False, adobe=False, ignorechars=b'', canonical=False)¶
دادههای Ascii85 را به دادههای دودویی تبدیل کرده و دادههای دودویی را برمیگرداند.
دادههای معتبر Ascii85 شامل نویسههایی از الفبای Ascii85 در گروههای پنجتایی هستند (بهجز گروه نهایی که ممکن است دارای دو تا پنج نویسه باشد). هر گروه دادههای دودویی ۳۲ بیتی را در محدودهی شامل
0تا2 ** 32 - 1کدگذاری میکند. نویسهی خاصzبه عنوان فرم کوتاهی از گروه!!!!!پذیرفته میشود که چهار بایت تهی متوالی را کدگذاری میکند. یک گروه نهایی تکنویسهای همیشه به عنوان نقض کدگذاری رد میشود.پارامتر foldspaces پرچمی است که مشخص میکند آیا دنبالهی کوتاه 'y' باید به عنوان میانبری برای ۴ فضای خالی متوالی (اسکی 0x20) پذیرفته شود یا خیر. این ویژگی توسط کدگذاری «استاندارد» Ascii85 پشتیبانی نمیشود.
پارامتر adobe کنترل میکند که آیا دنبالهی بایتهای کدگذاریشده با
<~و~>قاببندی شدهاند یا خیر، درست مانند یک رشتهی لفظی base-85 در PostScript. اگر adobe مقدار درست باشد، وجود یک<~در ابتدا به صورت اختیاری پذیرفته میشود، در حالی که وجود~>در انتها الزامی است و اگر یافت نشود، استثنایbinascii.Errorپرتاب میشود.پارامتر ignorechars باید یک شیء شبهبایت حاوی نویسههایی باشد که باید از ورودی نادیده گرفته شوند. این پارامتر باید فقط شامل نویسههای فاصله باشد.
اگر canonical مقدار درست باشد، کدگذاریهای غیرکانونیکال با
binascii.Errorرد میشوند. در اینجا «کانونیکال» به معنای کدگذاریای است که تابعb2a_ascii85()تولید میکند: علامت اختصاریzباید برای گروههای تماماً صفر (بهجای!!!!!) استفاده شود و گروههای نهایی جزئی باید از همان رقمهای پدینگِ کدگذار استفاده کنند.دادههای نامعتبر Ascii85 استثنای
binascii.Errorرا پرتاب خواهند کرد.اضافه شده در نسخهی 3.15.
- binascii.b2a_ascii85(data, /, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)¶
دادههای دودویی را به یک دنبالهی قالببندیشده از نویسههای اسکی در کدگذاری Ascii85 تبدیل میکند. مقدار بازگشتی، دادههای تبدیلشده است.
پارامتر foldspaces پرچمی اختیاری است که بهجای ۴ فضای خالی متوالی (اسکی 0x20)، از دنبالهی کوتاه ویژهی 'y' استفاده میکند، همانطور که توسط 'btoa' پشتیبانی میشود. این ویژگی توسط کدگذاری «استاندارد» Ascii85 پشتیبانی نمیشود.
اگر wrapcol غیرصفر باشد، پس از حداکثر هر wrapcol نویسه، یک نویسهی خط جدید (
b'\n') درج کنید. اگر wrapcol صفر باشد (پیشفرض)، هیچ خط جدیدی درج نکنید.اگر pad مقدار درست باشد، پدینگ صفر اعمالشده به انتهای ورودی بهطور کامل در کدگذاری خروجی حفظ میشود، درست مانند کاری که
btoaانجام میدهد، و در نتیجه خروجی دقیقاً ضریبی از ۵ بایت خواهد بود. این مورد بخشی از کدگذاری استاندارد مورداستفاده در PDF نیست، زیرا طول دادهها را حفظ نمیکند.پارامتر adobe کنترل میکند که آیا دنبالهی بایتهای کدگذاریشده با
<~و~>قاببندی شدهاند یا خیر، درست مانند یک رشتهی لفظی base-85 در PostScript. توجه داشته باشید که اگرچه جریانهای ASCII85Decode در اسناد PDF باید با~>خاتمه یابند، اما نباید از<~در ابتدا استفاده کنند.اضافه شده در نسخهی 3.15.
- binascii.a2b_base85(string, /, *, alphabet=BASE85_ALPHABET, ignorechars=b'', canonical=False)¶
دادههای Base85 را به دادههای دودویی تبدیل کرده و دادههای دودویی را برمیگرداند. ممکن است بیش از یک سطر در هر بار ارسال شود.
دادههای معتبر Base85 شامل نویسههایی از الفبای Base85 در گروههای پنجتایی هستند (بهجز گروه نهایی که ممکن است از دو تا پنج نویسه داشته باشد). هر گروه ۳۲ بیت از دادههای دودویی را در محدودهی
0تا2 ** 32 - 1(شامل هر دو) کدگذاری میکند. یک گروه نهایی تکنویسهای همیشه به عنوان تخلف از قوانین کدگذاری رد میشود.پارامتر اختیاری alphabet باید یک شیء
bytesبا طول ۸۵ باشد که الفبای جایگزینی را مشخص میکند.پارامتر ignorechars باید یک شیء شبهبایت حاوی نویسههایی باشد که باید از ورودی نادیده گرفته شوند.
اگر canonical مقدار درست باشد، کدگذاریهای غیرکانونیکال با
binascii.Errorرد میشوند. در اینجا «کانونیکال» به معنای کدگذاریای است که تابعb2a_base85()تولید میکند: گروههای نهایی جزئی باید از همان رقمهای پدینگِ کدگذار استفاده کنند.دادههای نامعتبر Base85 استثنای
binascii.Errorرا پرتاب خواهند کرد.اضافه شده در نسخهی 3.15.
- binascii.b2a_base85(data, /, *, alphabet=BASE85_ALPHABET, wrapcol=0, pad=False)¶
دادههای دودویی را به یک سطر از نویسههای اسکی در کدگذاری Base85 تبدیل میکند. مقدار بازگشتی، سطر تبدیلشده است.
پارامتر اختیاری alphabet باید یک شیء شبهبایت با طول ۸۵ باشد که الفبای جایگزینی را مشخص میکند.
اگر wrapcol غیرصفر باشد، پس از حداکثر هر wrapcol نویسه، یک نویسهی خط جدید (
b'\n') درج کنید. اگر wrapcol صفر باشد (پیشفرض)، هیچ خط جدیدی درج نکنید.اگر pad مقدار درست باشد، پدینگ صفر اعمالشده به انتهای ورودی در خروجی حفظ میشود که همیشه ضریبی از ۵ بایت خواهد بود، و در نتیجه ممکن است طول دادهها هنگام کدگشایی حفظ نشود.
اضافه شده در نسخهی 3.15.
- binascii.a2b_base32(string, /, *, padded=True, alphabet=BASE32_ALPHABET, ignorechars=b'', canonical=False)¶
دادههای base32 را به دادههای دودویی تبدیل کرده و دادههای دودویی را برمیگرداند.
دادههای معتبر base32 شامل نویسههایی از الفبای base32 مشخصشده در RFC 4648 در گروههای هشتتایی هستند (در صورت نیاز، گروه نهایی با
=تا هشت نویسه پدینگ میشود). هر گروه ۴۰ بیت از دادههای دودویی را در محدودهی0تا2 ** 40 - 1(شامل هر دو) کدگذاری میکند.نکته
این تابع نویسههای حروف کوچک (که در base32 استاندارد نامعتبر هستند) را به معادلهای حروف بزرگ آنها نگاشت نمیکند و همچنین همانطور که RFC 4648 اجازه میدهد، به صورت متنی
0را بهOو1را بهI/Lنگاشت نمیکند.پارامتر اختیاری alphabet باید یک شیء
bytesبا طول ۳۲ باشد که الفبای جایگزینی را مشخص میکند.اگر padded مقدار درست باشد، آخرین گروه از ۸ نویسهی الفبای base 32 باید با نویسهی '=' پدینگ شود. اگر padded مقدار نادرست باشد، نویسهی '=' مانند سایر نویسههای غیرالفبایی رفتار میشود (بسته به مقدار پارامتر ignorechars).
پارامتر ignorechars باید یک شیء شبهبایت حاوی نویسههایی باشد که باید از ورودی نادیده گرفته شوند. اگر ignorechars شامل نویسهی پدینگ
'='باشد، نویسههای پدینگ ارائهشده قبل از انتهای دادههای کدگذاریشده و نویسههای پدینگ اضافی نادیده گرفته خواهند شد.اگر canonical برابر با true باشد، بیتهای پُرکنندهی غیرصفر در آخرین گروه با استثنای
binascii.Errorرد میشوند و کدگذاری کانونیکال را همانطور که در بخش ۳.۵ استاندارد RFC 4648 تعریف شده است، اعمال میکنند.دادههای نامعتبر base32 باعث ایجاد استثنای
binascii.Errorمیشوند.اضافه شده در نسخهی 3.15.
- binascii.b2a_base32(data, /, *, padded=True, alphabet=BASE32_ALPHABET, wrapcol=0)¶
دادههای دودویی را به یک سطر از نویسههای اسکی در کدگذاری base32 تبدیل میکند، همانطور که در RFC 4648 مشخص شده است. مقدار بازگشتی، سطر تبدیلشده است.
پارامتر اختیاری alphabet باید یک شیء شبهبایت به طول ۳۲ باشد که الفبای جایگزینی را مشخص میکند.
اگر padded برابر با True باشد (پیشفرض)، دادههای کدگذاریشده با نویسهی '=' تا ضریبی از اندازهی ۸ پُر میشوند. اگر padded برابر با False باشد، نویسههای پُرکننده اضافه نمیشوند.
اگر wrapcol غیرصفر باشد، پس از حداکثر هر wrapcol نویسه، یک نویسهی خط جدید (
b'\n') درج کنید. اگر wrapcol صفر باشد (پیشفرض)، هیچ خط جدیدی درج نکنید.اضافه شده در نسخهی 3.15.
- binascii.a2b_qp(data, header=False)¶
یک بلوک از دادههای quoted-printable را دوباره به دودویی تبدیل میکند و دادههای دودویی را برمیگرداند. میتوان بیش از یک خط را در هر نوبت ارسال کرد. اگر آرگومان اختیاری header وجود داشته باشد و مقدار آن درست باشد، زیرسطرها بهعنوان فاصله کدگشایی میشوند.
- binascii.b2a_qp(data, quotetabs=False, istext=True, header=False)¶
دادههای دودویی را به یک یا چند خط از نویسههای ASCII با کدگذاری quoted-printable تبدیل میکند. مقدار بازگشتی، خط یا سطرهای تبدیلشده است. اگر آرگومان اختیاری quotetabs موجود و درست باشد، همهی تبها و فاصلهها کدگذاری خواهند شد. اگر آرگومان اختیاری istext موجود و درست باشد، نویسههای خط جدید کدگذاری نمیشوند، اما فاصلههای انتهایی کدگذاری خواهند شد. اگر آرگومان اختیاری header موجود و درست باشد، فاصلهها مطابق RFC 1522 بهصورت زیرخط کدگذاری میشوند. اگر آرگومان اختیاری header موجود و نادرست باشد، نویسههای خط جدید نیز کدگذاری خواهند شد؛ در غیر این صورت، تبدیل linefeed ممکن است جریان دادههای دودویی را خراب کند.
- binascii.crc_hqx(data, value)¶
مقدار CRC ۱۶بیتی data را، با شروع از value بهعنوان CRC اولیه، محاسبه میکند و نتیجه را برمیگرداند. این از چندجملهای CRC-CCITT x16 + x12 + x5 + 1 استفاده میکند، که اغلب بهصورت 0x1021 نمایش داده میشود. این CRC در قالب binhex4 استفاده میشود.
- binascii.crc32(data[, value])¶
CRC-32، جمعآزمای ۳۲ بیتی بدون علامت برای data را با شروع از مقدار اولیهی CRC برابر با value محاسبه کنید. مقدار اولیهی پیشفرض CRC صفر است. این الگوریتم با جمعآزمای پرونده ZIP سازگار است. از آنجا که این الگوریتم برای استفاده بهعنوان الگوریتم جمعآزما طراحی شده است، برای استفاده بهعنوان یک الگوریتم هش عمومی مناسب نیست. بهصورت زیر استفاده کنید:
print(binascii.crc32(b"hello world")) # Or, in two pieces: crc = binascii.crc32(b"hello") crc = binascii.crc32(b" world", crc) print('crc32 = {:#010x}'.format(crc))
تغییر یافته در نسخهی 3.0: نتیجه همواره بدون علامت است.
- binascii.b2a_hex(data[, sep[, bytes_per_sep=1]])¶
- binascii.hexlify(data[, sep[, bytes_per_sep=1]])¶
بازنمایی مبنای شانزدهی دادهی دودویی data را برمیگرداند. هر بایت از data به بازنمایی مبنای شانزدهی ۲رقمی متناظر تبدیل میشود. بنابراین، شیء bytes برگرداندهشده دو برابر طول data طول دارد.
قابلیت مشابهی (اما با برگرداندن یک رشته متنی) همچنین بهراحتی با استفاده از متد
bytes.hex()قابل دسترسی است.اگر sep مشخص شده باشد، باید یک شیء str یا bytes تکنویسهای باشد. این جداکننده در خروجی پس از هر bytes_per_sep بایت ورودی درج میشود. بهطور پیشفرض، شمارش محل قرارگیری جداکننده از انتهای راست خروجی انجام میشود؛ اگر میخواهید از سمت چپ شمارش کنید، یک مقدار منفی برای bytes_per_sep ارائه دهید.
>>> import binascii >>> binascii.b2a_hex(b'\xb9\x01\xef') b'b901ef' >>> binascii.hexlify(b'\xb9\x01\xef', '-') b'b9-01-ef' >>> binascii.b2a_hex(b'\xb9\x01\xef', b'_', 2) b'b9_01ef' >>> binascii.b2a_hex(b'\xb9\x01\xef', b' ', -2) b'b901 ef'
تغییر یافته در نسخهی 3.8: پارامترهای sep و bytes_per_sep افزوده شدند.
- binascii.a2b_hex(hexstr, *, ignorechars=b'')¶
- binascii.unhexlify(hexstr, *, ignorechars=b'')¶
دادهی دودویی نمایشدادهشده توسط رشتهی مبنای شانزده hexstr را برمیگرداند. این تابع معکوس
b2a_hex()است. hexstr باید حاوی تعداد زوجی از ارقام مبنای شانزده باشد (که میتوانند بهصورت حروف بزرگ یا کوچک باشند)، در غیر این صورت استثنایErrorپرتاب میشود.پارامتر ignorechars باید یک شیء شبهبایت حاوی نویسههایی باشد که باید از ورودی نادیده گرفته شوند.
قابلیت مشابهی (اما با سختگیری کمتر نسبت به فضای خالی) نیز از طریق متد کلاسی
bytes.fromhex()در دسترس است.تغییر یافته در نسخهی 3.15: پارامتر ignorechars اضافه شد.
- exception binascii.Error¶
استثنایی که در صورت بروز خطا پرتاب میشود. این موارد معمولاً خطاهای برنامهنویسی هستند.
- exception binascii.Incomplete¶
استثنایی که هنگام ناقص بودن دادهها پرتاب میشود. این استثناها معمولاً خطاهای برنامهنویسی نیستند، اما ممکن است با خواندن اندکی داده بیشتر و تلاش دوباره مدیریت شوند.
- binascii.URLSAFE_BASE64_ALPHABET¶
الفبای Base 64 «امن برای URL و نام پرونده» بر اساس استاندارد RFC 4648.
اضافه شده در نسخهی 3.15.
- binascii.UU_ALPHABET¶
الفبای uuencoding.
اضافه شده در نسخهی 3.15.
- binascii.CRYPT_ALPHABET¶
الفبای Base 64 استفادهشده در رویهی crypt(3) و در قالب GEDCOM.
اضافه شده در نسخهی 3.15.
- binascii.BINHEX_ALPHABET¶
الفبای Base 64 استفادهشده در BinHex 4 (HQX) درون مک اواس کلاسیک.
اضافه شده در نسخهی 3.15.
- binascii.BASE85_ALPHABET¶
الفبای Base85.
اضافه شده در نسخهی 3.15.
- binascii.ASCII85_ALPHABET¶
الفبای Ascii85.
اضافه شده در نسخهی 3.15.