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, /, *, strict_mode=False)

یک بلوک از داده‌های base64 را دوباره به دودویی تبدیل می‌کند و داده‌های دودویی را برمی‌گرداند. شما می‌توانید بیش از یک خط را در هر بار ارسال کنید.

اگر strict_mode درست باشد، فقط داده‌های معتبر base64 تبدیل می‌شوند. داده‌های نامعتبر base64 باعث پرتاب binascii.Error می‌شوند.

base64 معتبر:

• با RFC 3548 مطابقت دارد.

• فقط شامل نویسه‌های الفبای base64 است.

• فاقد داده اضافی پس از پدینگ (padding) است (از جمله پدینگ اضافی، سطرهای جدید و غیره).

• با یک پرکننده (padding) شروع نمی‌شود.

تغییر یافته در نسخه‌ی 3.11: پارامتر strict_mode اضافه شد.

binascii.b2a_base64(data, *, newline=True)

داده‌های دودویی را به سطری از نویسه‌های ASCII با کدگذاری base64 تبدیل می‌کند. مقدار بازگشتی، خط تبدیل‌شده است و در صورتی که newline درست باشد، شامل یک نویسه خط جدید نیز می‌شود. خروجی این تابع با RFC 3548 مطابقت دارد.

تغییر یافته در نسخه‌ی 3.6: پارامتر newline افزوده شد.

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 x¹⁶ + x¹² + x⁵ + 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)

binascii.unhexlify(hexstr)

داده‌ی دودویی نمایش‌داده‌شده توسط رشته‌ی مبنای شانزده hexstr را برمی‌گرداند. این تابع معکوس b2a_hex() است. hexstr باید حاوی تعداد زوجی از ارقام مبنای شانزده باشد (که می‌توانند به‌صورت حروف بزرگ یا کوچک باشند)، در غیر این صورت استثنای Error پرتاب می‌شود.

قابلیت مشابهی (اما با سخت‌گیری کمتر نسبت به فضای خالی) نیز از طریق متد کلاسی bytes.fromhex() در دسترس است.

exception binascii.Error

استثنایی که در صورت بروز خطا پرتاب می‌شود. این موارد معمولاً خطاهای برنامه‌نویسی هستند.

exception binascii.Incomplete

استثنایی که هنگام ناقص بودن داده‌ها پرتاب می‌شود. این استثناها معمولاً خطاهای برنامه‌نویسی نیستند، اما ممکن است با خواندن اندکی داده بیشتر و تلاش دوباره مدیریت شوند.

همچنین ملاحظه نمائید

ماژول base64

پشتیبانی از کدگذاری به‌سبک base64 مطابق با RFC در مبنای ۱۶، ۳۲، ۶۴ و ۸۵.

ماژول quopri

پشتیبانی از کدگذاری quoted-printable مورد استفاده در پیام‌های ایمیل MIME.