inspect --- بازرسی اشیاء زنده

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

---

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

این ماژول ۴ نوع خدمت اصلی ارائه می‌دهد: بررسی نوع، دریافت کد منبع، بازرسی کلاس‌ها و توابع، و بررسی پشته مفسر.

انواع و اعضا

تابع getmembers() اعضای یک شیء مانند یک کلاس یا ماژول را بازیابی می‌کند. توابعی که نام‌هایشان با «is» آغاز می‌شوند، عمدتاً به‌عنوان گزینه‌هایی مناسب برای دومین آرگومان getmembers() ارائه شده‌اند. آن‌ها همچنین به شما کمک می‌کنند تا تعیین کنید چه زمانی می‌توانید انتظار داشته باشید ویژگی‌های خاص زیر را بیابید (برای ویژگی‌های ماژول ویژگی‌های مرتبط با ایمپورت در اشیای ماژول را ببینید):

نوع	ویژگی	توضیحات
کلاس	__doc__	رشته مستندسازی
	__name__	نامی که این کلاس با آن تعریف شده است
	__qualname__	نام کامل
	__module__	نام ماژولی که این کلاس در آن تعریف شده است
	__type_params__	یک تاپل حاوی پارامترهای نوع یک کلاس عام
متد	__doc__	رشته مستندسازی
	__name__	نامی که این متد با آن تعریف شده است
	__qualname__	نام کامل
	__func__	شیء تابعی حاوی پیاده‌سازی متد
	__self__	نمونه‌ای که این متد به آن مقید شده است، یا None
	__module__	نام ماژولی که این متد در آن تعریف شده است
تابع	__doc__	رشته مستندسازی
	__name__	نامی که این تابع با آن تعریف‌شده است
	__qualname__	نام کامل
	__code__	شیء کد حاوی بایت‌کد تابع کامپایل‌شده
	__defaults__	تاپلی از هرگونه مقدار پیش‌فرض برای پارامترهای جایگاهی یا کلیدواژه‌ای
	__kwdefaults__	نگاشت مقادیر پیش‌فرض برای پارامترهای فقط کلیدواژه‌ای
	__globals__	فضای نام سراسری که این تابع در آن تعریف شده است
	__builtins__	فضای نام توکارها
	__annotations__	نگاشت نام پارامترها به حاشیه‌نویسی‌ها؛ کلید "return" برای حاشیه‌نویسی‌های بازگشتی رزرو شده است.
	__type_params__	تاپلی شامل پارامترهای نوع یک تابع عام
	__module__	نام ماژولی که این تابع در آن تعریف شده است
traceback	tb_frame	شیء فریم در این سطح
	tb_lasti	اندیس آخرین دستور بایت‌کد که اجرای آن تلاش شد
	tb_lineno	شماره خط جاری در کد منبع پایتون
	tb_next	شیء ردگیری پشته‌ی داخلی بعدی (فراخوانی‌شده توسط این سطح)
فریم	f_back	شیء فریم بیرونی بعدی (فراخواننده‌ی این فریم)
	f_builtins	فضای نام builtins که توسط این فریم دیده می‌شود
	f_code	شیء کدِ در حال اجرا در این فریم
	f_globals	فضای نام سراسری قابل‌مشاهده برای این فریم
	f_lasti	اندیس آخرین دستور بایت‌کد که اجرای آن تلاش شد
	f_lineno	شماره خط جاری در کد منبع پایتون
	f_locals	فضای نام محلی دیده‌شده توسط این فریم
	f_generator	شیء تولیدگر یا هم‌روال را که مالک این فریماست برمی‌گرداند، یا اگر فریم متعلق به یک تابع معمولی باشد None را برمی‌گرداند
	f_trace	تابع ردگیری برای این فریم، یا None
	f_trace_lines	نشان می‌دهد که آیا یک رویداد ردگیری برای هر خط منبع راه‌اندازی می‌شود یا خیر
	f_trace_opcodes	نشان می‌دهد که آیا رویدادهای به‌ازای هر opcode درخواست شده‌اند
	clear()	برای پاک کردن تمام ارجاع‌ها به متغیرهای محلی استفاده می‌شود
کد	co_argcount	تعداد آرگومان‌ها (به‌جز آرگومان‌های فقط کلیدواژه‌ای، * یا ** args)
	co_code	رشته‌ای از بایت‌کد خام کامپایل‌شده
	co_cellvars	تاپلی از نام‌های متغیرهای سلولی (که توسط محدوده‌های دربرگیرنده ارجاع داده‌شده‌اند)
	co_consts	تاپل ثابت‌های استفاده‌شده در بایت‌کد
	co_filename	نام پرونده‌ای که این شیء کد در آن ایجاد شده است
	co_firstlineno	شماره‌ی نخستین خط در کد منبع پایتون
	co_flags	بیت‌مپ پرچم‌های CO_*، برای مطالعه بیشتر اینجا را ببینید
	co_lnotab	نگاشت کدگذاری‌شده از شماره سطرها به اندیس‌های بایت‌کد
	co_freevars	تاپلی از نام‌های متغیرهای آزاد (ارجاع‌شده از طریق بستار یک تابع )
	co_posonlyargcount	تعداد آرگومان‌های فقط جایگاهی
	co_kwonlyargcount	تعداد آرگومان‌های فقط کلیدواژه‌ای (بدون احتساب ** arg)
	co_name	نامی که این شیء کد با آن تعریف شده است
	co_qualname	نام کامل که این شیء کد با آن تعریف شده است
	co_names	تاپلی از نام‌هایی غیر از آرگومان‌ها و متغیرهای محلی تابع
	co_nlocals	تعداد متغیرهای محلی
	co_stacksize	فضای پشته‌ی ماشین مجازی موردنیاز
	co_varnames	تاپلی از نام‌های آرگومان‌ها و متغیرهای محلی
	co_lines()	یک پیمایش‌گر برمی‌گرداند که بازه‌های پیاپی بایت‌کد را تولید می‌کند
	co_positions()	یک پیمایش‌گر از موقعیت‌های کد منبع برای هر دستور بایت‌کد برمی‌گرداند
	replace()	نسخه‌ای از شیء کد را با مقادیر جدید بازمی‌گرداند
تولیدگر	__name__	نام
	__qualname__	نام کامل
	gi_frame	فریم
	gi_running	آیا تولیدگر در حال اجرا است؟
	gi_suspended	آیا تولیدگر معلق است؟
	gi_code	کد
	gi_yieldfrom	شیئی که yield from روی آن پیمایش می‌کند، یا None
تولیدگر ناهمگام	__name__	نام
	__qualname__	نام کامل
	ag_await	شیء‌ای که await روی آن انجام می‌شود، یا None
	ag_frame	فریم
	ag_running	آیا تولیدگر در حال اجرا است؟
	ag_suspended	آیا تولیدگر معلق است؟
	ag_code	کد
هم‌روال	__name__	نام
	__qualname__	نام کامل
	cr_await	شیء‌ای که await روی آن انجام می‌شود، یا None
	cr_frame	فریم
	cr_running	آیا هم‌روال در حال اجرا است؟
	cr_suspended	آیا هم‌روال معلق است؟
	cr_code	کد
	cr_origin	جایی که هم‌روال ایجاد شده است، یا None. ببینید sys.set_coroutine_origin_tracking_depth()
توکار	__doc__	رشته مستندسازی
	__name__	نام اصلی این تابع یا متد
	__qualname__	نام کامل
	__self__	نمونه‌ای که یک متد به آن مقید شده است، یا None

تغییر یافته در نسخه‌ی 3.5: افزودن ویژگی‌های __qualname__ و gi_yieldfrom به تولیدگرها.

ویژگی __name__ تولیدگرها اکنون به‌جای نام کد، از نام تابع تنظیم می‌شود و اکنون می‌توان آن را تغییر داد.

تغییر یافته در نسخه‌ی 3.7: افزودن ویژگی cr_origin به هم‌روال‌ها.

تغییر یافته در نسخه‌ی 3.10: افزودن ویژگی __builtins__ به توابع.

تغییر یافته در نسخه‌ی 3.11: افزودن ویژگی gi_suspended به تولیدگرها.

تغییر یافته در نسخه‌ی 3.11: افزودن ویژگی cr_suspended به هم‌روال‌ها.

تغییر یافته در نسخه‌ی 3.12: افزودن ویژگی ag_suspended به تولیدگرهای ناهمگام.

تغییر یافته در نسخه‌ی 3.14: افزودن ویژگی f_generator به فریم‌ها.

inspect.getmembers(object[, predicate])

تمام اعضای یک شیء را در فهرستی از جفت‌های (name, value) مرتب‌شده بر اساس نام برمی‌گرداند. اگر آرگومان اختیاری predicate — که با شیء value هر عضو فراخوانی می‌شود — داده شده باشد، تنها اعضایی که predicate برای آن‌ها مقدار درست برگرداند، گنجانده می‌شوند.

توجه

getmembers() تنها زمانی ویژگی‌های کلاس تعریف‌شده در فراکلاس را برمی‌گرداند که آرگومان یک کلاس باشد و آن ویژگی‌ها در __dir__() سفارشی فراکلاس فهرست‌شده باشند.

inspect.getmembers_static(object[, predicate])

تمام اعضای یک شیء را در فهرستی از جفت‌های (name, value) به‌صورت مرتب‌شده بر اساس نام، بدون فعال‌سازی جستجوی پویا از طریق پروتکل توصیف‌گر، __getattr__ یا __getattribute__ برمی‌گرداند. به‌صورت اختیاری، فقط اعضایی را برمی‌گرداند که یک محمول داده‌شده را برآورده می‌کنند.

توجه

getmembers_static() ممکن است نتواند تمام اعضایی را که getmembers می‌تواند واکشی کند، بازیابی کند (مانند ویژگی‌هایی که به‌صورت پویا ایجاد شده‌اند) و ممکن است اعضایی را پیدا کند که getmembers قادر به پیدا کردن آن‌ها نیست (مانند توصیف‌گرهایی که AttributeError را پرتاب می‌کنند). همچنین در برخی موارد می‌تواند به‌جای اعضای نمونه، اشیای توصیف‌گر را برگرداند.

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

inspect.getmodulename(path)

نام ماژول مشخص‌شده توسط مسیر پرونده path را برمی‌گرداند، بدون آنکه نام بسته‌های دربرگیرنده را شامل شود. پسوند پرونده با تمام ورودی‌های importlib.machinery.all_suffixes() مقایسه می‌شود. در صورت تطابق، آخرین کامپوننت مسیر بدون پسوند برگردانده می‌شود. در غیر این صورت، None برگردانده می‌شود.

توجه داشته باشید که این تابع فقط برای ماژول‌های واقعی پایتون یک نام معنادار برمی‌گرداند - مسیرهایی که ممکن است به بسته‌های پایتون اشاره داشته باشند، همچنان None را برمی‌گردانند.

تغییر یافته در نسخه‌ی 3.3: این تابع مستقیماً بر importlib مبتنی است.

inspect.ismodule(object)

اگر شیء یک ماژول باشد، True را برمی‌گرداند.

inspect.isclass(object)

اگر شیء یک کلاس باشد، True را برمی‌گرداند؛ خواه توکار باشد، خواه در کد پایتون ایجاد شده باشد.

این تابع برای نام‌های مستعار عام (generic aliases) کلاس‌ها، مانند list[int]، مقدار False را برمی‌گرداند.

inspect.ismethod(object)

اگر شیء یک متد مقید (bound method) نوشته‌شده به پایتون باشد، True برمی‌گرداند.

توجه

برای مثال، با فرض این کلاس:

>>> class Greeter:
...     def say_hello(self):
...         print('hello!')

یک متد مقید (bound method)، که به‌عنوان متد نمونه نیز شناخته می‌شود، هنگام دسترسی به say_hello (یک تابع تعریف‌شده در فضای نام Greeter) از طریق نمونه‌ای از کلاس Greeter ایجاد می‌شود:

>>> instance = Greeter()

>>> instance.say_hello
<bound method Greeter.say_hello of <__main__.Greeter object ...>>
>>> ismethod(instance.say_hello)
True
>>> isfunction(instance.say_hello)
False

دسترسی به say_hello از طریق کلاس Greeter خود تابع را برمی‌گرداند. برای این تابع، ismethod() مقدار False را برمی‌گرداند، اما isfunction() مقدار True را برمی‌گرداند:

>>> Greeter.say_hello
<function Greeter.say_hello at 0x7f7503854a90>
>>> ismethod(Greeter.say_hello)
False
>>> isfunction(Greeter.say_hello)
True

برای جزئیات، Methods را ببینید.

inspect.isfunction(object)

اگر شیء یک تابع پایتون باشد، True را برمی‌گرداند؛ این شامل توابع ساخته‌شده با عبارت lambda نیز می‌شود.

برای یک مثال، یادداشت مربوط به ismethod() را ببینید.

inspect.ispackage(object)

اگر شیء یک بسته باشد، True را برمی‌گرداند.

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

inspect.isgeneratorfunction(object)

اگر شیء یک تابع تولیدگر پایتون باشد، True را برمی‌گرداند.

همچنین برای متدهای مقید ایجادشده از توابع تولیدگر پایتون، True برمی‌گرداند (برای اطلاعات بیشتر Methods را ببینید).

تغییر یافته در نسخه‌ی 3.8: توابع پوشیده‌شده با functools.partial() اکنون اگر تابع پوشیده‌شده یک تابع تولیدگر پایتون باشد، True را برمی‌گردانند.

تغییر یافته در نسخه‌ی 3.10.6: Duck-typed function-like objects now return True if their code object has the CO_GENERATOR flag.

تغییر یافته در نسخه‌ی 3.13: توابعی که در functools.partialmethod() پوشیده شده‌اند، اکنون در صورتی که تابع پوشیده‌شده یک تابع تولیدگر پایتون باشد، True برمی‌گردانند.

inspect.isgenerator(object)

اگر شیء تولیدگر باشد، True برمی‌گرداند.

inspect.iscoroutinefunction(object)

اگر شیء یک تابع هم‌روال (تابعی که با سینتکس async def تعریف شده است)، یک functools.partial() که یک تابع هم‌روال را در بر می‌گیرد، یا یک تابع همگام علامت‌گذاری‌شده با markcoroutinefunction() باشد، True را برمی‌گرداند.

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

تغییر یافته در نسخه‌ی 3.8: توابع پوشش‌داده‌شده توسط functools.partial() اکنون در صورتی True را برمی‌گردانند که تابع پوشش‌داده‌شده یک تابع هم‌روال باشد.

تغییر یافته در نسخه‌ی 3.10.6: Duck-typed function-like objects now return True if their code object has the CO_COROUTINE flag.

تغییر یافته در نسخه‌ی 3.12: توابع همگامی که با markcoroutinefunction() علامت‌گذاری شده‌اند، اکنون True برمی‌گردانند.

تغییر یافته در نسخه‌ی 3.13: توابعی که در functools.partialmethod() پیچیده شده‌اند، اکنون در صورتی True را برمی‌گردانند که تابع پیچیده‌شده یک تابع هم‌روال باشد.

inspect.markcoroutinefunction(func)

دکوراتوری برای علامت‌گذاری یک شیء فراخوانی‌پذیر به‌عنوان coroutine function، اگر در غیر این صورت توسط iscoroutinefunction() شناسایی نشود.

این می‌تواند برای توابع همگامی که یک هم‌روال را برمی‌گردانند، مفید باشد، اگر تابع به یک API ارسال شود که به iscoroutinefunction() نیاز دارد.

در صورت امکان، استفاده از یک تابع async def ترجیح داده می‌شود. همچنین فراخوانی تابع و آزمایش مقدار بازگشتی با iscoroutine() نیز قابل قبول است.

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

inspect.iscoroutine(object)

اگر شیء یک هم‌روال باشد که توسط یک تابع async def ایجادشده است، True را برمی‌گرداند.

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

inspect.isawaitable(object)

اگر شیء قابل استفاده در عبارت await باشد، True برمی‌گرداند.

همچنین می‌توان از آن برای تمایز هم‌روال‌های مبتنی بر تولیدگر از تولیدگرهای معمولی استفاده کرد:

import types

def gen():
    yield
@types.coroutine
def gen_coro():
    yield

assert not isawaitable(gen())
assert isawaitable(gen_coro())

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

inspect.isasyncgenfunction(object)

اگر شیء یک تابع تولیدگر ناهمگام باشد، True برمی‌گرداند، برای مثال:

>>> async def agen():
...     yield 1
...
>>> inspect.isasyncgenfunction(agen)
True

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

تغییر یافته در نسخه‌ی 3.8: توابعی که با functools.partial() پوشیده‌شده‌اند، اکنون اگر تابع پوشیده‌شده یک تابع تولیدگر ناهمگام باشد، True برمی‌گردانند.

تغییر یافته در نسخه‌ی 3.10.6: Duck-typed function-like objects now return True if their code object has the CO_ASYNC_GENERATOR flag.

تغییر یافته در نسخه‌ی 3.13: توابع پوشش‌داده‌شده با functools.partialmethod() اکنون در صورتی True برمی‌گردانند که تابع پوشش‌داده‌شده یک تابع تولیدگر ناهمگام باشد.

inspect.isasyncgen(object)

اگر شیء یک پیمایش‌گر تولیدگر ناهمگام باشد که توسط یک تابع تولیدگر ناهمگام ایجاد شده است، True را برمی‌گرداند.

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

inspect.istraceback(object)

اگر شیء یک ردگیری پشته باشد، True را برمی‌گرداند.

inspect.isframe(object)

اگر شیء یک فریمباشد، True برمی‌گرداند.

inspect.iscode(object)

اگر شیء یک کد باشد، True را برمی‌گرداند.

inspect.isbuiltin(object)

اگر شیء یک تابع توکار یا یک متد توکار مقید باشد، True برمی‌گرداند.

inspect.ismethodwrapper(object)

اگر نوع شیء MethodWrapperType باشد، True برمی‌گرداند.

این‌ها نمونه‌هایی از MethodWrapperType هستند، مانند __str__()، __eq__() و __repr__().

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

inspect.isroutine(object)

اگر شیء یک تابع یا متد تعریف‌شده توسط کاربر یا توکار باشد، True برمی‌گرداند.

inspect.isabstract(object)

اگر شیء یک کلاس پایه انتزاعی باشد، True را برمی‌گرداند.

inspect.ismethoddescriptor(object)

اگر شیء یک توصیف‌گر متدباشد، True را برمی‌گرداند، اما نه در صورتی که isclass()، ismethod() یا isfunction() درست باشد.

این، برای مثال، در مورد int.__add__ صدق می‌کند. یک شیء که این آزمون را با موفقیت پشت سر می‌گذارد، دارای متد __get__() است، اما متد __set__() یا متد __delete__() ندارد. فراتر از آن، مجموعه‌ی ویژگی‌ها متفاوت است. ویژگی __name__ معمولاً معنادار است، و __doc__ نیز اغلب چنین است.

توصیف‌گرهای متد که همچنین از هر یک از آزمون‌های دیگر (isclass()، ismethod() یا isfunction()) عبور می‌کنند، باعث می‌شوند این تابع False را برگرداند، صرفاً به این دلیل که آن آزمون‌های دیگر تضمین بیشتری می‌دهند -- برای مثال، وقتی یک شیء از آزمون ismethod() عبور کند، می‌توانید روی داشتن ویژگی __func__ حساب کنید.

تغییر یافته در نسخه‌ی 3.13: این تابع دیگر اشیایی را که دارای __get__() و __delete__() هستند، اما __set__() ندارند، به‌اشتباه به‌عنوان توصیف‌گرهای متد گزارش نمی‌دهد (چنین اشیایی توصیف‌گرهای داده هستند، نه توصیف‌گرهای متد).

inspect.isdatadescriptor(object)

اگر شیء یک توصیف‌گر داده (data descriptor) باشد، True را برمی‌گرداند، اما در صورتی که isclass()، ismethod() یا isfunction() درست باشد، برنمی‌گرداند.

توصیف‌گرهای داده همیشه یک متد __set__() و/یا یک متد __delete__() دارند. به‌صورت اختیاری، ممکن است یک متد __get__() نیز داشته باشند.

نمونه‌هایی از توصیف‌گرهای داده عبارت‌اند از properties، getsetها و توصیف‌گرهای عضو. توجه داشته باشید که برای دو مورد اخیر (که تنها در ماژول‌های توسعه C تعریف شده‌اند)، آزمون‌های خاص‌تری در دسترس هستند: به ترتیب isgetsetdescriptor() و ismemberdescriptor().

اگرچه توصیف‌گرهای داده ممکن است ویژگی‌های __name__ و __doc__ را نیز داشته باشند (همان‌طور که پراپرتی‌ها، getsetها و توصیف‌گرهای عضو این ویژگی‌ها را دارند)، اما این موضوع لزوماً در حالت کلی صادق نیست.

تغییر یافته در نسخه‌ی 3.8: این تابع اکنون اشیایی را که فقط یک متد __set__() دارند، به‌عنوان توصیف‌گرهای داده (data descriptors) گزارش می‌کند (وجود __get__() دیگر برای آن لازم نیست). علاوه بر این، اشیایی که __delete__() دارند، اما __set__() ندارند، اکنون به‌درستی به‌عنوان توصیف‌گرهای داده (data descriptors) نیز شناخته می‌شوند که پیش از این چنین نبود.

inspect.isgetsetdescriptor(object)

اگر شیء یک توصیف‌گر getset باشد، True را برمی‌گرداند.

getsetها ویژگی‌هایی هستند که در ماژول‌های توسعه از طریق ساختارهای PyGetSetDef تعریف شده‌اند. در پیاده‌سازی‌های پایتونی که چنین انواعی ندارند، این متد همیشه False را برمی‌گرداند.

inspect.ismemberdescriptor(object)

اگر شیء یک توصیف‌گر عضو (member descriptor) باشد، True را برمی‌گرداند.

توصیف‌گرهای عضو، ویژگی‌هایی هستند که در ماژول‌های توسعه از طریق ساختارهای PyMemberDef تعریف شده‌اند. برای پیاده‌سازی‌های پایتون که فاقد چنین نوع‌هایی هستند، این متد همیشه False را برمی‌گرداند.

بازیابی کد منبع

inspect.getdoc(object)

رشته مستندات یک شیء را، پاک‌سازی‌شده با cleandoc()، دریافت کنید. اگر رشته مستندات یک شیء فراهم‌نشده باشد و آن شیء یک کلاس، یک متد، یک ویژگی یا یک توصیف‌گر باشد، رشته مستندات را از سلسله‌مراتب وراثت بازیابی کنید. اگر رشته مستندات نامعتبر یا موجود نباشد، None را برگردانید.

تغییر یافته در نسخه‌ی 3.5: رشته مستندات اکنون در صورتی که بازنویسی نشده باشند، به ارث می‌رسند.

inspect.getcomments(object)

هر یک از سطرهای کامنت‌ها بلافاصله پیش از کد منبع شیء (برای یک کلاس، تابع یا متد) یا در بالای پرونده منبع پایتون (اگر شیء یک ماژول باشد) را در یک رشته‌ی واحد برمی‌گرداند. اگر کد منبع شیء در دسترس نباشد، None را برمی‌گرداند. این حالت ممکن است در صورتی رخ دهد که شیء در C یا پوسته‌ی تعاملی تعریف شده باشد.

inspect.getfile(object)

Return the name of the (text or binary) file in which an object was defined. An OSError is raised if the source code cannot be retrieved. This will fail with a TypeError if the object is a built-in module, class, or function.

inspect.getmodule(object)

تلاش می‌کند حدس بزند که یک شیء در کدام ماژول تعریف شده است. اگر ماژول را نتوان تعیین کرد، None برمی‌گرداند.

inspect.getsourcefile(object)

Return the name of the Python source file in which an object was defined or None if no way can be identified to get the source. An OSError is raised if the source code cannot be retrieved. This will fail with a TypeError if the object is a built-in module, class, or function.

inspect.getsourcelines(object)

فهرستی از سطرهای کد منبع و شماره خط آغازین برای یک شیء برمی‌گرداند. آرگومان می‌تواند یک ماژول، کلاس، متد، تابع، ردگیری، فریمیا شیء کد باشد. کد منبع به‌صورت فهرستی از سطرهای متناظر با شیء برگردانده می‌شود و شماره خط نشان می‌دهد که اولین خط کد در کجای پرونده منبع اصلی یافت شده است. اگر کد منبع قابل بازیابی نباشد، یک OSError پرتاب می‌شود. اگر شیء یک ماژول، کلاس یا تابع توکار باشد، یک TypeError پرتاب می‌شود.

تغییر یافته در نسخه‌ی 3.3: OSError به جای IOError پرتاب می‌شود؛ دومی اکنون نام مستعاری از اولی است.

inspect.getsource(object)

متن کد منبع یک شیء را برمی‌گرداند. آرگومان می‌تواند یک ماژول، کلاس، متد، تابع، ردگیری پشته، فریم، یا شیء کد باشد. کد منبع به صورت یک رشته واحد برگردانده می‌شود. اگر نتوان کد منبع را بازیابی کرد، یک OSError پرتاب می‌شود. اگر شیء یک ماژول، کلاس یا تابع توکار باشد، یک TypeError پرتاب می‌شود.

تغییر یافته در نسخه‌ی 3.3: OSError به جای IOError پرتاب می‌شود؛ دومی اکنون نام مستعاری از اولی است.

inspect.cleandoc(doc)

حذف تورفتگی از رشته مستندات که برای هم‌تراز شدن با بلوک‌های کد تورفته شده‌اند.

تمام فضای سفید ابتدایی از خط اول حذف می‌شود. هر فضای سفید ابتدایی که بتوان آن را به‌طور یکنواخت از خط دوم به بعد حذف کرد، حذف می‌شود. سطرهای خالی در ابتدا و انتها سپس حذف می‌شوند. همچنین، تمام تب‌ها به فاصله تبدیل می‌شوند.

درون‌نگری اشیاء فراخوانی‌پذیر با شیء Signature

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

شیء Signature، امضای فراخوانی یک شیء فراخوانی‌پذیر و حاشیه‌نویسی مقدار بازگشتی آن را نشان می‌دهد. برای دریافت یک شیء Signature، از تابع signature() استفاده کنید.

inspect.signature(callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False, annotation_format=Format.VALUE)

یک شیء Signature برای فراخوانی‌پذیر داده‌شده برمی‌گرداند:

>>> from inspect import signature
>>> def foo(a, *, b:int, **kwargs):
...     pass

>>> sig = signature(foo)

>>> str(sig)
'(a, *, b: int, **kwargs)'

>>> str(sig.parameters['b'])
'b: int'

>>> sig.parameters['b'].annotation
<class 'int'>

طیف گسترده‌ای از اشیاء فراخوانی‌پذیر پایتون را می‌پذیرد، از توابع و کلاس‌های ساده تا اشیای functools.partial().

اگر برخی از حاشیه‌نویسی‌ها رشته باشند (برای مثال، به این دلیل که از from __future__ import annotations استفاده شده است)، signature() تلاش می‌کند با استفاده از annotationlib.get_annotations() حاشیه‌نویسی‌ها را به‌طور خودکار از حالت رشته‌ای خارج کند. پارامترهای globals، locals و eval_str هنگام تعیین حاشیه‌نویسی‌ها به annotationlib.get_annotations() ارسال می‌شوند؛ برای دستورالعمل‌های نحوه استفاده از این پارامترها، مستندات annotationlib.get_annotations() را ببینید. می‌توان یک عضو از نوع شمارشی (enum) annotationlib.Format را به پارامتر annotation_format ارسال کرد تا قالب حاشیه‌نویسی‌های برگردانده‌شده کنترل شود. برای مثال، از annotation_format=annotationlib.Format.STRING استفاده کنید تا حاشیه‌نویسی‌ها در قالب رشته‌ای برگردانده شوند.

اگر نتوان امضایی ارائه کرد، ValueError پرتاب می‌شود، و اگر از آن نوع شیء پشتیبانی نشود، TypeError پرتاب می‌شود. همچنین، اگر حاشیه‌نویسی‌ها به‌صورت رشته‌ای درآمده باشند و eval_str نادرست نباشد، فراخوانی‌های eval() برای از حالت رشته‌ای خارج کردن حاشیه‌نویسی‌ها در annotationlib.get_annotations() ممکن است هر نوع استثنایی را پرتاب کنند.

یک اسلش (/) در امضای یک تابع نشان می‌دهد که پارامترهای پیش از آن فقط جایگاهی هستند. برای اطلاعات بیشتر، مدخل پرسش‌های پرتکرار درباره پارامترهای فقط جایگاهی را ببینید.

تغییر یافته در نسخه‌ی 3.5: پارامتر follow_wrapped افزوده شد. برای دریافت امضای callable به‌طور خاص، False را ارسال کنید (از callable.__wrapped__ برای باز کردن فراخوانی‌پذیرهای دکوراته‌شده استفاده نخواهد شد.)

تغییر یافته در نسخه‌ی 3.10: پارامترهای globals، locals و eval_str افزوده شدند.

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

توجه

برخی از فراخوانی‌پذیرها ممکن است در پیاده‌سازی‌های خاصی از پایتون قابل درون‌نگری نباشند. برای مثال، در CPython، برخی از توابع توکار تعریف‌شده در C هیچ فراداده‌ای درباره آرگومان‌های خود ارائه نمی‌دهند.

اگر شیء داده‌شده دارای ویژگی __signature__ باشد، ممکن است از آن برای ایجاد امضا استفاده شود. معناشناسی دقیق، جزئیاتی از پیاده‌سازی است و در معرض تغییرات بدون اعلام قبلی قرار دارد. برای معناشناسی کنونی به کد منبع مراجعه کنید.

class inspect.Signature(parameters=None, *, return_annotation=Signature.empty)

یک شیء Signature نشان‌دهنده‌ی امضای فراخوانی یک تابع و حاشیه‌نویسی بازگشت آن است. این شیء برای هر پارامتری که تابع می‌پذیرد، یک شیء Parameter را در مجموعه‌ی parameters خود ذخیره می‌کند.

آرگومان اختیاری parameters دنباله‌ای از اشیای Parameter است که اعتبارسنجی می‌شود تا بررسی شود که هیچ پارامتری با نام تکراری وجود ندارد، و اینکه پارامترها در ترتیب صحیح قرار دارند، یعنی ابتدا پارامترهای فقط جایگاهی، سپس پارامترهای جایگاهی یا کلیدواژه‌ای، و اینکه پارامترهای دارای مقدار پیش‌فرض پس از پارامترهای بدون مقدار پیش‌فرض می‌آیند.

آرگومان اختیاری return_annotation می‌تواند یک شیء پایتون دلخواه باشد. این نشان‌دهنده‌ی حاشیه‌نویسی "return" برای شیء فراخوانی‌پذیر است.

اشیای Signature تغییرناپذیر هستند. برای ایجاد یک کپی اصلاح‌شده، از Signature.replace() یا copy.replace() استفاده کنید.

تغییر یافته در نسخه‌ی 3.5: اشیای Signature اکنون پیکل‌پذیر و hashable هستند.

empty

یک نشانگر ویژه‌ی سطح کلاس برای مشخص کردن فقدان حاشیه‌نویسی بازگشت (return annotation).

parameters

یک نگاشت مرتب از نام‌های پارامترها به اشیای متناظر Parameter. پارامترها به ترتیب دقیق تعریف ظاهر می‌شوند، از جمله پارامترهای فقط کلیدواژه‌ای.

تغییر یافته در نسخه‌ی 3.7: پایتون تنها از نسخه 3.7 به‌صراحت تضمین کرد که ترتیب تعریف پارامترهای فقط کلیدواژه‌ای حفظ می‌شود، اگرچه در عمل این ترتیب همیشه در پایتون 3 حفظ شده بود.

return_annotation

حاشیه‌نویسی «return» برای شیء فراخوانی‌پذیر. اگر شیء فراخوانی‌پذیر حاشیه‌نویسی «return» نداشته باشد، این ویژگی روی Signature.empty تنظیم می‌شود.

bind(*args, **kwargs)

یک نگاشت از آرگومان‌های جایگاهی و کلیدواژه‌ای به پارامترها ایجاد می‌کند. اگر *args و **kwargs با امضا مطابقت داشته باشند، BoundArguments را بازمی‌گرداند، در غیر این صورت TypeError را پرتاب می‌کند.

bind_partial(*args, **kwargs)

مانند Signature.bind() عمل می‌کند، اما امکان حذف برخی از آرگومان‌های الزامی را فراهم می‌کند (رفتار functools.partial() را شبیه‌سازی می‌کند.) BoundArguments را برمی‌گرداند، یا اگر آرگومان‌های ارسال‌شده با امضا مطابقت نداشته باشند، یک TypeError را پرتاب می‌کند.

replace(*[, parameters][, return_annotation])

یک نمونه‌ی جدید از Signature را بر اساس نمونه‌ای که replace() روی آن فراخوانی شده است، ایجاد کنید. می‌توانید parameters و/یا return_annotation متفاوتی را برای بازنویسی ویژگی‌های متناظر امضای پایه ارسال کنید. برای حذف return_annotation از Signature کپی‌شده، Signature.empty را ارسال کنید.

>>> def test(a, b):
...     pass
...
>>> sig = signature(test)
>>> new_sig = sig.replace(return_annotation="new return anno")
>>> str(new_sig)
"(a, b) -> 'new return anno'"

تابع عام copy.replace() نیز از اشیای Signature پشتیبانی می‌کند.

format(*, max_width=None, quote_annotation_strings=True)

یک نمایش رشته‌ای از شیء Signature ایجاد کنید.

اگر max_width ارسال شود، این متد تلاش می‌کند امضا را در سطرهایی با حداکثر max_width نویسه جای دهد. اگر امضا طولانی‌تر از max_width باشد، همه پارامترها در سطرهای جداگانه قرار خواهند گرفت.

اگر quote_annotation_strings برابر False باشد، حاشیه‌نویسی‌ها در امضا، اگر رشته باشند، بدون علامت‌های نقل‌قول آغازین و پایانی نمایش داده می‌شوند. این حالت مفید است اگر امضا با قالب STRING ایجاد شده باشد یا اگر از from __future__ import annotations استفاده شده باشد.

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

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

classmethod from_callable(obj, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)

برای یک شیء فراخوانی‌پذیر داده‌شده obj، یک شیء Signature (یا زیرکلاس آن) را برمی‌گرداند.

این متد، زیرکلاس‌سازی از Signature را ساده‌تر می‌کند:

class MySignature(Signature):
    pass
sig = MySignature.from_callable(sum)
assert isinstance(sig, MySignature)

در غیر این صورت، رفتار آن دقیقاً با رفتار signature() یکسان است.

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

تغییر یافته در نسخه‌ی 3.10: پارامترهای globals، locals و eval_str افزوده شدند.

class inspect.Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)

اشیای Parameter تغییرناپذیر هستند. به‌جای تغییر یک شیء Parameter، می‌توانید از Parameter.replace() یا copy.replace() برای ایجاد یک کپی تغییرکرده استفاده کنید.

تغییر یافته در نسخه‌ی 3.5: اشیای پارامتر اکنون پیکل‌پذیر و hashable هستند.

empty

یک نشانگر ویژه در سطح کلاس برای مشخص کردن نبود مقادیر پیش‌فرض و حاشیه‌نویسی‌ها .

name

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

CPython نام‌های پارامتر ضمنی به‌شکل .0 را در اشیای کدی که برای پیاده‌سازی درک‌ها و عبارات تولیدگر استفاده می‌شوند، تولید می‌کند.

تغییر یافته در نسخه‌ی 3.6: این نام‌های پارامتر اکنون توسط این ماژول به‌صورت نام‌هایی مانند implicit0 در دسترس قرار گرفته‌اند.

default

مقدار پیش‌فرض پارامتر. اگر پارامتر مقدار پیش‌فرض نداشته باشد، این ویژگی به Parameter.empty تنظیم می‌شود.

annotation

حاشیه‌نویسی پارامتر. اگر پارامتر حاشیه‌نویسی نداشته باشد، این ویژگی روی Parameter.empty تنظیم می‌شود.

kind

نحوه مقید شدن مقادیر آرگومان به پارامتر را توصیف می‌کند. مقادیر ممکن از طریق Parameter قابل دسترسی هستند (مانند Parameter.KEYWORD_ONLY) و از مقایسه و مرتب‌سازی بر اساس ترتیب زیر پشتیبانی می‌کنند:

نام	معنی
POSITIONAL_ONLY	مقدار باید به‌عنوان آرگومان جایگاهی ارائه شود. پارامترهای فقط جایگاهی پارامترهایی هستند که پیش از ورودی / (در صورت وجود) در تعریف تابع پایتون قرار دارند.
POSITIONAL_OR_KEYWORD	مقدار ممکن است به‌صورت آرگومان کلیدواژه‌ای یا جایگاهی ارائه شود (این رفتار اتصال استاندارد برای توابع پیاده‌سازی‌شده در پایتون است.)
VAR_POSITIONAL	تاپلی از آرگومان‌های جایگاهی که به هیچ پارامتر دیگری مقید نشده‌اند. این متناظر با یک پارامتر *args در تعریف یک تابع پایتون است.
KEYWORD_ONLY	مقدار باید به‌عنوان آرگومان کلیدواژه‌ای ارائه شود. پارامترهای فقط کلیدواژه‌ای آن‌هایی هستند که پس از یک * یا *args در تعریف تابع پایتون ظاهر می‌شوند.
VAR_KEYWORD	دیکشنری‌ای از آرگومان‌های کلیدواژه‌ای که به هیچ پارامتر دیگری متصل نیستند. این معادل یک پارامتر **kwargs در تعریف تابع پایتون است.

مثال: چاپ همه‌ی آرگومان‌های فقط کلیدواژه‌ای بدون مقدار پیش‌فرض:

>>> def foo(a, b, *, c, d=10):
...     pass

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     if (param.kind == param.KEYWORD_ONLY and
...                        param.default is param.empty):
...         print('Parameter:', param)
Parameter: c

kind.description

یک مقدار enum از Parameter.kind را توصیف می‌کند.

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

مثال: چاپ همه‌ی توضیحات آرگومان‌ها:

>>> def foo(a, b, *, c, d=10):
...     pass

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     print(param.kind.description)
positional or keyword
positional or keyword
keyword-only
keyword-only

replace(*[, name][, kind][, default][, annotation])

یک نمونه جدید از Parameter بر اساس نمونه‌ای که replace روی آن فراخوانی شده است، ایجاد کنید. برای بازنویسی یک ویژگی Parameter، آرگومان متناظر را ارسال کنید. برای حذف مقدار پیش‌فرض یا/و حاشیه‌نویسی از یک Parameter، Parameter.empty را ارسال کنید.

>>> from inspect import Parameter
>>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42)
>>> str(param)
'foo=42'

>>> str(param.replace()) # Will create a shallow copy of 'param'
'foo=42'

>>> str(param.replace(default=Parameter.empty, annotation='spam'))
"foo: 'spam'"

اشیای Parameter نیز توسط تابع عام copy.replace() پشتیبانی می‌شوند.

تغییر یافته در نسخه‌ی 3.4: در پایتون 3.3، اگر kind اشیای Parameter روی POSITIONAL_ONLY تنظیم شده بود، اجازه داده می‌شد name آن‌ها روی None تنظیم شود. این دیگر مجاز نیست.

class inspect.BoundArguments

نتیجه‌ی فراخوانی Signature.bind() یا Signature.bind_partial(). نگاشت آرگومان‌ها به پارامترهای تابع را نگه می‌دارد.

arguments

یک نگاشت تغییرپذیر از نام پارامترها به مقادیر آرگومان‌ها. فقط شامل آرگومان‌هایی است که به‌صراحت متصل شده‌اند. تغییرات در arguments در args و kwargs منعکس می‌شود.

باید برای هرگونه پردازش آرگومان، همراه با Signature.parameters استفاده شود.

توجه

از آرگومان‌هایی که Signature.bind() یا Signature.bind_partial() برای آن‌ها به مقدار پیش‌فرض اتکا کرده است، صرف‌نظر می‌شود. با این حال، در صورت نیاز، برای افزودن آن‌ها از BoundArguments.apply_defaults() استفاده کنید.

تغییر یافته در نسخه‌ی 3.9: arguments اکنون از نوع dict است. پیش‌تر، از نوع collections.OrderedDict بود.

args

تاپلی از مقادیر آرگومان‌های جایگاهی. به‌صورت پویا از ویژگی arguments محاسبه می‌شود.

kwargs

یک دیکشنری از مقادیر آرگومان‌های کلیدواژه‌ای. به‌صورت پویا از ویژگی arguments محاسبه می‌شود. آرگومان‌هایی که می‌توانند به‌صورت جایگاهی ارسال شوند، در عوض در args قرار می‌گیرند.

signature

ارجاعی به شیء والد Signature.

apply_defaults()

تعیین مقادیر پیش‌فرض برای آرگومان‌های ناموجود.

برای آرگومان‌های جایگاهی متغیر (*args)، مقدار پیش‌فرض یک تاپل خالی است.

برای آرگومان‌های کلیدواژه‌ای متغیر (**kwargs)، مقدار پیش‌فرض یک دیکشنری خالی است.

>>> def foo(a, b='ham', *args): pass
>>> ba = inspect.signature(foo).bind('spam')
>>> ba.apply_defaults()
>>> ba.arguments
{'a': 'spam', 'b': 'ham', 'args': ()}

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

می‌توان از ویژگی‌های args و kwargs برای فراخوانی توابع استفاده کرد:

def test(a, *, b):
    ...

sig = signature(test)
ba = sig.bind(10, b=20)
test(*ba.args, **ba.kwargs)

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

PEP 362 - شیء امضای تابع.

مشخصات دقیق، جزئیات پیاده‌سازی و مثال‌ها.

کلاس‌ها و توابع

inspect.getclasstree(classes, unique=False)

فهرست داده‌شده از کلاس‌ها را در قالب سلسله‌مراتبی از فهرست‌های تودرتو مرتب می‌کند. هر جا که فهرست تودرتویی ظاهر شود، شامل کلاس‌هایی است که از کلاسی مشتق شده‌اند که آیتم آن بلافاصله پیش از آن فهرست آمده است. هر آیتم یک تاپل دوتایی (2-tuple) است که شامل یک کلاس و تاپلی از کلاس‌های پایه‌ی آن است. اگر آرگومان unique درست باشد، در ساختار برگردانده‌شده دقیقاً یک آیتم برای هر کلاس در فهرست داده‌شده ظاهر می‌شود. در غیر این صورت، کلاس‌هایی که از وراثت چندگانه استفاده می‌کنند و نوادگان آن‌ها چندین بار ظاهر خواهند شد.

inspect.getfullargspec(func)

نام‌ها و مقادیر پیش‌فرض پارامترهای یک تابع پایتون را دریافت کنید. یک named tuple برگردانده می‌شود:

FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations)

args فهرستی از نام پارامترهای جایگاهی است. varargs نام پارامتر * است، یا اگر آرگومان‌های جایگاهی دلخواه پذیرفته نشوند، None است. varkw نام پارامتر ** است، یا اگر آرگومان‌های کلیدواژه‌ای دلخواه پذیرفته نشوند، None است. defaults یک تاپل به طول n از مقادیر پیش‌فرض آرگومان‌ها است که با آخرین n پارامتر جایگاهی متناظر است، یا اگر چنین پیش‌فرض‌هایی تعریف نشده باشند، None است. kwonlyargs فهرستی از نام پارامترهای فقط کلیدواژه‌ای به ترتیب اعلام است. kwonlydefaults دیکشنری است که نام پارامترهای موجود در kwonlyargs را به مقادیر پیش‌فرضی که در صورت ارائه نشدن آرگومان استفاده می‌شوند، نگاشت می‌کند. annotations دیکشنری است که نام پارامترها را به حاشیه‌نویسی‌ها نگاشت می‌کند. کلید ویژه "return" برای گزارش حاشیه‌نویسی مقدار بازگشتی تابع (در صورت وجود) استفاده می‌شود.

توجه داشته باشید که signature() و شیء امضا، API توصیه‌شده برای درون‌نگری اشیاء فراخوانی‌پذیر را فراهم می‌کنند و از رفتارهای اضافی (مانند آرگومان‌های فقط جایگاهی) پشتیبانی می‌کنند که گاهی در APIهای ماژول‌های توسعه‌ای با آن‌ها مواجه می‌شوید. این تابع عمدتاً برای استفاده در کدی نگه داشته شده است که نیاز دارد سازگاری با API ماژول inspect در پایتون 2 را حفظ کند.

تغییر یافته در نسخه‌ی 3.4: این تابع اکنون بر پایه‌ی signature() است، اما همچنان ویژگی‌های __wrapped__ را نادیده می‌گیرد و نخستین پارامتر از پیش مقید را در خروجی امضا برای متدهای مقید قرار می‌دهد.

تغییر یافته در نسخه‌ی 3.6: این متد پیش‌تر در پایتون 3.5 به‌عنوان منسوخ و به نفع signature() مستند شده بود، اما آن تصمیم معکوس شده است تا یک رابط استاندارد و به‌وضوح پشتیبانی‌شده برای کد تک‌منبعی پایتون 2/3 که در حال مهاجرت از API قدیمی getargspec() است، بازگردانده شود.

تغییر یافته در نسخه‌ی 3.7: پایتون تنها از نسخه 3.7 به‌صراحت تضمین کرد که ترتیب تعریف پارامترهای فقط کلیدواژه‌ای حفظ می‌شود، اگرچه در عمل این ترتیب همیشه در پایتون 3 حفظ شده بود.

inspect.getargvalues(frame)

اطلاعات مربوط به آرگومان‌های ارسال‌شده به یک فریم مشخص را دریافت کنید. یک named tuple به‌صورت ArgInfo(args, varargs, keywords, locals) برگردانده می‌شود. args فهرستی از نام‌های آرگومان است. varargs و keywords نام آرگومان‌های * و ** هستند، یا None هستند. locals دیکشنری متغیرهای محلی فریم داده‌شده است.

توجه

این تابع به‌اشتباه در پایتون 3.5 به‌عنوان منسوخ علامت‌گذاری شده بود.

inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])

یک مشخصات آرگومان خوش‌فرمت را از چهار مقدار بازگردانده‌شده توسط getargvalues() قالب‌بندی کنید. آرگومان‌های format* توابع قالب‌بندی اختیاری متناظری هستند که برای تبدیل نام‌ها و مقادیر به رشته‌ها فراخوانی می‌شوند.

توجه

این تابع به‌اشتباه در پایتون 3.5 به‌عنوان منسوخ علامت‌گذاری شده بود.

inspect.getmro(cls)

یک تاپل از کلاس‌های پایه‌ی کلاس cls، از جمله cls، را در ترتیب حل متد برمی‌گرداند. هیچ کلاسی بیش از یک بار در این تاپل ظاهر نمی‌شود. توجه داشته باشید که ترتیب حل متد به نوع cls بستگی دارد. مگر اینکه یک فراگونه (metatype) بسیار خاص تعریف‌شده توسط کاربر در حال استفاده باشد، cls نخستین المان تاپل خواهد بود.

inspect.getcallargs(func, /, *args, **kwds)

args و kwds را به نام آرگومان‌های تابع یا متد پایتون func مقید می‌کند، گویی با آن‌ها فراخوانی شده است. برای متدهای مقید، آرگومان نخست (که معمولاً self نام دارد) را نیز به نمونه مرتبط مقید می‌کند. یک دیکشنری بازگردانده می‌شود که نام آرگومان‌ها (از جمله نام آرگومان‌های * و **، در صورت وجود) را به مقدارهای آن‌ها از args و kwds نگاشت می‌کند. در صورت فراخوانی نادرست func، یعنی هرگاه func(*args, **kwds) به دلیل امضای ناسازگار استثنا پرتاب کند، استثنایی از همان نوع و با همان پیام یا پیامی مشابه پرتاب می‌شود. برای مثال:

>>> from inspect import getcallargs
>>> def f(a, b=1, *pos, **named):
...     pass
...
>>> getcallargs(f, 1, 2, 3) == {'a': 1, 'named': {}, 'b': 2, 'pos': (3,)}
True
>>> getcallargs(f, a=2, x=4) == {'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}
True
>>> getcallargs(f)
Traceback (most recent call last):
...
TypeError: f() missing 1 required positional argument: 'a'

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

منسوخ شده از نسخه‌ی 3.5: در عوض از Signature.bind() و Signature.bind_partial() استفاده کنید.

inspect.getclosurevars(func)

دریافت نگاشت ارجاع‌ها به نام‌های بیرونی در تابع یا متد پایتون func به مقادیر فعلی‌شان. یک named tuple به‌صورت ClosureVars(nonlocals, globals, builtins, unbound) برگردانده می‌شود. nonlocals نام‌های ارجاع‌شده را به متغیرهای بستار واژگانی، globals این نام‌ها را به سراسری‌های ماژول تابع و builtins این نام‌ها را به توکارهای قابل مشاهده از بدنه تابع نگاشت می‌کند. unbound مجموعه‌ای از نام‌های ارجاع‌شده در تابع است که با توجه به سراسری‌های فعلی ماژول و توکارها، به‌هیچ‌وجه قابل حل نبودند.

اگر func یک تابع یا متد پایتون نباشد، TypeError پرتاب می‌شود.

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

inspect.unwrap(func, *, stop=None)

شیء پوشیده‌شده توسط func را دریافت کنید. این تابع زنجیره‌ی ویژگی‌های __wrapped__ را دنبال می‌کند و آخرین شیء در زنجیره را برمی‌گرداند.

stop یک کال‌بک اختیاری است که یک شیء در زنجیره‌ی پوششی را به‌عنوان تنها آرگومان خود می‌پذیرد و اجازه می‌دهد در صورتی که کال‌بک مقدار درست برگرداند، واگشایی زودتر متوقف شود. اگر کال‌بک هرگز مقدار درست برنگرداند، آخرین شیء در زنجیره مانند معمول برگردانده می‌شود. برای مثال، signature() از این استفاده می‌کند تا اگر هر شیء در زنجیره دارای ویژگی __signature__ تعریف‌شده باشد، واگشایی را متوقف کند.

در صورت مواجهه با یک چرخه، ValueError پرتاب می‌شود.

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

inspect.get_annotations(obj, *, globals=None, locals=None, eval_str=False, format=annotationlib.Format.VALUE)

دیکشنری حاشیه‌نویسی‌ها را برای یک شیء محاسبه می‌کند.

این یک نام مستعار برای annotationlib.get_annotations() است؛ برای اطلاعات بیشتر، مستندات آن تابع را ببینید.

ملاحظه

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

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

تغییر یافته در نسخه‌ی 3.14: این تابع اکنون نام مستعاری برای annotationlib.get_annotations() است. فراخوانی آن به‌صورت inspect.get_annotations همچنان کار خواهد کرد.

پشته مفسر

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

class inspect.FrameInfo

frame

شیء فریم که رکورد به آن مربوط می‌شود.

filename

نام پرونده مرتبط با کدی که توسط فریممتناظر با این رکورد اجرا می‌شود.

lineno

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

function

نام تابعی که فریممربوط به این رکورد آن را اجرا می‌کند.

code_context

فهرستی از سطرهای زمینه از کد منبعی که فریممتناظر با این رکورد آن را اجرا می‌کند.

index

اندیس خط جاری در حال اجرا در فهرست code_context.

positions

یک شیء dis.Positions شامل شماره خط آغاز، شماره خط پایان، آفست ستون آغاز و آفست ستون پایان، مرتبط با دستورالعملی که در فریم متناظر با این رکورد اجرا می‌شود.

تغییر یافته در نسخه‌ی 3.5: یک named tuple را به‌جای یک tuple برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.11: FrameInfo اکنون یک نمونه از کلاس است (که با named tuple پیشین سازگاری رو به عقب دارد).

class inspect.Traceback

filename

نام پرونده مرتبط با کدی که توسط فریممتناظر با این ردگیری پشته اجرا می‌شود.

lineno

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

function

نام تابعی که توسط فریم متناظر با این ردگیری پشته اجرا می‌شود.

code_context

فهرستی از سطرهای زمینه از کد منبعی که توسط فریم متناظر با این ردگیری پشته اجرا می‌شود.

index

اندیس خط جاری در حال اجرا در فهرست code_context.

positions

یک شیء dis.Positions حاوی شماره خط آغاز، شماره خط پایان، آفست ستون آغاز و آفست ستون پایان مربوط به دستورالعملی که توسط فریممتناظر با این ردگیری پشته اجرا می‌شود.

تغییر یافته در نسخه‌ی 3.11: Traceback اکنون یک نمونه کلاس است (که با named tuple پیشین سازگار است).

توجه

نگه‌داشتن ارجاع‌ها به اشیاء فریم، که در اولین عنصر رکوردهای فریمی که این توابع برمی‌گردانند یافت می‌شوند، می‌تواند باعث شود برنامه شما چرخه‌های ارجاع ایجاد کند. پس از اینکه یک چرخه ارجاع ایجاد شد، طول عمر تمام اشیایی که از اشیای تشکیل‌دهنده چرخه قابل دسترسی هستند، حتی اگر تشخیص‌دهنده اختیاری چرخه پایتون فعال باشد، می‌تواند بسیار طولانی‌تر شود. اگر چنین چرخه‌هایی باید ایجاد شوند، مهم است اطمینان حاصل شود که آن‌ها به‌صراحت شکسته می‌شوند تا از تخریب با تأخیر اشیاء و افزایش مصرف حافظه‌ای که رخ می‌دهد جلوگیری شود.

اگرچه تشخیص‌دهنده چرخه این موارد را شناسایی می‌کند، اما تخریب فریم‌ها (و متغیرهای محلی) را می‌توان با حذف چرخه در یک بند finally قطعی کرد. این موضوع همچنین در صورتی مهم است که تشخیص‌دهنده چرخه هنگام کامپایل پایتون یا با استفاده از gc.disable() غیرفعال شده باشد. برای مثال:

def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # do something with the frame
    finally:
        del frame

اگر می‌خواهید فریم را نگه دارید (برای مثال برای چاپ یک ردگیری پشته درภายหลัง)، می‌توانید با استفاده از متد frame.clear() نیز چرخه‌های ارجاع را بشکنید.

آرگومان اختیاری context که بیشتر این توابع از آن پشتیبانی می‌کنند، تعداد سطرهای زمینه‌ای را که باید برگردانده شوند مشخص می‌کند؛ این سطرها به‌طور متقارن در اطراف خط جاری قرار دارند.

inspect.getframeinfo(frame, context=1)

دریافت اطلاعات درباره‌ی یک شیء فریم یا ردگیری پشته. یک شیء Traceback برگردانده می‌شود.

تغییر یافته در نسخه‌ی 3.11: به جای یک تاپل نام‌دار (named tuple)، یک شیء Traceback برگردانده می‌شود.

inspect.getouterframes(frame, context=1)

فهرستی از اشیای FrameInfo برای یک فریم و همه‌ی فریم‌های بیرونی را دریافت کنید. این فریم‌ها فراخوانی‌هایی را نشان می‌دهند که به ایجاد frame منجر شده‌اند. اولین ورودی در فهرست برگردانده‌شده نشان‌دهنده‌ی frame است؛ آخرین ورودی نشان‌دهنده‌ی بیرونی‌ترین فراخوانی در پشته‌ی frame است.

تغییر یافته در نسخه‌ی 3.5: فهرستی از named tuples FrameInfo(frame, filename, lineno, function, code_context, index) برگردانده می‌شود.

تغییر یافته در نسخه‌ی 3.11: فهرستی از اشیای FrameInfo برگردانده می‌شود.

inspect.getinnerframes(traceback, context=1)

فهرستی از اشیای FrameInfo برای فریمِ یک ردگیری و همه فریم‌های داخلی را دریافت کنید. این فریم‌ها نشان‌دهنده فراخوانی‌هایی هستند که در اثر frame انجام شده‌اند. نخستین عضو فهرست نشان‌دهنده traceback است؛ آخرین عضو نشان‌دهنده جایی است که استثنا پرتاب شده است.

تغییر یافته در نسخه‌ی 3.5: فهرستی از named tuples FrameInfo(frame, filename, lineno, function, code_context, index) برگردانده می‌شود.

تغییر یافته در نسخه‌ی 3.11: فهرستی از اشیای FrameInfo برگردانده می‌شود.

inspect.currentframe()

شیء فریم مربوط به فریم پشته‌ی فراخواننده را برمی‌گرداند.

این تابع به پشتیبانی مفسر از فریم پشته پایتون (Python stack frame) متکی است، که وجود آن در همه پیاده‌سازی‌های پایتون تضمین نمی‌شود. اگر در پیاده‌سازی بدون پشتیبانی از فریم پشته پایتون (Python stack frame) اجرا شود، این تابع None را برمی‌گرداند.

inspect.stack(context=1)

فهرستی از اشیای FrameInfo را برای پشته‌ی فراخواننده برمی‌گرداند. نخستین ورودی در فهرست برگردانده‌شده نمایانگر فراخواننده است؛ آخرین ورودی نمایانگر بیرونی‌ترین فراخوانی در پشته است.

تغییر یافته در نسخه‌ی 3.5: فهرستی از named tuples FrameInfo(frame, filename, lineno, function, code_context, index) برگردانده می‌شود.

تغییر یافته در نسخه‌ی 3.11: فهرستی از اشیای FrameInfo برگردانده می‌شود.

inspect.trace(context=1)

فهرستی از اشیای FrameInfo را برای پشته‌ی بین فریم فعلی و فریمی که استثنای در حال رسیدگی در آن پرتاب شده است، برمی‌گرداند. اولین ورودی فهرست، فراخواننده را نشان می‌دهد؛ آخرین ورودی، محل پرتاب استثنا را نشان می‌دهد.

تغییر یافته در نسخه‌ی 3.5: فهرستی از named tuples FrameInfo(frame, filename, lineno, function, code_context, index) برگردانده می‌شود.

تغییر یافته در نسخه‌ی 3.11: فهرستی از اشیای FrameInfo برگردانده می‌شود.

واکشی ویژگی‌ها به‌صورت ایستا

هر دو getattr() و hasattr() می‌توانند هنگام واکشی یا بررسی وجود ویژگی‌ها، باعث اجرای کد شوند. توصیف‌گرها، مانند پراپرتی‌ها، فراخوانی می‌شوند و ممکن است __getattr__() و __getattribute__() فراخوانی شوند.

در مواردی که به درون‌نگری غیرفعال نیاز دارید، مانند ابزارهای مستندسازی، این موضوع می‌تواند نامناسب باشد. getattr_static() امضایی مشابه getattr() دارد، اما هنگام واکشی ویژگی‌ها از اجرای کد اجتناب می‌کند.

inspect.getattr_static(obj, attr)

inspect.getattr_static(obj, attr, default)

ویژگی‌ها را بدون فعال‌سازی جستجوی پویا از طریق پروتکل توصیف‌گر (descriptor protocol)، __getattr__() یا __getattribute__() بازیابی کنید.

توجه: این تابع ممکن است نتواند تمام ویژگی‌هایی را که getattr می‌تواند واکشی کند، بازیابی کند (مانند ویژگی‌هایی که به‌صورت پویا ایجاد شده‌اند) و ممکن است ویژگی‌هایی را پیدا کند که getattr نمی‌تواند آن‌ها را واکشی کند، مانند توصیف‌گرها که AttributeError را پرتاب می‌کنند. همچنین می‌تواند به‌جای اعضای نمونه، اشیای توصیف‌گر (descriptor objects) را برگرداند.

اگر __dict__ نمونه توسط عضو دیگری (برای مثال یک پراپرتی) پوشانده شود، این تابع قادر به یافتن اعضای نمونه نخواهد بود.

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

getattr_static() توصیف‌گرها را حل نمی‌کند، برای مثال توصیف‌گرهای slot یا توصیف‌گرهای getset در اشیاء پیاده‌سازی‌شده با C. به‌جای ویژگی زیربنایی، شیء توصیف‌گر برگردانده می‌شود.

می‌توانید این موارد را با کدی مانند کد زیر مدیریت کنید. توجه داشته باشید که برای توصیف‌گرهای getset دلخواه، فراخوانی آن‌ها ممکن است باعث اجرای کد شود:

# example code for resolving the builtin descriptor types
class _foo:
    __slots__ = ['foo']

slot_descriptor = type(_foo.foo)
getset_descriptor = type(type(open(__file__)).name)
wrapper_descriptor = type(str.__dict__['__add__'])
descriptor_types = (slot_descriptor, getset_descriptor, wrapper_descriptor)

result = getattr_static(some_object, 'foo')
if type(result) in descriptor_types:
    try:
        result = result.__get__()
    except AttributeError:
        # descriptors can raise AttributeError to
        # indicate there is no underlying value
        # in which case the descriptor itself will
        # have to do
        pass

وضعیت کنونی تولیدگرها، هم‌روال‌ها و تولیدگرهای ناهمگام

هنگام پیاده‌سازی زمان‌بندهای هم‌روال و برای سایر استفاده‌های پیشرفته از تولیدگرها، مفید است که تشخیص دهید آیا یک تولیدگر در حال حاضر در حال اجرا است، منتظر شروع یا از سرگیری اجرا است، یا پیش‌تر خاتمه یافته است. getgeneratorstate() امکان تعیین وضعیت فعلی یک تولیدگر را به‌آسانی فراهم می‌کند.

inspect.getgeneratorstate(generator)

وضعیت فعلی یک پیمایش‌گر تولیدگر را دریافت کنید.

حالت‌های ممکن عبارتند از:

• GEN_CREATED: در انتظار آغاز اجرا.

• GEN_RUNNING: در حال حاضر توسط مفسر اجرا می‌شود.

• GEN_SUSPENDED: در حال حاضر در یک عبارت yield معلق است.

• GEN_CLOSED: اجرا کامل شده است.

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

inspect.getcoroutinestate(coroutine)

وضعیت فعلی یک شیء هم‌روال را دریافت می‌کند. این تابع برای استفاده با اشیای هم‌روالی که توسط توابع async def ایجاد شده‌اند در نظر گرفته شده است، اما هر شیء هم‌روال‌مانندی را که دارای ویژگی‌های cr_running و cr_frame باشد، می‌پذیرد.

حالت‌های ممکن عبارتند از:

• CORO_CREATED: در انتظار آغاز اجرا.

• CORO_RUNNING: در حال حاضر توسط مفسر اجرا می‌شود.

• CORO_SUSPENDED: در حال حاضر در یک عبارت await معلق است.

• CORO_CLOSED: اجرا کامل شده است.

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

inspect.getasyncgenstate(agen)

وضعیت فعلی یک شیء تولیدگر ناهمگام را دریافت می‌کند. این تابع برای استفاده با اشیاء پیمایش‌گر ناهمگام ایجادشده به‌وسیله‌ی توابع async def که از دستور yield استفاده می‌کنند، در نظر گرفته شده است، اما هر شیء شبه‌تولیدگر ناهمگامی را که دارای ویژگی‌های ag_running و ag_frame باشد، می‌پذیرد.

حالت‌های ممکن عبارتند از:

• AGEN_CREATED: در انتظار شروع اجرا.

• AGEN_RUNNING: در حال حاضر توسط مفسر اجرا می‌شود.

• AGEN_SUSPENDED: در حال حاضر در یک عبارت yield معلق است.

• AGEN_CLOSED: اجرا به پایان رسیده است.

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

همچنین می‌توان وضعیت داخلی فعلی تولیدگر را نیز پرس‌وجو کرد. این موضوع بیشتر برای اهداف آزمایش مفید است، تا اطمینان حاصل شود که وضعیت داخلی همان‌طور که انتظار می‌رود به‌روزرسانی می‌شود:

inspect.getgeneratorlocals(generator)

نگاشت متغیرهای محلی زنده در generator به مقدارهای فعلی‌شان را دریافت کنید. دیکشنری‌ای بازگردانده می‌شود که نام‌های متغیرها را به مقدارها نگاشت می‌کند. این معادل فراخوانی locals() در بدنه‌ی تولیدگر است، و همه‌ی همان ملاحظات اعمال می‌شوند.

اگر generator یک تولیدگر باشد که در حال حاضر هیچ فریمی به آن مرتبط نباشد، یک دیکشنری خالی برگردانده می‌شود. اگر generator یک شیء تولیدگر پایتون نباشد، TypeError پرتاب می‌شود.

این تابع به این وابسته است که تولیدگر یک فریم پشته‌ی پایتون (Python stack frame) را برای درون‌نگری در دسترس قرار دهد، که تضمینی وجود ندارد این شرایط در همه‌ی پیاده‌سازی‌های پایتون برقرار باشد. در چنین مواردی، این تابع همیشه یک دیکشنری خالی برمی‌گرداند.

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

inspect.getcoroutinelocals(coroutine)

این تابع مشابه getgeneratorlocals() است، اما برای اشیاء هم‌روالی که توسط توابع async def ایجاد شده‌اند کار می‌کند.

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

inspect.getasyncgenlocals(agen)

این تابع مشابه getgeneratorlocals() است، اما برای اشیای تولیدگر ناهمگامی کار می‌کند که توسط توابع async def با استفاده از دستور yield ایجاد شده‌اند.

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

پرچم‌های بیتی اشیای کد

اشیای کد پایتون دارای ویژگی co_flags هستند، که بیت‌مپی از پرچم‌های زیر است:

inspect.CO_OPTIMIZED

شیء کد با استفاده از محلی‌های سریع (fast locals) بهینه‌سازی شده است.

inspect.CO_NEWLOCALS

اگر تنظیم شده باشد، هنگام اجرای شیء کد، یک دیکشنری جدید برای f_locals فریم ایجاد می‌شود.

inspect.CO_VARARGS

شیء کد دارای یک پارامتر جایگاهی متغیر (مانند *args) است.

inspect.CO_VARKEYWORDS

شیء کد دارای یک پارامتر کلیدواژه‌ای متغیر (مشابه **kwargs) است.

inspect.CO_NESTED

این پرچم زمانی تنظیم می‌شود که شیء کد یک تابع تودرتو باشد.

inspect.CO_GENERATOR

این پرچم زمانی تنظیم می‌شود که شیء کد یک تابع تولیدگر باشد، یعنی هنگامی که شیء کد اجرا می‌شود، یک شیء تولیدگر بازگردانده می‌شود.

inspect.CO_COROUTINE

این پرچم زمانی تنظیم می‌شود که شیء کد یک تابع هم‌روال باشد. هنگامی که شیء کد اجرا می‌شود، یک شیء هم‌روال برمی‌گرداند. برای جزئیات بیشتر PEP 492 را ببینید.

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

inspect.CO_ITERABLE_COROUTINE

این پرچم برای تبدیل تولیدگرها به هم‌روال‌های مبتنی بر تولیدگر استفاده می‌شود. اشیاء تولیدگر دارای این پرچم می‌توانند در عبارت await استفاده شوند و می‌توانند اشیاء هم‌روال را yield from کنند. برای جزئیات بیشتر PEP 492 را ببینید.

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

inspect.CO_ASYNC_GENERATOR

این پرچم زمانی تنظیم می‌شود که شیء کد یک تابع تولیدگر ناهمگام باشد. هنگامی که شیء کد اجرا می‌شود، یک شیء تولیدگر ناهمگام بازمی‌گرداند. برای جزئیات بیشتر PEP 525 را ببینید.

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

inspect.CO_HAS_DOCSTRING

این پرچم زمانی تنظیم می‌شود که در کد منبع، برای شیء کد یک رشته مستند وجود داشته باشد. اگر تنظیم شده باشد، نخستین آیتم در co_consts خواهد بود.

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

inspect.CO_METHOD

این پرچم هنگامی تنظیم می‌شود که شیء کد، تابعی تعریف‌شده در محدوده کلاس باشد.

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

توجه

پرچم‌ها مخصوص CPython هستند و ممکن است در سایر پیاده‌سازی‌های پایتون تعریف نشده باشند. علاوه بر این، پرچم‌ها جزئیات پیاده‌سازی هستند و ممکن است در نسخه‌های آینده پایتون حذف یا منسوخ شوند. توصیه می‌شود برای هرگونه نیاز به درون‌نگری، از APIهای عمومی ماژول inspect استفاده کنید.

پرچم‌های بافر

class inspect.BufferFlags

این یک enum.IntFlag است که نشان‌دهنده‌ی پرچم‌هایی است که می‌توان آن‌ها را به متد __buffer__() اشیایی که پروتکل بافر را پیاده‌سازی می‌کنند، ارسال کرد.

معنای پرچم‌ها در انواع درخواست بافر توضیح داده شده است.

SIMPLE

WRITABLE

FORMAT

ND

STRIDES

C_CONTIGUOUS

F_CONTIGUOUS

ANY_CONTIGUOUS

INDIRECT

CONTIG

CONTIG_RO

STRIDED

STRIDED_RO

RECORDS

RECORDS_RO

FULL

FULL_RO

READ

WRITE

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

رابط خط فرمان

ماژول inspect همچنین قابلیت مقدماتی درون‌نگری را از خط فرمان فراهم می‌کند.

به‌طور پیش‌فرض، نام یک ماژول را می‌پذیرد و کد منبع آن ماژول را چاپ می‌کند. به‌جای آن، با افزودن یک دونقطه و نام کامل شیء هدف، می‌توان یک کلاس یا تابع درون ماژول را چاپ کرد.

--details

چاپ اطلاعات درباره شیء مشخص به جای کد منبع