انواع و اعضا¶

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

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

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

inspect.isfunction(object)¶

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

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

inspect.ispackage(object)¶

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

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

inspect.isgeneratorfunction(object)¶

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

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

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

تغییر یافته در نسخه‌ی 3.10.6: نوع‌دهی اردکی شیءهای شبیه‌تابع اکنون True برمی‌گردانند اگر شیء کد آن‌ها پرچم CO_GENERATOR را داشته باشد.

تغییر یافته در نسخه‌ی 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: نوع‌دهی اردکی شیءهای شبیه‌تابع اکنون True برمی‌گردانند اگر شیء کد آن‌ها پرچم CO_COROUTINE را داشته باشد.

تغییر یافته در نسخه‌ی 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: نوع‌دهی اردکی شیءهای شبیه‌به‌تابع اکنون True را برمی‌گردانند اگر شیء کد آن‌ها پرچم CO_ASYNC_GENERATOR را داشته باشد.

تغییر یافته در نسخه‌ی 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, *, inherit_class_doc=True, fallback_to_class_doc=True)¶

دریافت رشته‌ی مستندات برای یک شیء، که با cleandoc() پاک‌سازی شده است. اگر رشته‌ی مستندات برای یک شیء فراهم نشده باشد:

• اگر شیء یک کلاس باشد و inherit_class_doc برابر با درست (به‌طور پیش‌فرض) باشد، رشته‌ی مستندات از سلسله‌مراتب ارث‌بری بازیابی می‌شود؛

• اگر شیء یک متد، یک ویژگی یا یک توصیف‌گر باشد، رشته‌ی مستندات از سلسله‌مراتب ارث‌بری بازیابی می‌شود؛

• در غیر این صورت، اگر fallback_to_class_doc برابر با درست (به‌طور پیش‌فرض) باشد، رشته‌ی مستندات از کلاسِ شیء بازیابی می‌شود.

اگر رشته‌ی مستندات نامعتبر یا گم شده باشد، مقدار None را برمی‌گرداند.

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

تغییر یافته در نسخه‌ی 3.15: پارامترهای inherit_class_doc و fallback_to_class_doc اضافه شدند.

رشته‌های مستندسازی روی اشیاء cached_property اکنون در صورت عدم بازنویسی، به ارث برده می‌شوند.

inspect.getcomments(object)¶

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

inspect.getfile(object)¶

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

inspect.getmodule(object)¶

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

inspect.getsourcefile(object)¶

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

inspect.getsourcelines(object)¶

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

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

inspect.getsource(object)¶

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

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

inspect.cleandoc(doc)¶

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

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

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

شیء 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)

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

inspect.getclasstree(classes, unique=False)¶

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

inspect.getfullargspec(func, *, annotation_format=Format.VALUE)¶

نام‌ها و مقادیر پیش‌فرض پارامترهای یک تابع پایتون را دریافت کنید. یک 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 را حفظ کند.

می‌توان یک عضو از شمارشی annotationlib.Format را به پارامتر annotation_format ارسال کرد تا قالب حاشیه‌نویسی‌های برگردانده‌شده کنترل شود. برای مثال، از annotation_format=annotationlib.Format.STRING استفاده کنید تا حاشیه‌نویسی‌ها در قالب رشته برگردانده شوند. توجه داشته باشید که با قالب پیش‌فرض VALUE، ایجاد برخی از مشخصات آرگومان ممکن است یک استثنا ایجاد کند.

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

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

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

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

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 پیشین سازگار است).

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

آرگومان اختیاری 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.

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

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 همچنین قابلیت مقدماتی درون‌نگری را از خط فرمان فراهم می‌کند.

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

--details¶

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