<type>documentation</type>
<domain>scripting</domain>
<id>analysis</id>
<title>API Reference - Analysis</title>
<product>per+</product>


The static analysis API is used to inspect the structure and contents
of Python files.  It consists of two parts:

**(1)** ``CAPISymbolInfo`` is used to describe a particular source symbol.

**(2)** ``CAPIStaticAnalysis`` is used to inspect a particular Python
file.


Class CAPISymbolInfo
====================

API to describe the inferred type for a particular source symbol. This class should
not be instantiated directly. Instances of this class are returned from
``CAPIStaticAnalysis.GetSymbolInfo``.

Type information is accessed with the following instance attributes:

``generalType``: General type of the symbol:  One of ``'class'``, ``'method'``, 
``'function'``, ``'instance'``, ``'keyword'``, ``'literal'``, or ``'module'``.
  
``typeName``: The full name of the type.

``fileName``: The file where the type is defined.

``lineStart``: The first line of the type definition (0=first line in file).

``lineCount``: The number of lines taken up by the type definition.

``pos``: The position of the type definition within the first line.

``isCallable``: ``True`` when the symbol is a callable.

``args``: A list of argument names, if ``isCallable`` is ``True``.

``docString``: The docstring for the type.


Class CAPIStaticAnalysis
========================

API for inspecting the contents of a Python file, based on Wing's static analysis of
that file. This class should not be instantiated directly. Use ``CAPIApplication.GetAnalysis``
instead.

**CAPIStaticAnalysis.GetScopeContents(scope, timeout=0.5)**

Get a list of all the symbols defined in the given scope.  

``scope`` is the name of the scope to inspect. For example, ``MyClass.MyMethod`` is
the method ``MyMethod`` in class ``MyClass`` and ``MyClass.MyMethod.nested`` is a
nested function ``nested`` within that method.

Use ``''`` for the top level of the module.

To obtain attributes for an instance, append ':' to the class name. For example,
'MyClass:' provides the attributes for an instance of ``MyClass``.

Set ``timeout`` to specify the maximum computation time in seconds.

Returns a dictionary mapping symbol names to a sequence of one or more strings
describing the symbol. The descriptors may be::

  imported -- The symbol is imported from another module
  class -- The symbol is a class or class attrib when 'attrib' is also present
  method -- The symbol is a method
  function -- The symbol is a function
  argument -- The symbol is a function or method argument
  module -- The symbol is a module
  package -- The symbol is a package
  attrib -- The symbol is an instance attribute
  
Use ``GetSymbolInfo`` to obtain additional information about a symbol, including its
inferred type and point of definition.

**CAPIStaticAnalysis.FindScopeContainingLine(lineno)**

Find the scope containing the given line number. Note that a class line or a def
line is in its parent's scope.

**CAPIStaticAnalysis.GetSymbolInfo(scope, symbol)**

Get extended information for the given symbol within the named scope.
A scope of ``''`` and symbol of ``''`` obtains type information for the module
as a whole. Returns a sequence of ``CAPISymbolInfo`` instances.

**CAPIStaticAnalysis.GetLogicalLineBounds(lineno)**

Find the first and last lines that contain the logical line spanning the
given line number. This takes into account Python syntax that allows a single logical
line to contain multiple physical lines.  All line numbers are 0=first.

