padl.dumptools.symfinder

Module for symbolically finding python entities in python source code given their name.

A thing in python can get its name in various ways:

  • it’s defined as a function

  • it’s defined as a class

  • it’s assigned

  • it is imported

  • it’s created in a with statement

  • it’s created in a for loop

This module defines subclasses of the _ThingFinder class, which allow to identify these cases in an AST tree of a source code.

Finding names in code then corresponds to building the AST tree of the code and using the _ThingFinder subclasses to identify if and how the names were created.

The main function to use is find, which will find a name in a module or the current ipython history.

exception padl.dumptools.symfinder.NameNotFound

Exception indicating that a name could not be found.

class padl.dumptools.symfinder.Scope(module: module, def_source: str, scopelist: List[Tuple[str, _ast.AST]])

A scope.

Scope objects can be used to find names that are not defined globally in a module, but nested, for example within a function body.

It contains the module, the source string and a “scopelist”.

classmethod empty()

Create the empty scope (a scope with no module and no nesting).

from_level(i: int) → padl.dumptools.symfinder.Scope

Return a new scope starting at level i of the scope hierarchy.

classmethod from_source(def_source, lineno, call_source, module=None, drop_n=0, calling_scope=None)

Create a Scope object from source code.

Parameters

  • def_source – The source string containing the scope.

  • lineno – The line number to get the scope from.

  • call_source – The source of the call used for accessing the scope.

  • module – The module.

  • drop_n – Number of levels to drop from the scope.

global_() → padl.dumptools.symfinder.Scope

Return the global scope surrounding self.

is_global() → bool

True iff the scope is global.

property module_name: str

The name of the scope’s module.

classmethod toplevel(module)

Create a top-level scope (i.e. module level, no nesting).

unscoped(varname: str) → str

Convert a variable name in an “unscoped” version by adding strings representing the containing scope.

up() → padl.dumptools.symfinder.Scope

Return a new scope one level up in the scope hierarchy.

class padl.dumptools.symfinder.ScopedName(name: str, scope: padl.dumptools.symfinder.Scope, n: int = 0)

A name with a scope and a counter. The “name” is the name of the item, the scope is its Scope and the counter counts the items with the same name, in the same scope, from most recent on up.

Example - the following:

a = 1

def f(x):
    a = 2

a = a + 1

contains four scoped names:

  • The “a” of a = a + 1, with name = a, module-level scope and n = 0 (it is the most recent “a” in the module level scope).

  • The “a” in the function body, with name = a, function f scope and n = 0 (it is the most recent “a” in “f” scope).

  • the function name “f”, module level scope, n = 0

  • the “a” of a = 1, with name = a, module-level scope and n = 1 (as it’s the second most recent “a” in its scope).

padl.dumptools.symfinder.find(var_name: str, module=None, i: int = 0) → Tuple[str, _ast.AST]

Find the piece of code that assigned a value to the variable with name var_name in the module module.

If module is not specified, this uses __main__. In that case, the ipython history will be searched as well.

Parameters

  • var_name – Name of the variable to look for.

  • module – Module to search (defaults to __main__).

Returns

Tuple with source code segment and corresponding ast node.

padl.dumptools.symfinder.find_in_ipython(var_name: str, i: int = 0) → Tuple[str, _ast.AST]

Find the piece of code that assigned a value to the variable with name var_name in the ipython history.

Parameters

var_name – Name of the variable to look for.

Returns

Tuple with source code segment and the corresponding ast node.

padl.dumptools.symfinder.find_in_module(var_name: str, module, i: int = 0) → Tuple[str, _ast.AST]

Find the piece of code that assigned a value to the variable with name var_name in the module module.

Parameters

  • var_name – Name of the variable to look for.

  • module – Module to search.

Returns

Tuple with source code segment and corresponding ast node.

padl.dumptools.symfinder.find_in_scope(name: padl.dumptools.symfinder.ScopedName)

Find the piece of code that assigned a value to the variable with name var_name in the scope scope.

Parameters

scope – Name (with scope) of the variable to look for.

padl.dumptools.symfinder.find_in_source(var_name: str, source: str, tree=None, i: int = 0, return_partial=False) → Tuple[str, _ast.AST]

Find the piece of code that assigned a value to the variable with name var_name in the source string source.

Parameters

  • var_name – Name of the variable to look for.

  • source – Source code to search.

Returns

Tuple with source code segment and corresponding AST node.

padl.dumptools.symfinder.replace_star_imports(tree: _ast.Module)

Replace star imports in the tree with their written out forms.

So that:

from padl import *

would become:

from padl import value, transform, Batchify, […]

padl.dumptools.symfinder.split_call(call_source)

Split the function of a call from its arguments.

Example:

>>> split_call('f(1, 2, 3)')
('f', '1, 2, 3')