Delete tools/telemetry.

tools/telemetry/third_party/modulegraph/doc/modulegraph.rst

-:mod:`modulegraph.modulegraph` --- Find modules used by a script
-================================================================
-
-.. module:: modulegraph.modulegraph
-   :synopsis: Find modules used by a script
-
-This module defines :class:`ModuleGraph`, which is used to find
-the dependencies of scripts using bytecode analysis.
-
-A number of APIs in this module refer to filesystem path. Those paths can refer to
-files inside zipfiles (for example when there are zipped egg files on :data:`sys.path`).
-Filenames referring to entries in a zipfile are not marked any way, if ``"somepath.zip"``
-refers to a zipfile, that is ``"somepath.zip/embedded/file"`` will be used to refer to
-``embedded/file`` inside the zipfile.
-
-The actual graph
-----------------
-
-.. class:: ModuleGraph([path[, excludes[, replace_paths[, implies[, graph[, debug]]]]]])
-
-   Create a new ModuleGraph object. Use the :meth:`run_script` method to add scripts,
-   and their dependencies to the graph.
-
-   :param path: Python search path to use, defaults to :data:`sys.path`
-   :param excludes: Iterable with module names that should not be included as a dependency
-   :param replace_paths: List of pathname rewrites ``(old, new)``. When this argument is
-     supplied the ``co_filename`` attributes of code objects get rewritten before scanning
-     them for dependencies.
-   :param implies: Implied module dependencies, a mapping from a module name to the list
-     of modules it depends on. Use this to tell modulegraph about dependencies that cannot
-     be found by code inspection (such as imports from C code or using the :func:`__import__`
-     function).
-   :param graph: A precreated :class:`Graph <altgraph.Graph.Graph>` object to use, the
-     default is to create a new one.
-   :param debug: The :class:`ObjectGraph <altgraph.ObjectGraph.ObjectGraph>` debug level.
-
-
-.. method:: run_script(pathname[, caller])
-
-   Create, and return,  a node by path (not module name). The *pathname* should
-   refer to a Python source file and will be scanned for dependencies.
-
-   The optional argument *caller* is the the node that calls this script,
-   and is used to add a reference in the graph.
-
-.. method:: import_hook(name[[, caller[, fromlist[, level, [, attr]]]])
-
-   Import a module and analyse its dependencies
-
-   :arg name:     The module name
-   :arg caller:   The node that caused the import to happen
-   :arg fromlist: The list of names to import, this is an empty list for
-      ``import name`` and a list of names for ``from name import a, b, c``.
-   :arg level:    The import level. The value should be ``-1`` for classical Python 2
-     imports, ``0`` for absolute imports and a positive number for relative imports (
-     where the value is the number of leading dots in the imported name).
-   :arg attr:     Attributes for the graph edge.
-
-
-.. method:: implyNodeReference(node, other, edgeData=None)
-
-   Explictly mark that *node* depends on *other*. Other is either
-   a :class:`node <Node>` or the name of a module that will be
-   searched for as if it were an absolute import.
-
-
-.. method:: createReference(fromnode, tonode[, edge_data])
-
-   Create a reference from *fromnode* to *tonode*, with optional edge data.
-
-   The default for *edge_data* is ``"direct"``.
-
-.. method:: getReferences(fromnode)
-
-   Yield all nodes that *fromnode* refers to. That is, all modules imported
-   by *fromnode*.
-
-   Node :data:`None` is the root of the graph, and refers to all notes that were
-   explicitly imported by :meth:`run_script` or :meth:`import_hook`, unless you use
-   an explicit parent with those methods.
-
-   .. versionadded:: 0.11
-
-.. method:: getReferers(tonode, collapse_missing_modules=True)
-
-   Yield all nodes that refer to *tonode*. That is, all modules that import
-   *tonode*.
-
-   If *collapse_missing_modules* is false this includes refererences from
-   :class:`MissingModule` nodes, otherwise :class:`MissingModule` nodes
-   are replaced by the "real" nodes that reference this missing node.
-
-   .. versionadded:: 0.12
-
-.. method:: foldReferences(pkgnode)
-
-   Hide all submodule nodes for package *pkgnode* and add ingoing and outgoing
-   edges to *pkgnode* based on the edges from the submodule nodes.
-
-   This can be used to simplify a module graph: after folding 'email' all
-   references to modules in the 'email' package are references to the package.
-
-   .. versionadded: 0.11
-
-.. method:: findNode(name)
-
-   Find a node by identifier.  If a node by that identifier exists, it will be returned.
-
-   If a lazy node exists by that identifier with no dependencies (excluded), it will be
-   instantiated and returned.
-
-   If a lazy node exists by that identifier with dependencies, it and its
-   dependencies will be instantiated and scanned for additional depende
-
-
-
-.. method:: create_xref([out])
-
-   Write an HTML file to the *out* stream (defaulting to :data:`sys.stdout`).
-
-   The HTML file contains a textual description of the dependency graph.
-
-
-
-.. method:: graphreport([fileobj[, flatpackages]])
-
-   .. todo:: To be documented
-
-
-
-.. method:: report()
-
-   Print a report to stdout, listing the found modules with their
-   paths, as well as modules that are missing, or seem to be missing.
-
-
-Mostly internal methods
-.......................
-
-The methods in this section should be considered as methods for subclassing at best,
-please let us know if you need these methods in your code as they are on track to be
-made private methods before the 1.0 release.
-
-.. warning:: The methods in this section will be refactored in a future release,
-   the current architecture makes it unnecessarily hard to write proper tests.
-
-.. method:: determine_parent(caller)
-
-   Returns the node of the package root voor *caller*. If *caller* is a package
-   this is the node itself, if the node is a module in a package this is the
-   node of for the package and otherwise the *caller* is not a package and
-   the result is :data:`None`.
-
-.. method:: find_head_package(parent, name[, level])
-
-   .. todo:: To be documented
-
-
-.. method:: load_tail(mod, tail)
-
-   This method is called to load the rest of a dotted name after loading the root
-   of a package. This will import all intermediate modules as well (using
-   :meth:`import_module`), and returns the module :class:`node <Node>` for the
-   requested node.
-
-   .. note:: When *tail* is empty this will just return *mod*.
-
-   :arg mod:   A start module (instance of :class:`Node`)
-   :arg tail:  The rest of a dotted name, can be empty
-   :raise ImportError: When the requested (or one of its parents) module cannot be found
-   :returns: the requested module
-
-
-
-.. method:: ensure_fromlist(m, fromlist)
-
-   Yield all submodules that would be imported when importing *fromlist*
-   from *m* (using ``from m import fromlist...``).
-
-   *m* must be a package and not a regular module.
-
-.. method:: find_all_submodules(m)
-
-   Yield the filenames for submodules of in the same package as *m*.
-
-
-
-.. method:: import_module(partname, fqname, parent)
-
-   Perform import of the module with basename *partname* (``path``) and
-   full name *fqname* (``os.path``). Import is performed by *parent*.
-
-   This will create a reference from the parent node to the
-   module node and will load the module node when it is not already
-   loaded.
-
-
-
-.. method:: load_module(fqname, fp, pathname, (suffix, mode, type))
-
-   Load the module named *fqname* from the given *pathame*. The
-   argument *fp* is either :data:`None`, or a stream where the
-   code for the Python module can be loaded (either byte-code or
-   the source code). The *(suffix, mode, type)* tuple are the
-   suffix of the source file, the open mode for the file and the
-   type of module.
-
-   Creates a node of the right class and processes the dependencies
-   of the :class:`node <Node>` by scanning the byte-code for the node.
-
-   Returns the resulting :class:`node <Node>`.
-
-
-
-.. method:: scan_code(code, m)
-
-   Scan the *code* object for module *m* and update the dependencies of
-   *m* using the import statemets found in the code.
-
-   This will automaticly scan the code for nested functions, generator
-   expressions and list comprehensions as well.
-
-
-
-.. method:: load_package(fqname, pathname)
-
-   Load a package directory.
-
-
-
-.. method:: find_module(name, path[, parent])
-
-   Locates a module named *name* that is not yet part of the
-   graph. This method will raise :exc:`ImportError` when
-   the module cannot be found or when it is already part
-   of the graph. The *name* can not be a dotted name.
-
-   The *path* is the search path used, or :data:`None` to
-   use the default path.
-
-   When the *parent* is specified *name* refers to a
-   subpackage of *parent*, and *path* should be the
-   search path of the parent.
-
-   Returns the result of the global function
-   :func:`find_module <modulegraph.modulegraph.find_module>`.
-
-
-.. method:: itergraphreport([name[, flatpackages]])
-
-   .. todo:: To be documented
-
-
-
-.. method:: replace_paths_in_code(co)
-
-   Replace the filenames in code object *co* using the *replace_paths* value that
-   was passed to the contructor. Returns the rewritten code object.
-
-
-
-.. method:: calc_setuptools_nspackages()
-
-   Returns a mapping from package name to a list of paths where that package
-   can be found in ``--single-version-externally-managed`` form.
-
-   This method is used to be able to find those packages: these use
-   a magic ``.pth`` file to ensure that the package is added to :data:`sys.path`,
-   as they do not contain an ``___init__.py`` file.
-
-   Packages in this form are used by system packages and the "pip"
-   installer.
-
-
-Graph nodes
------------
-
-The :class:`ModuleGraph` contains nodes that represent the various types of modules.
-
-.. class:: Alias(value)
-
-   This is a subclass of string that is used to mark module aliases.
-
-
-
-.. class:: Node(identifier)
-
-   Base class for nodes, which provides the common functionality.
-
-   Nodes can by used as mappings for storing arbitrary data in the node.
-
-   Nodes are compared by comparing their *identifier*.
-
-.. data:: debug
-
-   Debug level (integer)
-
-.. data:: graphident
-
-   The node identifier, this is the value of the *identifier* argument
-   to the constructor.
-
-.. data:: identifier
-
-   The node identifier, this is the value of the *identifier* argument
-   to the constructor.
-
-.. data:: filename
-
-   The filename associated with this node.
-
-.. data:: packagepath
-
-   The value of ``__path__`` for this node.
-
-.. data:: code
-
-   The :class:`code object <types.CodeObject>` associated with this node
-
-.. data:: globalnames
-
-   The set of global names that are assigned to in this module. This
-   includes those names imported through startimports of Python modules.
-
-.. data:: startimports
-
-   The set of startimports this module did that could not be resolved,
-   ie. a startimport from a non-Python module.
-
-
-.. method:: __contains__(name)
-
-   Return if there is a value associated with *name*.
-
-   This method is usually accessed as ``name in aNode``.
-
-.. method:: __setitem__(name, value)
-
-   Set the value of *name* to *value*.
-
-   This method is usually accessed as ``aNode[name] = value``.
-
-.. method:: __getitem__(name)
-
-   Returns the value of *name*, raises :exc:`KeyError` when
-   it cannot be found.
-
-   This method is usually accessed as ``value = aNode[name]``.
-
-.. method:: get(name[, default])
-
-   Returns the value of *name*, or the default value when it
-   cannot be found. The *default* is :data:`None` when not specified.
-
-.. method:: infoTuple()
-
-   Returns a tuple with information used in the :func:`repr`
-   output for the node. Subclasses can add additional informations
-   to the result.
-
-
-.. class:: AliasNode (name, node)
-
-   A node that represents an alias from a name to another node.
-
-   The value of attribute *graphident* for this node will be the
-   value of *name*, the other :class:`Node` attributed are
-   references to those attributed in *node*.
-
-.. class:: BadModule(identifier)
-
-   Base class for nodes that should be ignored for some reason
-
-.. class:: ExcludedModule(identifier)
-
-   A module that is explicitly excluded.
-
-.. class:: MissingModule(identifier)
-
-   A module that is imported but cannot be located.
-
-
-
-.. class:: Script(filename)
-
-   A python script.
-
-   .. data:: filename
-
-      The filename for the script
-
-.. class:: BaseModule(name[, filename[, path]])
-
-    The base class for actual modules. The *name* is
-    the possibly dotted module name, *filename* is the
-    filesystem path to the module and *path* is the
-    value of ``__path__`` for the module.
-
-.. data:: graphident
-
-   The name of the module
-
-.. data:: filename
-
-   The filesystem path to the module.
-
-.. data:: path
-
-   The value of ``__path__`` for this module.
-
-.. class:: BuiltinModule(name)
-
-   A built-in module (on in :data:`sys.builtin_module_names`).
-
-.. class:: SourceModule(name)
-
-   A module for which the python source code is available.
-
-.. class:: InvalidSourceModule(name)
-
-   A module for which the python source code is available, but where
-   that source code cannot be compiled (due to syntax errors).
-
-   This is a subclass of :class:`SourceModule`.
-
-   .. versionadded:: 0.12
-
-.. class:: CompiledModule(name)
-
-   A module for which only byte-code is available.
-
-.. class:: Package(name)
-
-   Represents a python package
-
-.. class:: NamespacePackage(name)
-
-   Represents a python namespace package.
-
-   This is a subclass of :class:`Package`.
-
-.. class:: Extension(name)
-
-   A native extension
-
-
-.. warning:: A number of other node types are defined in the module. Those modules aren't
-   used by modulegraph and will be removed in a future version.
-
-
-Edge data
----------
-
-The edges in a module graph by default contain information about the edge, represented
-by an instance of :class:`DependencyInfo`.
-
-.. class:: DependencyInfo(conditional, function, tryexcept, fromlist)
-
-   This class is a :func:`namedtuple <collections.namedtuple>` for representing
-   the information on a dependency between two modules.
-
-   All attributes can be used to deduce if a dependency is essential or not, and
-   are particularly useful when reporting on missing modules (dependencies on
-   :class:`MissingModule`).
-
-   .. data:: fromlist
-
-      A boolean that is true iff the target of the edge is named in the "import"
-      list of a "from" import ("from package import module").
-
-      When the target module is imported multiple times this attribute is false
-      unless all imports are in "import" list of a "from" import.
-
-   .. data:: function
-
-      A boolean that is true iff the import is done inside a function definition,
-      and is false for imports in module scope (or class scope for classes that
-      aren't definined in a function).
-
-   .. data:: tryexcept
-
-      A boolean that is true iff the import that is done in the "try" or "except"
-      block of a try statement (but not in the "else" block).
-
-   .. data:: conditional
-
-      A boolean that is true iff the import is done in either block of an "if"
-      statement.
-
-   When the target of the edge is imported multiple times the :data:`function`,
-   :data:`tryexcept` and :data:`conditional` attributes of all imports are
-   merged: when there is an import where all these attributes are false the
-   attributes are false, otherwise each attribute is set to true if it is
-   true for at least one of the imports.
-
-   For example, when a module is imported both in a try-except statement and
-   furthermore is imported in a function (in two separate statements),
-   both :data:`tryexcept` and :data:`function` will be true.  But if there
-   is a third unconditional toplevel import for that module as well all
-   three attributes are false.
-
-   .. warning::
-
-      All attributes but :data:`fromlist` will be false when the source of
-      a dependency is scanned from a byte-compiled module instead of a python
-      source file. The :data:`fromlist` attribute will stil be set correctly.
-
-Utility functions
------------------
-
-.. function:: find_module(name[, path])
-
-   A version of :func:`imp.find_module` that works with zipped packages (and other
-   :pep:`302` importers).
-
-.. function:: moduleInfoForPath(path)
-
-   Return the module name, readmode and type for the file at *path*, or
-   None if it doesn't seem to be a valid module (based on its name).
-
-.. function:: addPackagePath(packagename, path)
-
-   Add *path* to the value of ``__path__`` for the package named *packagename*.
-
-.. function:: replacePackage(oldname, newname)
-
-   Rename *oldname* to *newname* when it is found by the module finder. This
-   is used as a workaround for the hack that the ``_xmlplus`` package uses
-   to inject itself in the ``xml`` namespace.
-
-