astuce

package documentation

(source)

ast.AST inference utilities.

What is this?

This is a derived work from astroid.

The aim of this module is to provide an enhanced version of the AST nodes that keeps 100% compatibility with the standard AST nodes.

The node classes have additional methods and attributes for different usages. Methods and attributes are added by patching ast classes.

They include some support for some simple static inference and local name scopes.

It works well with literals.

Why?

I needed a inference library that supports the standard AST nodes such that, it can be used in pydoctor.

This library can help:

Infer what's the value of complex __all__ variables and other literal constants across different modules.
Trace back where a name was assigned, filtering ignorable statements.
Navigating in the tree with handy functions.

Limitations

Astuce is smart, but not very.

It is intra-procedural: Does not try to infer what value a ast.Call might return in a generic manner. Type hints will be considered as a source of information to get the return type of a call, this is not a type checker.
It is not path sensitive: Does not support constraints from ast.If blocks or assertions.
It can't create AST by inspecting living objects.

Example usage

from astuce import parser, inference

p = parser.Parser()

mod1 = p.parse('''
from mod2 import __all__ as _l
__all__ = ['f', 'k']
__all__.extend(_l)
''', modname='mod1')

mod2 = p.parse('''
__all__ = ('i', 'j')
''', modname='mod2')

inferred = list(inference.infer_attr(mod2, '__all__'))
assert len(inferred) == 1
assert ast.literal_eval(inferred[0]) == ['f', 'k', 'i', 'j']

Module	`exceptions`	No module docstring; 8/10 classes documented
Module	`inference`	Core of the inference engine.
Module	`nodes`	No module docstring; 0/2 constant, 17/17 functions, 4/5 classes documented
Module	`parser`	This module provides a replacement for `ast.parse` function.
Module	`_assigned_statements`	This module contains the code adjusted from astroid to infer/unpack assigned names from statements.
Module	`_astunparse`	A fallback `ast.unparse` function that works with a minimal subset of nodes.
Module	`_context`	Like astroid's inference context utilities, but more simple.
Module	`_decorators`	Decorator module, see https://github.com/micheles/decorator/blob/master/docs/documentation.md for the documentation.
Module	`_filter_statements`	No module docstring; 0/5 constant, 9/9 functions documented
Module	`_inference_decorators`	No module docstring; 3/3 functions documented
Module	`_lookup`	Code driving the ASTNode.lookup() method.
Module	`_monkey`	No module docstring; 0/3 variable, 1/1 class documented
Module	`_typing`	These classes are for type annotations only, do not instanciate them.

From __init__.py:

Function	`setup_logger`	Utility to (re)setup astuce's stream logger.
Variable	`_patcher`	Undocumented

def setup_logger(*, name='astuce', verbose=False, quiet=False, stream=sys.stdout, format_string='%(message)s'): (source)

Utility to (re)setup astuce's stream logger.

Parameters
name:`str`	Undocumented
verbose:`bool`	Undocumented
quiet:`bool`	Undocumented
stream:`TextIO`	Undocumented
format_string:`str`	Undocumented
Returns
`logging.Logger`	Undocumented

_patcher = (source)

Undocumented