17db96d56Sopenharmony_ci:mod:`pyclbr` --- Python module browser support 27db96d56Sopenharmony_ci=============================================== 37db96d56Sopenharmony_ci 47db96d56Sopenharmony_ci.. module:: pyclbr 57db96d56Sopenharmony_ci :synopsis: Supports information extraction for a Python module browser. 67db96d56Sopenharmony_ci 77db96d56Sopenharmony_ci.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 87db96d56Sopenharmony_ci 97db96d56Sopenharmony_ci**Source code:** :source:`Lib/pyclbr.py` 107db96d56Sopenharmony_ci 117db96d56Sopenharmony_ci-------------- 127db96d56Sopenharmony_ci 137db96d56Sopenharmony_ciThe :mod:`pyclbr` module provides limited information about the 147db96d56Sopenharmony_cifunctions, classes, and methods defined in a Python-coded module. The 157db96d56Sopenharmony_ciinformation is sufficient to implement a module browser. The 167db96d56Sopenharmony_ciinformation is extracted from the Python source code rather than by 177db96d56Sopenharmony_ciimporting the module, so this module is safe to use with untrusted code. 187db96d56Sopenharmony_ciThis restriction makes it impossible to use this module with modules not 197db96d56Sopenharmony_ciimplemented in Python, including all standard and optional extension 207db96d56Sopenharmony_cimodules. 217db96d56Sopenharmony_ci 227db96d56Sopenharmony_ci 237db96d56Sopenharmony_ci.. function:: readmodule(module, path=None) 247db96d56Sopenharmony_ci 257db96d56Sopenharmony_ci Return a dictionary mapping module-level class names to class 267db96d56Sopenharmony_ci descriptors. If possible, descriptors for imported base classes are 277db96d56Sopenharmony_ci included. Parameter *module* is a string with the name of the module 287db96d56Sopenharmony_ci to read; it may be the name of a module within a package. If given, 297db96d56Sopenharmony_ci *path* is a sequence of directory paths prepended to ``sys.path``, 307db96d56Sopenharmony_ci which is used to locate the module source code. 317db96d56Sopenharmony_ci 327db96d56Sopenharmony_ci This function is the original interface and is only kept for back 337db96d56Sopenharmony_ci compatibility. It returns a filtered version of the following. 347db96d56Sopenharmony_ci 357db96d56Sopenharmony_ci 367db96d56Sopenharmony_ci.. function:: readmodule_ex(module, path=None) 377db96d56Sopenharmony_ci 387db96d56Sopenharmony_ci Return a dictionary-based tree containing a function or class 397db96d56Sopenharmony_ci descriptors for each function and class defined in the module with a 407db96d56Sopenharmony_ci ``def`` or ``class`` statement. The returned dictionary maps 417db96d56Sopenharmony_ci module-level function and class names to their descriptors. Nested 427db96d56Sopenharmony_ci objects are entered into the children dictionary of their parent. As 437db96d56Sopenharmony_ci with readmodule, *module* names the module to be read and *path* is 447db96d56Sopenharmony_ci prepended to sys.path. If the module being read is a package, the 457db96d56Sopenharmony_ci returned dictionary has a key ``'__path__'`` whose value is a list 467db96d56Sopenharmony_ci containing the package search path. 477db96d56Sopenharmony_ci 487db96d56Sopenharmony_ci.. versionadded:: 3.7 497db96d56Sopenharmony_ci Descriptors for nested definitions. They are accessed through the 507db96d56Sopenharmony_ci new children attribute. Each has a new parent attribute. 517db96d56Sopenharmony_ci 527db96d56Sopenharmony_ciThe descriptors returned by these functions are instances of 537db96d56Sopenharmony_ciFunction and Class classes. Users are not expected to create instances 547db96d56Sopenharmony_ciof these classes. 557db96d56Sopenharmony_ci 567db96d56Sopenharmony_ci 577db96d56Sopenharmony_ci.. _pyclbr-function-objects: 587db96d56Sopenharmony_ci 597db96d56Sopenharmony_ciFunction Objects 607db96d56Sopenharmony_ci---------------- 617db96d56Sopenharmony_ciClass :class:`Function` instances describe functions defined by def 627db96d56Sopenharmony_cistatements. They have the following attributes: 637db96d56Sopenharmony_ci 647db96d56Sopenharmony_ci 657db96d56Sopenharmony_ci.. attribute:: Function.file 667db96d56Sopenharmony_ci 677db96d56Sopenharmony_ci Name of the file in which the function is defined. 687db96d56Sopenharmony_ci 697db96d56Sopenharmony_ci 707db96d56Sopenharmony_ci.. attribute:: Function.module 717db96d56Sopenharmony_ci 727db96d56Sopenharmony_ci The name of the module defining the function described. 737db96d56Sopenharmony_ci 747db96d56Sopenharmony_ci 757db96d56Sopenharmony_ci.. attribute:: Function.name 767db96d56Sopenharmony_ci 777db96d56Sopenharmony_ci The name of the function. 787db96d56Sopenharmony_ci 797db96d56Sopenharmony_ci 807db96d56Sopenharmony_ci.. attribute:: Function.lineno 817db96d56Sopenharmony_ci 827db96d56Sopenharmony_ci The line number in the file where the definition starts. 837db96d56Sopenharmony_ci 847db96d56Sopenharmony_ci 857db96d56Sopenharmony_ci.. attribute:: Function.parent 867db96d56Sopenharmony_ci 877db96d56Sopenharmony_ci For top-level functions, None. For nested functions, the parent. 887db96d56Sopenharmony_ci 897db96d56Sopenharmony_ci .. versionadded:: 3.7 907db96d56Sopenharmony_ci 917db96d56Sopenharmony_ci 927db96d56Sopenharmony_ci.. attribute:: Function.children 937db96d56Sopenharmony_ci 947db96d56Sopenharmony_ci A dictionary mapping names to descriptors for nested functions and 957db96d56Sopenharmony_ci classes. 967db96d56Sopenharmony_ci 977db96d56Sopenharmony_ci .. versionadded:: 3.7 987db96d56Sopenharmony_ci 997db96d56Sopenharmony_ci 1007db96d56Sopenharmony_ci.. attribute:: Function.is_async 1017db96d56Sopenharmony_ci 1027db96d56Sopenharmony_ci ``True`` for functions that are defined with the ``async`` prefix, ``False`` otherwise. 1037db96d56Sopenharmony_ci 1047db96d56Sopenharmony_ci .. versionadded:: 3.10 1057db96d56Sopenharmony_ci 1067db96d56Sopenharmony_ci 1077db96d56Sopenharmony_ci.. _pyclbr-class-objects: 1087db96d56Sopenharmony_ci 1097db96d56Sopenharmony_ciClass Objects 1107db96d56Sopenharmony_ci------------- 1117db96d56Sopenharmony_ciClass :class:`Class` instances describe classes defined by class 1127db96d56Sopenharmony_cistatements. They have the same attributes as Functions and two more. 1137db96d56Sopenharmony_ci 1147db96d56Sopenharmony_ci 1157db96d56Sopenharmony_ci.. attribute:: Class.file 1167db96d56Sopenharmony_ci 1177db96d56Sopenharmony_ci Name of the file in which the class is defined. 1187db96d56Sopenharmony_ci 1197db96d56Sopenharmony_ci 1207db96d56Sopenharmony_ci.. attribute:: Class.module 1217db96d56Sopenharmony_ci 1227db96d56Sopenharmony_ci The name of the module defining the class described. 1237db96d56Sopenharmony_ci 1247db96d56Sopenharmony_ci 1257db96d56Sopenharmony_ci.. attribute:: Class.name 1267db96d56Sopenharmony_ci 1277db96d56Sopenharmony_ci The name of the class. 1287db96d56Sopenharmony_ci 1297db96d56Sopenharmony_ci 1307db96d56Sopenharmony_ci.. attribute:: Class.lineno 1317db96d56Sopenharmony_ci 1327db96d56Sopenharmony_ci The line number in the file where the definition starts. 1337db96d56Sopenharmony_ci 1347db96d56Sopenharmony_ci 1357db96d56Sopenharmony_ci.. attribute:: Class.parent 1367db96d56Sopenharmony_ci 1377db96d56Sopenharmony_ci For top-level classes, None. For nested classes, the parent. 1387db96d56Sopenharmony_ci 1397db96d56Sopenharmony_ci .. versionadded:: 3.7 1407db96d56Sopenharmony_ci 1417db96d56Sopenharmony_ci 1427db96d56Sopenharmony_ci.. attribute:: Class.children 1437db96d56Sopenharmony_ci 1447db96d56Sopenharmony_ci A dictionary mapping names to descriptors for nested functions and 1457db96d56Sopenharmony_ci classes. 1467db96d56Sopenharmony_ci 1477db96d56Sopenharmony_ci .. versionadded:: 3.7 1487db96d56Sopenharmony_ci 1497db96d56Sopenharmony_ci 1507db96d56Sopenharmony_ci.. attribute:: Class.super 1517db96d56Sopenharmony_ci 1527db96d56Sopenharmony_ci A list of :class:`Class` objects which describe the immediate base 1537db96d56Sopenharmony_ci classes of the class being described. Classes which are named as 1547db96d56Sopenharmony_ci superclasses but which are not discoverable by :func:`readmodule_ex` 1557db96d56Sopenharmony_ci are listed as a string with the class name instead of as 1567db96d56Sopenharmony_ci :class:`Class` objects. 1577db96d56Sopenharmony_ci 1587db96d56Sopenharmony_ci 1597db96d56Sopenharmony_ci.. attribute:: Class.methods 1607db96d56Sopenharmony_ci 1617db96d56Sopenharmony_ci A dictionary mapping method names to line numbers. This can be 1627db96d56Sopenharmony_ci derived from the newer children dictionary, but remains for 1637db96d56Sopenharmony_ci back-compatibility. 164