pyclbr --- پشتیبانی از مرورگر ماژول پایتون

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

ماژول pyclbr اطلاعات محدودی درباره‌ی توابع، کلاس‌ها و متدهای تعریف‌شده در یک ماژول نوشته‌شده به پایتون فراهم می‌کند. این اطلاعات برای پیاده‌سازی یک مرورگر ماژول کافی است. این اطلاعات به‌جای ایمپورت کردن ماژول، از کد منبع پایتون استخراج می‌شود، بنابراین استفاده از این ماژول با کد غیرقابل‌اعتماد امن است. این محدودیت استفاده از این ماژول را برای ماژول‌هایی که به پایتون پیاده‌سازی نشده‌اند، از جمله همه ماژول‌های توسعه‌ای استاندارد و اختیاری، غیرممکن می‌سازد.

pyclbr.readmodule(module, path=None)

دیکشنری‌ای بازمی‌گرداند که نام کلاس‌های سطح ماژول را به توصیف‌گرهای کلاس (class descriptors) نگاشت می‌کند. در صورت امکان، توصیف‌گرهای کلاس‌های پایه‌ی ایمپورت‌شده نیز گنجانده می‌شوند. پارامتر module یک رشته حاوی نام ماژولی است که باید خوانده شود؛ ممکن است نام یک ماژول درون یک بسته باشد. اگر داده شود، path دنباله‌ای از مسیرهای پوشه است که به ابتدای sys.path، که برای یافتن کد منبع ماژول استفاده می‌شود، پیش‌افزوده می‌شود.

این تابع رابط اصلی است و فقط برای سازگاری با نسخه‌های پیشین حفظ شده است. این تابع یک نسخه‌ی فیلترشده از مورد زیر را برمی‌گرداند.

pyclbr.readmodule_ex(module, path=None)

یک درخت مبتنی بر دیکشنری برمی‌گرداند که شامل توصیف‌گرهای تابع یا کلاس برای هر تابع و کلاس تعریف‌شده در ماژول با دستور def یا class است. دیکشنری برگردانده‌شده، نام توابع و کلاس‌های سطح ماژول را به توصیف‌گرهای آن‌ها نگاشت می‌کند. اشیای تودرتو در دیکشنری children والد آن‌ها وارد می‌شوند. مانند readmodule، module نام ماژول مورد نظر برای خواندن است و path به ابتدای sys.path افزوده می‌شود. اگر ماژولی که خوانده می‌شود یک بسته باشد، دیکشنری برگردانده‌شده دارای کلید '__path__' است که مقدار آن فهرستی حاوی مسیر جستجوی بسته است.

اضافه شده در نسخه‌ی 3.7: توصیف‌گرها برای تعریف‌های تودرتو. این توصیف‌گرها از طریق ویژگی جدید children قابل دسترسی هستند. هر کدام یک ویژگی جدید parent دارد.

توصیف‌گرهای برگردانده‌شده توسط این توابع، نمونه‌هایی از کلاس‌های Function و Class هستند. انتظار نمی‌رود کاربران نمونه‌هایی از این کلاس‌ها ایجاد کنند.

اشیای تابع

class pyclbr.Function

نمونه‌های کلاس Function توابعی را توصیف می‌کنند که با دستورهای def تعریف شده‌اند. این نمونه‌ها ویژگی‌های زیر را دارند:

file

نام پرونده‌ای که تابع در آن تعریف شده است.

module

نام ماژولی که تابع توصیف‌شده را تعریف می‌کند.

name

نام تابع.

lineno

شماره‌ی سطر در پرونده‌ای که تعریف در آن آغاز می‌شود.

parent

برای توابع سطح بالا، None. برای توابع تودرتو، والد.

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

children

یک دیکشنری که نام‌ها را به توصیف‌گرهایی برای توابع و کلاس‌های تودرتو نگاشت می‌کند.

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

is_async

True برای توابعی که با پیشوند async تعریف شده‌اند، False در غیر این صورت.

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

اشیای کلاس

class pyclbr.Class

نمونه‌های کلاس Class، کلاس‌هایی را توصیف می‌کنند که با دستورهای کلاس تعریف‌شده‌اند. این نمونه‌ها همان ویژگی‌های Function را دارند و ۲ ویژگی دیگر نیز دارند.

file

نام پرونده‌ای که کلاس در آن تعریف شده است.

module

نام ماژولی که کلاس توصیف‌شده را تعریف می‌کند.

name

نام کلاس.

lineno

شماره‌ی سطر در پرونده‌ای که تعریف در آن آغاز می‌شود.

parent

برای کلاس‌های سطح بالا، None. برای کلاس‌های تودرتو، والد.

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

children

یک دیکشنری که نام‌ها را به توصیف‌گرهایی برای توابع و کلاس‌های تودرتو نگاشت می‌کند.

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

super

فهرستی از اشیای Class که کلاس‌های پایه مستقیم کلاس توصیف‌شده را توصیف می‌کنند. کلاس‌هایی که به‌عنوان ابرکلاس نام برده شده‌اند اما توسط readmodule_ex() قابل کشف نیستند، به‌جای اینکه به‌صورت اشیای Class باشند، به‌صورت رشته‌ای حاوی نام کلاس فهرست می‌شوند.

methods

یک دیکشنری که نام متدها را به شماره‌های سطر نگاشت می‌کند. این را می‌توان از دیکشنری جدیدتر children استخراج کرد، اما برای سازگاری با نسخه‌های قدیمی همچنان باقی مانده است.