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