Python/dir

تستخدم الدالة الداخلية dir()‎ لمعرفة الأسماء التي تعرّفها الوحدة، وتعيد هذه الداة قائمة مرتّبة من السلاسل النصية:

>>> import fibo, sys
>>> dir(fibo)
['__name__', 'fib', 'fib2']
>>> dir(sys)  
['__displayhook__', '__doc__', '__excepthook__', '__loader__', '__name__',
 '__package__', '__stderr__', '__stdin__', '__stdout__',
 '_clear_type_cache', '_current_frames', '_debugmallocstats', '_getframe',
 '_home', '_mercurial', '_xoptions', 'abiflags', 'api_version', 'argv',
 'base_exec_prefix', 'base_prefix', 'builtin_module_names', 'byteorder',
 'call_tracing', 'callstats', 'copyright', 'displayhook',
 'dont_write_bytecode', 'exc_info', 'excepthook', 'exec_prefix',
 'executable', 'exit', 'flags', 'float_info', 'float_repr_style',
 'getcheckinterval', 'getdefaultencoding', 'getdlopenflags',
 'getfilesystemencoding', 'getobjects', 'getprofile', 'getrecursionlimit',
 'getrefcount', 'getsizeof', 'getswitchinterval', 'gettotalrefcount',
 'gettrace', 'hash_info', 'hexversion', 'implementation', 'int_info',
 'intern', 'maxsize', 'maxunicode', 'meta_path', 'modules', 'path',
 'path_hooks', 'path_importer_cache', 'platform', 'prefix', 'ps1',
 'setcheckinterval', 'setdlopenflags', 'setprofile', 'setrecursionlimit',
 'setswitchinterval', 'settrace', 'stderr', 'stdin', 'stdout',
 'thread_info', 'version', 'version_info', 'warnoptions']

في حال عدم تمرير أي وسائط فإنّ الدالة dir()‎ تسرد الأسماء المعرّفة في الوقت الحاضر:

>>> a = [1, 2, 3, 4, 5]
>>> import fibo
>>> fib = fibo.fib
>>> dir()
['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys']

لاحظ أنّ هذه الدالة تسرد جميع أنواع الأسماء: المتغيرات والوحدات والدوال وغيرها، ولكنّها لا تسرد أسماء الدوال والمتغيرات الداخلية، وللحصول على قائمة بها يجب استخدام الدالة تمرير الوحدة القياسية builtins كوسيط للدالة dir()‎:

>>> import builtins
>>> dir(builtins)  
['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',
 'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning',
 'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError',
 'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning',
 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',
 'FileExistsError', 'FileNotFoundError', 'FloatingPointError',
 'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError',
 'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError',
 'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError',
 'MemoryError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented',
 'NotImplementedError', 'OSError', 'OverflowError',
 'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError',
 'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning',
 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError',
 'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError',
 'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError',
 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning',
 'ValueError', 'Warning', 'ZeroDivisionError', '_', '__build_class__',
 '__debug__', '__doc__', '__import__', '__name__', '__package__', 'abs',
 'all', 'any', 'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'callable',
 'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits',
 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'exec', 'exit',
 'filter', 'float', 'format', 'frozenset', 'getattr', 'globals', 'hasattr',
 'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance', 'issubclass',
 'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memoryview',
 'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property',
 'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice',
 'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars',
 'zip']

ملاحظات

إن كان الكائن المُمرّر إلى الدّالة يحتوي على تابعٍ باسم ‎_‎_‎dir‎_‎_()‎، فسيُستدعى التّابع، والذي يجب عليه أن يُعيد قائمة خاصيّات الكائن. يسمح هذا للكائنات التي تُعرّف التّابع ‎_‎_‎getattr‎_‎_()‎ أو التّابع ‎_‎_‎getattribute‎_‎_()‎ بتغيير كيفيّة عرض الدّالة ‎dir‎()‎ لخاصيّات الكائن.

إن لم يكن التّابع الخاصّ ‎_‎_‎dir‎_‎_()‎ موجودًا، فستُحاول الدّالة ‎dir‎()‎ الحصول على معلومات حول الكائن من الخاصيّة ‎_‎_‎dict‎_‎_‎ الخاصّة به إن عُرّفَت، وتحصل على معلومات كذلك من نوع الكائن.

تختلف آليّة عمل الدّالة حسب نوع الكائن، وذلك لمُحاولة الدّالة توفيرَ أكثر معلومات مُفيدة عوضًا عن عرضها كلّها:

• إن كان الكائن وحدةً، فستحتوي القائمة على أسماء خاصيّات الوحدة.
• إن كان الكائن نوعًا (type) أو كائن صنف (class object)، فستحتوي القائمة على أسماء خاصيّاته وخاصيّات الأصناف التي ورِثَ منها تعاوديًّا (recursively).
• في غير ما سبق من حالات، ستحتوي القائمة على أسماء خاصيّات الكائن، وأسماء خاصيّات صنفه، وأسماء خاصيّات الأصناف التي ورثت منها أصنافه تعاوديًّا.

ولأنّ الدّالة تُستخدم أساسًا كأداة لاستكشاف معلومات حول الكائنات في سطر الأوامر التّفاعليّ، فإنّها تُحاول توفيرَ أكثر معلومات مُفيدة عوضًا عن عرضها كلّها، وقد تتغيّر المعلومات التّي تعرضها من نسخة Python إلى نُسخة أخرى.

مصادر

• قسم الدالة dir في صفحة Functions في توثيق Python الرسمي.
• صفحة Modules في توثيق بايثون الرسمي.