Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(4)

Unified Diff: tools/telemetry/third_party/modulegraph/doc/modulegraph.rst

Issue 1647513002: Delete tools/telemetry. (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master
Patch Set: Created 4 years, 11 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View side-by-side diff with in-line comments
Download patch
Index: tools/telemetry/third_party/modulegraph/doc/modulegraph.rst
diff --git a/tools/telemetry/third_party/modulegraph/doc/modulegraph.rst b/tools/telemetry/third_party/modulegraph/doc/modulegraph.rst
deleted file mode 100644
index 60566e7e73b9d94742fff6bc8bd4e0eb3f003620..0000000000000000000000000000000000000000
--- a/tools/telemetry/third_party/modulegraph/doc/modulegraph.rst
+++ /dev/null
@@ -1,531 +0,0 @@
-: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.
-
-
« no previous file with comments | « tools/telemetry/third_party/modulegraph/doc/license.rst ('k') | tools/telemetry/third_party/modulegraph/doc/util.rst » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698