pig.slicing

This module contains components related to the slicing functionality within the PIG system. It includes functionalities for slicing code into manageable pieces, which can then be processed for API migration tasks.

slicing

class pig.slicing.slicing.ContextRemover(nodes, targets={}, blank=False)

Remove irrelevant context nodes from the AST.

Walks the AST and retains only nodes that are present in self.nodes, pruning branches whose bodies become empty after transformation.

Parameters:

nodes (set) – The set of AST nodes to retain.
targets (set) – Optional set of target nodes.
blank (bool) – Whether to blank out removed nodes.

pig.slicing.slicing.FCTuple(root)

Return the __init__ method of a class if it exists, otherwise the class itself.

Parameters:: root (ast.ClassDef) – The class definition node to inspect.
Returns:: The __init__ ast.FunctionDef node if present, otherwise root itself.
Return type:: ast.FunctionDef | ast.ClassDef

pig.slicing.slicing.body_index(parent, node)

Find the index of node within the body of parent.

Searches through the possible body sections of parent in order: body, orelse, exception handlers (for ast.Try), and finalbody. Returns the first match found.

Parameters:

parent (ast.AST) – The parent AST node whose body sections are searched.
node (ast.AST) – The child AST node to locate.

Returns:

The index of node as a plain int if found in body or orelse; a (int, 'handler', ExceptHandler) tuple if found inside an exception handler’s body; or None if not found in any section.

Return type:

int | tuple[int, str, ast.ExceptHandler] | None

pig.slicing.slicing.bodyindex1(p1, v1, check='default')

Locate node within a body section of p1 and return context.

Searches body, orelse, finalbody, and exception handler bodies (for ast.Try) in order. The check parameter controls what is returned once the node is found.

Parameters:

p1 (ast.AST) – The parent AST node to search within.
node (ast.AST) – The child AST node to locate.
check (str) –
Controls the return value:
- 'default': return the integer index of node.
- 'aft': return the slice of the body after node (or the full body if node is last).
- 'bef': return the sibling immediately before node, or None if node is first.
- any other value: return the sibling immediately after node, or None if node is last.

Returns:

An index, a list of nodes, a single sibling node, or None depending on check and the position of node.

Return type:

int | list[ast.AST] | ast.AST | None

pig.slicing.slicing.delete_docstrings(root)

Remove all docstrings from the AST.

Walks the entire AST and strips the first expression statement from function and class definitions if it is a string literal (i.e. a docstring).

Parameters:: root (ast.Module) – The root AST module node to process.
Returns:: The modified AST module with all docstrings removed.
Return type:: ast.Module

pig.slicing.slicing.extract_name(node)

Get the name of the node.

Parameters:: node (Union[ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Module]) – The AST node to extract the name from.
Returns:: The name of the node, or 'module' if the node is an ast.Module or None, or None if the node type is unrecognized.
Return type:: Optional[str]

pig.slicing.slicing.fill_pass(root)

Fill empty bodies with ast.Pass() to avoid syntax errors.

Walks the entire AST and appends a ast.Pass node to any empty body block found in functions, classes, control flow statements, exception handlers, and modules.

Affected node types:

ast.FunctionDef, ast.AsyncFunctionDef
ast.ClassDef
ast.With, ast.AsyncWith
ast.If, ast.For
ast.Try, ast.ExceptHandler
ast.Module

Parameters:: root (ast.AST) – The root AST node to process.
Returns:: The modified AST with all empty bodies filled with ast.Pass().
Return type:: ast.AST

pig.slicing.slicing.find_need_node(root, names, nodes, index, classdefs, funcdefs, libo, target0)

Find necessary nodes that define or modify the given names before the given index.

Walks the AST to collect assignment, annotated assignment, and global statement nodes that define any of the requested names. Only nodes that appear before index in body order are considered, unless the node is already in nodes or target0 is a function/class definition. Class and function definitions matching names are appended last.

Parameters:

root (ast.Module) – The AST module to search within.
names (set) – The set of names whose defining nodes are being sought.
nodes (set) – The accumulator set of already-collected nodes.
index (int | tuple[int, str, ast.ExceptHandler] | None) – The body index before which to search. Either a plain int, a (int, str, ExceptHandler) tuple for nodes inside a try block, or None to match all positions.
classdefs (dict) – A mapping from class name to its ast.ClassDef node.
funcdefs (dict) – A mapping from function name to its ast.FunctionDef / ast.AsyncFunctionDef node.
libo (str) – The library name passed to call.NameExtractor to filter relevant name references.
target0 – The node that triggered this search; excluded from results and used to determine index comparison behaviour.

Returns:

A tuple of (nodes, remaining_names) where nodes is the updated set of collected nodes and remaining_names is the subset of names that could not be resolved.

Return type:

tuple[set, set]

pig.slicing.slicing.find_use_node(root, targets, index, libo)

Find the first node that uses any of the target names after the given index.

Walks the AST and returns the first statement node (at or below root) that references one of the targets names and appears after index in the body order. Compound statements are inspected at their key sub-expression (e.g. test for if/while, iter for for).

Parameters:

root (ast.Module) – The AST module to search within.
targets (set) – The set of names to look for.
index (Union[int, tuple[int, str, ast.ExceptHandler]]) – The body index after which to start matching. Either a plain int for top-level statements, or a (int, str, ExceptHandler) tuple for nodes inside a try block.
libo (str) – The library name passed to call.NameExtractor to filter relevant name references.

Returns:

A tuple of (matched_node, remaining_targets) where matched_node is the first node that uses a target name, or None if no match is found.

Return type:

tuple[ast.AST | None, set]

pig.slicing.slicing.index_info(ParentO, OCN)

Collect the body index of each ancestor node up to the module root.

Walks up the AST from OCN to the root ast.Module by repeatedly calling call.FindSSParent(), recording the index of each child within its parent’s body along the way.

Parameters:

ParentO – The parent object used to resolve ancestor relationships.
OCN – The starting AST node (Original Current Node) to walk up from.

Returns:

A mapping from each ancestor node to the index of its child in that node’s body, from OCN up to the root module.

Return type:

dict[ast.AST, int]

pig.slicing.slicing.need_nodes(nodes, codeo, CENs, Imps, indexes, ParentO, funcdefs, classdefs, libo)

Transitively collect all AST nodes required by the given seed nodes.

Starting from nodes, repeatedly extracts every name referenced by each node, resolves those names to their defining AST nodes via find_need_node(), and continues until no new nodes are discovered.

Parameters:

nodes (set) – The initial set of seed nodes whose dependencies are to be resolved.
codeo (ast.Module) – The top-level module node used as the fallback search root when traversal reaches the module scope.
CENs (set) – A set of built-in or context-defined names to exclude from dependency resolution.
Imps (set) – A set of imported names to exclude from dependency resolution.
indexes (dict) – A mapping from each ancestor node to the body index of its relevant child, as produced by index_info().
ParentO – The parent-resolver object used to locate ancestor nodes via call.FindSSParent() and call.FindFParent().
funcdefs (dict) – A mapping from function name to its defining node, used to resolve name references to functions.
classdefs (dict) – A mapping from class name to its defining node, used to resolve name references to classes.
libo (str) – The library name passed to call.NameExtractor to filter relevant name references.

Returns:

The fully expanded set of nodes required to execute the seed nodes.

Return type:

set

pig.slicing.slicing.slice(OCNs, codeo, apio, ParentO, libo, libn, funcdefs, classdefs, blank=False)

Slice the AST to retain only nodes relevant to the given API call sites.

Performs a five-step program slice on codeo:

Mark targets – identify the AST nodes where the old API (apio) is used, handling special cases such as class bases, decorators, and exception handlers.
Mark use cases – for Assign nodes, trace forward to find subsequent statements that consume the assigned names.
Mark dependencies – transitively collect all nodes required to execute the targets via need_nodes().
Remove context – strip all nodes not in the final set using ContextRemover.
Cleanup – insert pass into empty bodies with fill_pass() and remove unused imports with autoflake.

Parameters:

OCNs (dict) – A mapping from API name to the list of AST nodes (Old Call Nodes) where that API is referenced.
codeo (ast.AST) – The original AST module to slice.
apio (str) – The name of the old API whose usage sites are the slice criteria.
ParentO (dict) – The parent-resolver object used to locate ancestor nodes.
libo (str) – The name of the original library, used to filter name references during dependency resolution.
libn (str) – The name of the new library, excluded from dependency resolution alongside libo.
funcdefs – A mapping from function name to its defining AST node.
classdefs – A mapping from class name to its defining AST node.
blank (bool) – If True, passes the blank flag through to ContextRemover. Defaults to False.

Returns:

A new ast.Module containing only the sliced code, parsed from the autoflake-cleaned unparsed output.

Return type:

ast.Module