Jython 2.7.4 · org.python.indexer.Indexer · APIdia, the JavaDoc alternative

Modifier and Type	Field and Description
private boolean	aggressiveAssertions
private Map<String, NBinding>	allBindings A map of all bindings created, keyed on their qnames.
private AstCache	astCache Manages a store of serialized ASTs.
public Builtins	builtins Manages the built-in modules -- that is, modules from the standard Python library that are implemented in C and consequently have no Python source.
public String	currentFile
public Set<String>	failedModules When resolving imports we look in various possible locations.
public Scope	globaltable The top-level (builtin) scope.
public static Indexer	idx The global indexer instance.
private int	loadedFiles
private Map<Ref, List<NBinding>>	locations A map of references to their referenced bindings.
private Logger	logger
public Scope	moduleTable A scope containing bindings for all modules currently loaded by the indexer.
private int	nloc
private int	nparsing
private int	nprob
private int	nunbound
private int	nunknown
public Map<String, List<Diagnostic>>	parseErrs
public List<String>	path
public Map<String, List<Diagnostic>>	problems Diagnostics.
public String	projDir
private Map<String, Set<String>>	unresolvedModules This set tracks module imports that could not be resolved.

Access	Constructor and Description
public	Indexer()

Method Summary

Modifier and Type	Method and Description
pack-priv void	addFileErr(String file, int beg, int end, String msg)
public void	addPath(String p) Adds the specified absolute path to the module search path.
public void	addPaths(List<String> p) Adds the specified absolute paths to the module search path.
public boolean	aggressiveAssertionsEnabled()
public void	clearAstCache() Clears the AST cache (to free up memory).
public void	clearModuleTable() Clears the module table, discarding all resolved ASTs (modules) and their scope information.
private void	convertCallToNew(Ref ref, List<NBinding> bindings)
private int	countDefs(List<NBinding> bindings)
private void	duplicateBindingFailure(NBinding newb, NBinding oldb)
public void	enableAggressiveAssertions(boolean enable) Configures whether the indexer should abort with an exception when it encounters an internal error or unexpected program state.
public void	fine(String msg)
public void	finer(String msg)
public List<Outliner.Entry>	Returns: a list of entries constituting the file outline. Returns an empty list if the indexer hasn't indexed that path. generateOutline(String the file for which to build the outline path) Create an outline for a file in the index.
private AstCache	getAstCache()
public NModule	getAstForFile(String file) Returns the syntax tree for `file`.
public NModule	getAstForFile(String file, String contents) Returns the syntax tree for `file`.
public Map<String, NBinding>	getBindings() Returns the mutable set of all bindings collected, keyed on their qnames.
public NModuleType	getBuiltinModule(String qname)
pack-priv NModuleType	getCachedModule(String file)
public List<Diagnostic>	getDiagnosticsForFile(String file) Returns the list, possibly empty but never `null`, of errors and warnings generated in the file.
pack-priv List<Diagnostic>	getFileErrs(String file, Map<String, List<Diagnostic>> map)
public List<String>	getLoadedFiles()
public List<String>	getLoadPath() Returns the module search path -- the project directory followed by any paths that were added by `addPath(String)`.
public Logger	getLogger()
public NModuleType	getModuleForFile(String absolute file path file) Returns (loading/resolving if necessary) the module for a given source path.
pack-priv List<Diagnostic>	getParseErrs(String file)
public String	getStatusReport() Report resolution rate and other statistics data.
public void	handleException(String descriptive message; ok to be `null` msg, Throwable cause) If aggressive assertions are enabled, propagates the passed `Throwable`, wrapped in an `IndexingException`.
public void	info(String msg)
private boolean	isInLoadPath(File dir)
public boolean	isLibFile(String file)
public NModuleType	loadFile(String path) Loads a file and all its ancestor packages.
public NModuleType	Returns: `null` if `path` could not be loaded loadFile(String the absolute path to the file or directory. If it is a directory, it is suffixed with "__init__.py", and only that file is loaded from the directory. path, boolean `true` to skip loading ancestor packages skipChain) Load, parse and analyze a source file given its absolute path.
public void	loadFileRecursive(String fullname) Load all Python source files recursively if the given fullname is a directory; otherwise just load a file.
public NModuleType	loadModule(String a module name. Can be a relative path to a directory or a file (without the extension) or a possibly-qualified module name. If it is a module name, cannot contain leading dots. modname) This method searches the module path for the module `modname`.
private void	loadParentPackage(String file) When we load a module, load all its parent packages, top-down.
public NModuleType	loadString(String a path for reporting/caching purposes. The filename component is used to construct the module qualified name. path, String contents) Loads a module from a string containing the module contents.
public void	log(Level level, String msg)
public NBinding	lookupQname(String qname) Return the binding for `qname`, or `null` if not known.
public NType	lookupQnameType(String qname) Return the type for `qname`, or `null` if not known.
public int	numFilesLoaded()
private NModuleType	parseAndResolve(String file)
private NModuleType	parseAndResolve(String the filename file, String optional file contents. If `null`, loads the file contents from disk. contents) Parse a file or string and return its module parse tree.
private String	percent(int num, int total)
private String	printBindings()
public NBinding	putBinding(NBinding b)
public void	putLocation(NNode a node referring to a name binding. Typically a `NName`, `NStr` or `NUrl`. node, NBinding b) Add a reference to binding `b` at AST node `node`.
public void	putLocation(Ref ref, NBinding b)
public void	putProblem(NNode loc, String msg)
public void	putProblem(String file, int beg, int end, String msg)
public void	ready() Performs final indexing-building passes, including marking references to undeclared variables.
public void	recordUnresolvedModule(String module qname, e.g. "org.foo.bar" qname, String the file where the unresolved import occurred file) Reports a failed module or submodule resolution.
public void	release() Releases all resources for the current indexer.
public void	removeBinding(NBinding b)
public void	reportFailedAssertion(String a descriptive message about the problem msg) Signals a failed assertion about the state of the indexer or index.
public void	setLogger(Logger logger)
public void	setPath(List<String> path) Sets the module search path to the specified list of absolute paths.
public void	setProjectDir(String cd)
public void	severe(String msg)
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.
public void	updateLocation(Ref node, NBinding b) Add `node` as a reference to binding `b`, removing `node` from any other binding ref-lists that it may have occupied.
public void	warn(String msg)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

aggressiveAssertions	back to summary
private boolean aggressiveAssertions

allBindings	back to summary
private Map<String, NBinding> allBindings A map of all bindings created, keyed on their qnames.

astCache	back to summary
private AstCache astCache Manages a store of serialized ASTs. ANTLR parsing is one of the slower and more expensive phases of indexing; reusing parse trees can help with resource utilization when indexing several projects (or re-indexing one project).

builtins	back to summary
public Builtins builtins Manages the built-in modules -- that is, modules from the standard Python library that are implemented in C and consequently have no Python source.

currentFile	back to summary
public String currentFile

failedModules	back to summary
public Set<String> failedModules When resolving imports we look in various possible locations. This set keeps track of modules we attempted but didn't find.

globaltable	back to summary
public Scope globaltable The top-level (builtin) scope.

idx	back to summary
public static Indexer idx The global indexer instance. Provides convenient access to global resources, as well as easy cleanup of resources after the index is built.

loadedFiles	back to summary
private int loadedFiles

locations	back to summary
private Map<Ref, List<NBinding>> locations A map of references to their referenced bindings. Most nodes will refer to a single binding, and few ever refer to more than two. One situation in which a multiple reference can occur is the an attribute of a union type. For instance: class A: def foo(self): pass class B: def foo(self): pass if some_condition: var = A() else var = B() var.foo() # foo here refers to both A.foo and B.foo

locations

back to summary

private Map<Ref, List<NBinding>> locations

A map of references to their referenced bindings. Most nodes will refer to a single binding, and few ever refer to more than two. One situation in which a multiple reference can occur is the an attribute of a union type. For instance:

  class A:
    def foo(self): pass
  class B:
    def foo(self): pass
  if some_condition:
    var = A()
  else
    var = B()
  var.foo()  # foo here refers to both A.foo and B.foo

logger	back to summary
private Logger logger

moduleTable	back to summary
public Scope moduleTable A scope containing bindings for all modules currently loaded by the indexer.

nloc	back to summary
private int nloc

nparsing	back to summary
private int nparsing

nprob	back to summary
private int nprob

nunbound	back to summary
private int nunbound

nunknown	back to summary
private int nunknown

parseErrs	back to summary
public Map<String, List<Diagnostic>> parseErrs

path	back to summary
public List<String> path

problems	back to summary
public Map<String, List<Diagnostic>> problems Diagnostics.

projDir	back to summary
public String projDir

unresolvedModules	back to summary
private Map<String, Set<String>> unresolvedModules This set tracks module imports that could not be resolved.

Constructor Detail

Indexer	back to summary
public Indexer()

Method Detail

addFileErr	back to summary
pack-priv void addFileErr(String file, int beg, int end, String msg)

addPath	back to summary
public void addPath(String p) throws IOException Adds the specified absolute path to the module search path.

addPaths	back to summary
public void addPaths(List<String> p) throws IOException Adds the specified absolute paths to the module search path.

aggressiveAssertionsEnabled	back to summary
public boolean aggressiveAssertionsEnabled()

clearAstCache	back to summary
public void clearAstCache() Clears the AST cache (to free up memory). Subsequent calls to `getAstForFile` will either fetch the serialized AST from a disk cache or re-parse the file from scratch.

clearModuleTable	back to summary
public void clearModuleTable() Clears the module table, discarding all resolved ASTs (modules) and their scope information.

convertCallToNew	back to summary
private void convertCallToNew(Ref ref, List<NBinding> bindings)

countDefs	back to summary
private int countDefs(List<NBinding> bindings)

duplicateBindingFailure	back to summary
private void duplicateBindingFailure(NBinding newb, NBinding oldb)

enableAggressiveAssertions	back to summary
public void enableAggressiveAssertions(boolean enable) Configures whether the indexer should abort with an exception when it encounters an internal error or unexpected program state. Normally the indexer attempts to continue indexing, on the assumption that having an index with mostly good data is better than having no index at all. Enabling aggressive assertions is useful for debugging the indexer.

enableAggressiveAssertions

back to summary

public void enableAggressiveAssertions(boolean enable)

Configures whether the indexer should abort with an exception when it encounters an internal error or unexpected program state. Normally the indexer attempts to continue indexing, on the assumption that having an index with mostly good data is better than having no index at all. Enabling aggressive assertions is useful for debugging the indexer.

fine	back to summary
public void fine(String msg)

finer	back to summary
public void finer(String msg)

generateOutline	back to summary
public List<Outliner.Entry> generateOutline(String path) throws Exception Create an outline for a file in the index. Parameters path:String the file for which to build the outline Returns:List<Outliner.Entry> a list of entries constituting the file outline. Returns an empty list if the indexer hasn't indexed that path.

generateOutline

back to summary

public List<Outliner.Entry> generateOutline(String path) throws Exception

Create an outline for a file in the index.

Parameters

path:String: the file for which to build the outline

Returns:List<Outliner.Entry>

a list of entries constituting the file outline. Returns an empty list if the indexer hasn't indexed that path.

getAstCache	back to summary
private AstCache getAstCache() throws Exception

getAstForFile back to summary

getAstForFile	back to summary
public NModule getAstForFile(String file) throws Exception Returns the syntax tree for `file`.

public NModule getAstForFile(String file) throws Exception

Returns the syntax tree for file.

getAstForFile back to summary

getAstForFile	back to summary
public NModule getAstForFile(String file, String contents) throws Exception Returns the syntax tree for `file`.

public NModule getAstForFile(String file, String contents) throws Exception

Returns the syntax tree for file.

getBindings	back to summary
public Map<String, NBinding> getBindings() Returns the mutable set of all bindings collected, keyed on their qnames.

getBuiltinModule	back to summary
public NModuleType getBuiltinModule(String qname) throws Exception

getCachedModule	back to summary
pack-priv NModuleType getCachedModule(String file)

getDiagnosticsForFile	back to summary
public List<Diagnostic> getDiagnosticsForFile(String file) Returns the list, possibly empty but never `null`, of errors and warnings generated in the file.

getFileErrs	back to summary
pack-priv List<Diagnostic> getFileErrs(String file, Map<String, List<Diagnostic>> map)

getLoadedFiles	back to summary
public List<String> getLoadedFiles()

getLoadPath	back to summary
public List<String> getLoadPath() Returns the module search path -- the project directory followed by any paths that were added by `addPath(String)`.

getLogger	back to summary
public Logger getLogger()

getModuleForFile

back to summary

public NModuleType getModuleForFile(String file) throws Exception

Returns (loading/resolving if necessary) the module for a given source path.

Parameters

file:String: absolute file path

getParseErrs	back to summary
pack-priv List<Diagnostic> getParseErrs(String file)

getStatusReport	back to summary
public String getStatusReport() Report resolution rate and other statistics data.

handleException back to summary

public void handleException(String msg, Throwable cause)

If aggressive assertions are enabled, propagates the passed Throwable, wrapped in an IndexingException.

Parameters

msg:String: descriptive message; ok to be null

info	back to summary
public void info(String msg)

isInLoadPath	back to summary
private boolean isInLoadPath(File dir)

isLibFile	back to summary
public boolean isLibFile(String file)

loadFile back to summary

public NModuleType loadFile(String path) throws Exception

Loads a file and all its ancestor packages.

See Also: loadFile(String, boolean)

loadFile back to summary

public NModuleType loadFile(String path, boolean skipChain) throws Exception

Load, parse and analyze a source file given its absolute path. By default, loads the entire ancestor package chain.

Parameters

path:String: the absolute path to the file or directory. If it is a directory, it is suffixed with "__init__.py", and only that file is loaded from the directory.
skipChain:boolean: true to skip loading ancestor packages

Returns:NModuleType

null if path could not be loaded

loadFileRecursive	back to summary
public void loadFileRecursive(String fullname) throws Exception Load all Python source files recursively if the given fullname is a directory; otherwise just load a file. Looks at file extension to determine whether to load a given file.

loadModule back to summary

public NModuleType loadModule(String modname) throws Exception

This method searches the module path for the module modname. If found, it is passed to loadFile.

The mechanisms for importing modules are in general statically undecidable. We make a reasonable effort to follow the most common lookup rules.

Parameters

modname:String: a module name. Can be a relative path to a directory or a file (without the extension) or a possibly-qualified module name. If it is a module name, cannot contain leading dots.

See Also

The Import Statement

loadParentPackage	back to summary
private void loadParentPackage(String file) throws Exception When we load a module, load all its parent packages, top-down. This is in part because Python does it anyway, and in part so that you can click on all parent package components in import statements. We load whole ancestor chain top-down, as does Python.

loadString

back to summary

public NModuleType loadString(String path, String contents) throws Exception

Loads a module from a string containing the module contents. Idempotent: looks in the module cache first. Used for simple unit tests.

Parameters

path:String: a path for reporting/caching purposes. The filename component is used to construct the module qualified name.

log	back to summary
public void log(Level level, String msg)

lookupQname	back to summary
public NBinding lookupQname(String qname) Return the binding for `qname`, or `null` if not known.

lookupQnameType back to summary

public NType lookupQnameType(String qname)

Return the type for qname, or null if not known.

Exceptions

IllegalStateException:: if ready has not been called.

numFilesLoaded	back to summary
public int numFilesLoaded()

parseAndResolve	back to summary
private NModuleType parseAndResolve(String file) throws Exception

parseAndResolve back to summary

private NModuleType parseAndResolve(String file, String contents) throws Exception

Parse a file or string and return its module parse tree.

Parameters

file:String: the filename
contents:String: optional file contents. If null, loads the file contents from disk.

Annotations

@SuppressWarnings:unchecked

percent	back to summary
private String percent(int num, int total)

printBindings	back to summary
private String printBindings()

putBinding	back to summary
public NBinding putBinding(NBinding b)

putLocation back to summary

public void putLocation(NNode node, NBinding b)

Add a reference to binding b at AST node node.

Parameters

node:NNode: a node referring to a name binding. Typically a NName, NStr or NUrl.

putLocation	back to summary
public void putLocation(Ref ref, NBinding b)

putProblem	back to summary
public void putProblem(NNode loc, String msg)

putProblem	back to summary
public void putProblem(String file, int beg, int end, String msg)

ready	back to summary
public void ready() Performs final indexing-building passes, including marking references to undeclared variables. Caller should invoke this method after loading all files.

recordUnresolvedModule

back to summary

public void recordUnresolvedModule(String qname, String file)

Reports a failed module or submodule resolution.

Parameters

qname:String: module qname, e.g. "org.foo.bar"
file:String: the file where the unresolved import occurred

release	back to summary
public void release() Releases all resources for the current indexer.

removeBinding	back to summary
public void removeBinding(NBinding b)

reportFailedAssertion back to summary

public void reportFailedAssertion(String msg)

Signals a failed assertion about the state of the indexer or index. If aggressive assertions are enabled, throws an IndexingException. Otherwise the message is logged as a warning, and indexing continues.

Parameters

msg:String: a descriptive message about the problem

See Also

enableAggressiveAssertions(boolean)

setLogger	back to summary
public void setLogger(Logger logger)

setPath	back to summary
public void setPath(List<String> path) throws IOException Sets the module search path to the specified list of absolute paths.

setProjectDir	back to summary
public void setProjectDir(String cd) throws IOException

severe	back to summary
public void severe(String msg)

toString back to summary

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations

@Override

updateLocation	back to summary
public void updateLocation(Ref node, NBinding b) Add `node` as a reference to binding `b`, removing `node` from any other binding ref-lists that it may have occupied. Currently only used in retargeting attribute references from provisional bindings once the actual binding is determined.

warn	back to summary
public void warn(String msg)

public Class Indexer

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail