pickletools --- ابزارهایی برای توسعه‌دهندگان pickle

کد منبع: Lib/pickletools.py

---

این ماژول شامل ثابت‌های گوناگونی است که به جزئیات دقیق ماژول pickle مربوط می‌شوند، همچنین شامل برخی کامنت‌های طولانی درباره پیاده‌سازی و چند تابع مفید برای تحلیل داده‌های پیکل‌شده است. محتوای این ماژول برای توسعه‌دهندگان اصلی پایتون که روی pickle کار می‌کنند مفید است؛ کاربران عادی ماژول pickle احتمالاً ماژول pickletools را مرتبط نخواهند یافت.

استفاده از خط فرمان

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

هنگامی که از خط فرمان فراخوانی شود، python -m pickletools محتوای یک یا چند پرونده پیکل را واسازی (disassemble) خواهد کرد. توجه داشته باشید که اگر می‌خواهید به‌جای جزئیات قالب پیکل، شیء پایتون ذخیره‌شده در پیکل را ببینید، ممکن است بخواهید به‌جای آن از -m pickle استفاده کنید. با این حال، هنگامی که پرونده پیکلی که می‌خواهید بررسی کنید از منبعی نامطمئن آمده باشد، -m pickletools گزینه امن‌تری است، زیرا بایت‌کد پیکل را اجرا نمی‌کند.

برای مثال، با یک تاپل (1, 2) پیکل‌شده در پرونده x.pickle:

$ python -m pickle x.pickle
(1, 2)

$ python -m pickletools x.pickle
    0: \x80 PROTO      3
    2: K    BININT1    1
    4: K    BININT1    2
    6: \x86 TUPLE2
    7: q    BINPUT     0
    9: .    STOP
highest protocol among opcodes = 2

گزینه‌های خط فرمان

-a, --annotate

هر خط را با توضیحی کوتاه از آپ‌کد (opcode) حاشیه‌نویسی کنید.

-o, --output=<file>

نام پرونده‌ای که خروجی باید در آن نوشته شود.

-l, --indentlevel=<num>

تعداد نویسه‌های خالی که برای تورفتگی یک سطح MARK جدید استفاده می‌شود.

-m, --memo

هنگامی که چندین شیء disassemble می‌شوند، memo بین disassemblyها حفظ می‌شود.

-p, --preamble=<preamble>

هنگامی که بیش از یک پرونده پیکل مشخص شده باشد، پیش‌درآمد داده‌شده را پیش از هر واسازی (disassembly) چاپ می‌کند.

pickle_file

یک پرونده pickle برای خواندن، یا - برای نشان دادن خواندن از ورودی استاندارد.

رابط برنامه‌نویسی

pickletools.dis(pickle, out=None, memo=None, indentlevel=4, annotate=0)

یک disassembly نمادین از pickle را در شیء شبه‌پرونده‌ی out می‌نویسد؛ مقدار پیش‌فرض out برابر با sys.stdout است. pickle می‌تواند یک رشته یا یک شیء شبه‌پرونده باشد. memo می‌تواند یک دیکشنری پایتون باشد که به‌عنوان memo مربوط به pickle استفاده می‌شود؛ از آن می‌توان برای انجام disassembly روی چندین pickle ایجادشده توسط یک pickler یکسان استفاده کرد. سطح‌های متوالی که با کدهای عملیاتی MARK در جریان مشخص می‌شوند، به اندازه‌ی indentlevel فاصله تورفتگی می‌گیرند. اگر مقداری غیرصفر برای annotate داده شود، هر کدعمل در خروجی با توضیح کوتاهی حاشیه‌نویسی می‌شود. مقدار annotate به‌عنوان راهنمایی برای ستونی استفاده می‌شود که حاشیه‌نویسی باید از آن آغاز شود.

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

pickletools.genops(pickle)

یک iterator بر روی تمام آپ‌کدهای (opcode) موجود در یک pickle فراهم می‌کند و دنباله‌ای از سه‌تایی‌ها (opcode, arg, pos) را برمی‌گرداند. opcode یک نمونه از کلاس OpcodeInfo است؛ arg مقدار کدگشایی‌شده‌ی آرگومانِ آپ‌کد به‌عنوان یک شیء پایتون است؛ pos موقعیتی است که این آپ‌کد در آن قرار دارد. pickle می‌تواند یک رشته یا یک شیء شبه‌پرونده باشد.

pickletools.optimize(picklestring)

یک رشته‌ی پیکل جدید و معادل را پس از حذف آپ‌کدهای PUT که استفاده نمی‌شوند برمی‌گرداند. پیکل بهینه‌شده کوتاه‌تر است، زمان انتقال کمتری می‌گیرد، به فضای ذخیره‌سازی کمتری نیاز دارد و با کارایی بیشتری از حالت پیکل خارج می‌شود.