py2cfg

https://py2cfg.readthedocs.io/en/latest/
Admin
py2cfg is a Python3 package that generates control flow graphs (CFGs) for Python programs, enabling...
Tokens:24,604
Snippets:141
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Clone Repository and Generate Examples

Source: https://py2cfg.readthedocs.io/en/latest/index.html

Shell commands to clone the repository and generate example CFG images.

```shell
git clone repourl
cd intorepodirectory
./generate_examples.sh

```

--------------------------------

### Install py2cfg Locally

Source: https://py2cfg.readthedocs.io/en/latest/index.html

Commands to clone the repository and install py2cfg locally using pip.

```shell
git clone <url>
cd intoprojectdirectory
pip3 install . --user

```

--------------------------------

### GET /internal/ast_visitor

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Methods for visiting AST nodes to construct the CFG, including handling classes, assignments, and function calls.

```APIDOC
## GET /internal/ast_visitor

### Description
Visitor methods for processing AST nodes such as ClassDef, Expr, Call, Assign, AnnAssign, AugAssign, and Raise.

### Method
GET

### Parameters
#### Path Parameters
- **node** (ASTNode) - Required - The specific AST node to visit and process into the CFG.
```

--------------------------------

### Install py2cfg via pip

Source: https://py2cfg.readthedocs.io/en/latest/index.html

Command to install the py2cfg package using pip.

```shell
pip3 install py2cfg --user

```

--------------------------------

### Generate Fibonacci Sequence

Source: https://py2cfg.readthedocs.io/en/latest/index.html

Example Python code to generate the Fibonacci sequence.

```python
# fib.py

def fib():
    a, b = 0, 1
    while True:
        yield a
        a, b = b, a + b

fib_gen = fib()
for _ in range(10):
    next(fib_gen)

```

--------------------------------

### Build Key Graph

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

Builds and renders a key graph for the CFG.

```python
def build_key(self, **kwargs):
        """Build key graph"""
        key = self._build_key_subgraph(kwargs.get("format", "svg"))
        return key.render(**kwargs)
```

--------------------------------

### Build CFG from File

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Reads a Python source file and initiates the CFG construction process.

```python
    def build_from_file(self, name: str, filepath: str) -> CFG:
        """
        Build a CFG from some Python source file.

        Args:
            name: The name of the CFG being built.
            filepath: The path to the file containing the Python source code
                      to build the CFG from.

        Returns:
            The CFG produced from the source file.
        """
        with open(filepath, "r") as src_file:
            src = src_file.read()
            return self.build_from_src(name, src)
```

--------------------------------

### invert

Source: https://py2cfg.readthedocs.io/en/latest/builder_link.html

Inverts the operation in an AST node object to get its negation.

```APIDOC
## invert

### Description
Invert the operation in an ast node object (get its negation).

### Parameters
- **node** (Union[_ast.Compare, _ast.expr]) - Required - An ast node object.

### Response
- **Returns** (Union[ast.NameConstant, _ast.UnaryOp, _ast.Compare]) - An ast node object containing the inverse (negation) of the input node.
```

--------------------------------

### build Method

Source: https://py2cfg.readthedocs.io/en/latest/builder_link.html

Builds a control flow graph from an Abstract Syntax Tree (AST).

```APIDOC
## POST /build

### Description
Build a CFG from an AST.

### Method
POST

### Endpoint
`/build`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (str) - Required - The name of the CFG being built.
- **tree** (_ast.Module) - Required - The root of the AST from which the CFG must be built.
- **async** (bool) - Optional - Boolean indicating whether the CFG being built represents an asynchronous function or not. Defaults to False.
- **entry_id** (int) - Optional - Value for the id of the entry block of the CFG. Defaults to 0.

### Response
#### Success Response (200)
- **CFG** (py2cfg.model.CFG) - The CFG produced from the AST.
```

--------------------------------

### Build CFG from File

Source: https://py2cfg.readthedocs.io/en/latest/index.html

Python code to import CFGBuilder and build a CFG from a specified file.

```python
from py2cfg import CFGBuilder

cfg = CFGBuilder().build_from_file('example', './example.py')

```

--------------------------------

### Get Own Blocks in CFG

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

Generator that yields all blocks in the current graph, excluding any subgraphs. Uses a breadth-first search approach.

```python
def own_blocks(self) -> Iterator[Block]:
        """
        Generator that yields all blocks in the current graph, excluding any
        subgraphs
        """
        visited = set()
        if self.entryblock is None:
            raise TypeError("Expected self.entryblock to be not None but type is None")
        to_visit: Deque[Block] = deque([self.entryblock])
        while to_visit:
            block = to_visit.popleft()
            visited.add(block)
            for exit_ in block.exits:
                if exit_.target in visited or exit_.target in to_visit:
                    continue
                to_visit.append(exit_.target)
            yield block
```

--------------------------------

### CFGBuilder Build Method

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Builds a Control Flow Graph (CFG) from an Abstract Syntax Tree (AST). This method initializes the CFG, sets up the entry block, and traverses the AST to construct the graph.

```APIDOC
## CFGBuilder.build

### Description
Builds a CFG from an AST.

### Method
`build`

### Parameters
- **name** (str) - Required - The name of the CFG being built.
- **tree** (ast.Module) - Required - The root of the AST from which the CFG must be built.
- **asynchr** (bool) - Optional - Boolean indicating whether the CFG being built represents an asynchronous function or not. Defaults to False.
- **entry_id** (int) - Optional - Value for the id of the entry block of the CFG. Defaults to 0.

### Returns
- **CFG** - The CFG produced from the AST.

### Request Example
```python
# Assuming cfg_builder is an instance of CFGBuilder and ast_tree is an ast.Module object
cfg = cfg_builder.build(name='my_function', tree=ast_tree)
```

### Response Example
```json
{
  "cfg": "CFG object representing the control flow"
}
```
```

--------------------------------

### Utility Function: invert

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Inverts the operation in an AST node object, effectively getting its negation. This is useful for manipulating conditional expressions.

```APIDOC
## invert

### Description
Invert the operation in an ast node object (get its negation).

### Parameters
- **node** (Union[Compare, ast.expr]) - Required - An ast node object.

### Returns
- **Union[ast.NameConstant, ast.UnaryOp, Compare]** - An ast node object containing the inverse (negation) of the input node.

### Request Example
```python
# Assuming 'compare_node' is an AST node representing a comparison
inverted_node = invert(compare_node)
```

### Response Example
```json
{
  "inverted_node": "AST node representing the negated operation"
}
```
```

--------------------------------

### Build Visual Graph Representation

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

Initializes and builds the visual graph representation, including subgraphs for class configurations. Raises an error if the entry block is not defined.

```Python
    subgraphs: dict = Counter()

    def _build_visual(self, format: str = "pdf", calls: bool = True, interactive: bool = False, build_own=False) -> Digraph:
        graph = gv.Digraph(
            name=f"cluster{self.subgraphs[self.name]}{self.name}",
            format=format,
            graph_attr={
                "label": self.name,
                "rankdir": "TB",
                "ranksep": "0.02",
                "compound": "True",
                "pack": "False",
            },
        )
        self.subgraphs[self.name] += 1
        if self.entryblock is None:
            raise TypeError("Expected self.entryblock to be not None but type is None")
        self._visit_blocks(
            graph,
            self.entryblock,
            visited=set(),
            calls=calls,
            format=format,
            interactive=interactive,
        )
        if build_own:
            return graph
        # Build the subgraphs for the function definitions in the CFG and add
        # them to the graph.
        for subcfg in self.classcfgs:
            subgraph = self.classcfgs[subcfg]._build_visual(
                format=format,
                calls=calls,
                interactive=interactive,
            )
            graph.subgraph(subgraph)
```

--------------------------------

### Build Visualisation of CFG

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

Builds a visualisation of the CFG and outputs it to a DOT file. Handles cleanup and viewing options.

```python
def build_visual(self,
        filepath: str,
        format: str,
        calls: bool = True,
        show: bool = True,
        cleanup=True,
        directory=None,
        interactive=False,
        build_keys=True,
        build_own=False,
    ) -> str:
        """
        Build a visualisation of the CFG with graphviz and output it in a DOT
        file.

        Args:
            filename: The name of the output file in which the visualisation
                      must be saved.
            format: The format to use for the output file (PDF, ...).
            show: A boolean indicating whether to automatically open the output
                  file after building the visualisation.
        """
        if cleanup is None: # Not sure why I did this.
            cleanup = bool(os.environ["PY2CFG_CLEANUP"])
        
        graph = self._build_visual(format, calls, interactive, build_own)
        if build_keys:
            graph.subgraph(self._build_key_subgraph(format))
        return graph.render(filepath, view=show, cleanup=cleanup, directory=directory)
```

--------------------------------

### Build CFG from AST or Source

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Methods for constructing a CFG object from an existing AST module or raw Python source code string.

```python
    def build(
        self, name: str, tree: Module, asynchr: bool = False, entry_id: int = 0
    ) -> CFG:
        """
        Build a CFG from an AST.

        Args:
            name: The name of the CFG being built.
            tree: The root of the AST from which the CFG must be built.
            async: Boolean indicating whether the CFG being built represents an
                   asynchronous function or not. When the CFG of a Python
                   program is being built, it is considered like a synchronous
                   'main' function.
            entry_id: Value for the id of the entry block of the CFG.

        Returns:
            The CFG produced from the AST.
        """
        self.cfg = CFG(name, asynchr=asynchr, short=self.isShort)
        # Tracking of the current block while building the CFG.
        self.current_id = entry_id
        self.current_block = self.new_block()
        self.cfg.entryblock = self.current_block
        # Actual building of the CFG is done here.
        self.visit(tree)
        self.clean_cfg(self.cfg.entryblock)
        return self.cfg
```

```python
    def build_from_src(self, name: str, src: str) -> CFG:
        """
        Build a CFG from some Python source code.

        Args:
            name: The name of the CFG being built.
            src: A string containing the source code to build the CFG from.

        Returns:
            The CFG produced from the source code.
        """
```

--------------------------------

### CFG class initialization

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

The main container class for the control flow graph, including node styling configurations.

```python
class CFG(object):
    """
    Control flow graph (CFG).

    A control flow graph is composed of basic blocks and links between them
    representing control flow jumps. It has a unique entry block and several
    possible 'final' blocks (blocks with no exits representing the end of the
    CFG).
    """

    # Also serves as graph Key table
    # TODO Change value type to dict. Can be upacked into graph.node fn.
    node_styles = {
        "input": ("parallelogram", "#afeeee"),  # Pale Turquoise
        "default": ("rectangle", "#FFFB81"),  # Pale Yellow
        ast.If: ("diamond", "#FF6752"),  # Pale Red
        ast.For: ("hexagon", "#FFBE52"),  # Pale Orange
        ast.While: ("hexagon", "#FFBE52"),  # Pale Orange
        ast.Call: ("tab", "#E552FF"),  # Pale Purple
        ast.Return: ("parallelogram", "#98fb98"),  # Pale Green
        ast.Try: ("Mdiamond", "orange"),
        ast.Raise: ("house", "#98fb98"),
    }
    DEFAULT = node_styles["default"]

    def __init__(self, name: str, asynchr: bool = False, short: bool = True) -> None:
        assert isinstance(name, str), "Name of a CFG must be a string"
        assert isinstance(asynchr, bool), "Async must be a boolean value"
        # Name of the function or module being represented.
        self.name = name
        # Type of function represented by the CFG (sync or async). A Python
        # program is considered as a synchronous function (main).
        self.asynchr = asynchr
        # Entry block of the CFG.
        self.entryblock: Optional[Block] = None
        # Final blocks of the CFG.
        self.finalblocks: List[Block] = []
        # Sub-CFGs for functions defined inside the current CFG.
        self.functioncfgs: dict = {}
        # Sub-CFGs
        self.classcfgs: dict = {}
        self.isShort = short
        self.lineno: int = 0
        self.end_lineno: int = 0
```

--------------------------------

### build_from_file Method

Source: https://py2cfg.readthedocs.io/en/latest/builder_link.html

Builds a control flow graph from a Python source file.

```APIDOC
## POST /build_from_file

### Description
Build a CFG from some Python source file.

### Method
POST

### Endpoint
`/build_from_file`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (str) - Required - The name of the CFG being built.
- **filepath** (str) - Required - The path to the file containing the Python source code to build the CFG from.

### Response
#### Success Response (200)
- **CFG** (py2cfg.model.CFG) - The CFG produced from the source file.
```

--------------------------------

### Build Key Graph API

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

API for building and rendering a key graph.

```APIDOC
## POST /build_key

### Description
Builds and renders a key graph, which is a subgraph representing key elements. It accepts optional arguments for formatting and rendering.

### Method
POST

### Endpoint
/build_key

### Parameters
#### Query Parameters
- **format** (str) - Optional - The format to use for the key graph (e.g., 'svg'). Defaults to 'svg'.

### Request Example
```json
{
  "format": "svg"
}
```

### Response
#### Success Response (200)
- **str** (str) - The rendered key graph, typically in DOT format or as a file path depending on rendering options.

#### Response Example
```json
{
  "rendered_key": "digraph G { ... }"
}
```
```

--------------------------------

### Create New CFG Block

Source: https://py2cfg.readthedocs.io/en/latest/builder_link.html

Initializes a new block instance with a unique identifier.

```python
`new_block`(_statement =None_) → py2cfg.model.Block
```

--------------------------------

### Build Visualisation API

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

APIs for building and rendering control flow graph visualizations.

```APIDOC
## POST /build_visual

### Description
Builds a visualization of the Control Flow Graph (CFG) using Graphviz and outputs it to a DOT file. This method allows for customization of the output format, whether to automatically open the file, and cleanup options.

### Method
POST

### Endpoint
/build_visual

### Parameters
#### Query Parameters
- **filepath** (str) - Required - The name of the output file in which the visualisation must be saved.
- **format** (str) - Required - The format to use for the output file (e.g., PDF, SVG).
- **show** (bool) - Optional - A boolean indicating whether to automatically open the output file after building the visualisation. Defaults to True.
- **cleanup** (bool) - Optional - Specifies whether to clean up intermediate files after rendering. Defaults to True.
- **directory** (str) - Optional - The directory where the output file should be saved.
- **interactive** (bool) - Optional - Enables interactive mode for the visualization.
- **build_keys** (bool) - Optional - Whether to include keys in the visualization. Defaults to True.
- **build_own** (bool) - Optional - Whether to build the graph's own blocks.

### Request Example
```json
{
  "filepath": "cfg_output.pdf",
  "format": "pdf",
  "show": true,
  "cleanup": true,
  "directory": "./output",
  "interactive": false,
  "build_keys": true,
  "build_own": false
}
```

### Response
#### Success Response (200)
- **str** (str) - A string representing the path to the generated visualization file.

#### Response Example
```json
{
  "filepath": "./output/cfg_output.pdf"
}
```
```

--------------------------------

### Create New Blocks

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Methods for instantiating different types of control flow blocks with unique identifiers.

```python
    def new_block(self, statement=None) -> Block:
        """
        Create a new block with a new id.

        Returns:
            A Block object with a new unique id.
        """
        self.current_id += 1
        block = Block(self.current_id)
        if statement is not None:
            block.add_statement(statement)
        return block
```

```python
    def new_func_block(self) -> FuncBlock:
        """
        Create a new function block with a new id.

        Returns:
            A FuncBlock object with a new unique id.
        """
        self.current_id += 1
        return FuncBlock(self.current_id)
```

```python
    def new_try_block(self, statement=None):
        self.current_id += 1
        block = TryBlock(self.current_id)
        if statement is not None:
            block.add_statement(statement)
        return block
```

--------------------------------

### CFGBuilder API

Source: https://py2cfg.readthedocs.io/en/latest/genindex.html

Methods for constructing Control Flow Graphs from source code or files.

```APIDOC
## CFGBuilder Methods

### Description
The CFGBuilder class provides methods to initialize and build CFG structures from various inputs.

### Methods
- **build_from_file(path)**: Constructs a CFG from a specified Python file.
- **build_from_src(source)**: Constructs a CFG from a string of Python source code.
- **new_block()**: Creates a new block within the builder context.
- **new_functionCFG()**: Initializes a new function-level CFG.
- **add_statement()**: Adds a statement to the current CFG construction.
```

--------------------------------

### Visit Await Expression for CFG

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Manages the 'await' expression by creating a block for the code following the await and visiting the await node.

```python
def visit_Await(self, node):
        afterawait_block = self.new_block()
        self.add_exit(self.current_block, afterawait_block)
        self.generic_visit(node)
        self.current_block = afterawait_block
```

--------------------------------

### CFGBuilder Build From Source Method

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Builds a Control Flow Graph (CFG) directly from Python source code. This method first parses the source code into an AST and then proceeds to build the CFG.

```APIDOC
## CFGBuilder.build_from_src

### Description
Build a CFG from some Python source code.

### Method
`build_from_src`

### Parameters
- **name** (str) - Required - The name of the CFG being built.
- **src** (str) - Required - A string containing the source code to build the CFG from.

### Returns
- **CFG** - The CFG produced from the source code.

### Request Example
```python
# Assuming cfg_builder is an instance of CFGBuilder
source_code = "def greet(name):\n    print(f'Hello, {name}!')"
cfg = cfg_builder.build_from_src(name='greet_function', src=source_code)
```

### Response Example
```json
{
  "cfg": "CFG object representing the control flow"
}
```
```

--------------------------------

### New Block Creation

Source: https://py2cfg.readthedocs.io/en/latest/builder_link.html

Creates a new block within the CFG model.

```APIDOC
## Function: new_block

### Description
Creates a new block with a unique ID. This is a utility function for building CFGs.

### Method
`new_block(_statement = None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Block** (py2cfg.model.Block) - A newly created block object.

#### Response Example
```json
{
  "block_id": "new_block_123",
  "statements": []
}
```
```

--------------------------------

### Create Key Subgraph for AST Nodes

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

Generates a subgraph to represent the key for understanding node styles in the visualization. It defines nodes for different type objects with specific shapes and colors.

```python
def _create_key_subgraph(self) -> Digraph:
        key_subgraph = Digraph(name="cluster_KEY", format=format, graph_attr={"label": "KEY"})
        for typeobj, (shape, color) in zip(
            self.node_styles.keys(), self.node_styles.values()
        ):
            key_subsubgraph.node(
                name=(
                    typeobj.__name__.lower()
                    if isinstance(typeobj, type)
                    else str(typeobj)
                ),
                _attributes={"shape": shape, "style": "filled", "fillcolor": color},
            )

        # Adding edge helps with alignment.
        key_subgraph.edge("if", "input", _attributes={"style": "invis"})
        key_subgraph.edge("input", "call", _attributes={"style": "invis"})
        key_subgraph.edge("for", "return", _attributes={"style": "invis"})
        key_subgraph.edge("return", "default", _attributes={"style": "invis"})
        key_subgraph.edge("try", "raise", _attributes={"style": "invis"})
        return key_subgraph
```

--------------------------------

### Visit Return Statement for CFG

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Implements CFG generation for 'return' statements. It handles cases where the current block has statements and manages control flow within try blocks.

```python
def visit_Return(self, node: Return) -> None:
        if self.current_block.statements:
            return_block = self.new_block()
            self.current_block.add_exit(return_block)
            self.current_block = return_block

        self.add_statement(self.current_block, node)

        if self.try_stack:
            stackobj = self.try_stack[0]
            if stackobj.iter_state != TryEnum.FINAL and stackobj.has_final:
                after_return = self.new_block()
                self.current_block.add_exit(after_return)
                after_return.add_exit(self.current_block)
                self.current_block = after_return
                for child in stackobj.node.finalbody:
```

--------------------------------

### Visit Blocks in AST

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

Traverses and visualizes blocks within an AST. It handles visited blocks, styles nodes, and prepares labels, including logic for shortening long string literals based on a regex pattern.

```python
def _visit_blocks(
        self,
        graph: Digraph,
        block: Block,
        visited: Set[Block] = set(),
        calls: bool = True,
        format: str = None,
        interactive: bool = False
    ) -> None:
        # Don't visit blocks twice.
        if block in visited:
            return
        visited.add(block)
        nodeshape, nodecolor, nodelabel = self.stylize_node(block)
        node_type = block.type()
        original_nodelabel = nodelabel
        nodelabel = ""
        if (
            self.isShort
            and not isinstance(node_type, ast.ClassDef)
            and not isinstance(node_type, ast.FunctionDef)
            and not isinstance(node_type, ast.If)
            and not isinstance(node_type, ast.While)
        ):
            sub_pattern = r"""("|')                # Group 1: " or '
                              (?=[^"'\r\n]{20,})   # Enforce min length of 20
                              ([^"'\r\n]{,20})     # Group 2: Words that stay
                              ([^"'\r\n]{,9999})   # Group 3: Shorten these 
        """
```

--------------------------------

### build_from_src Method

Source: https://py2cfg.readthedocs.io/en/latest/builder_link.html

Builds a control flow graph from a string containing Python source code.

```APIDOC
## POST /build_from_src

### Description
Build a CFG from some Python source code.

### Method
POST

### Endpoint
`/build_from_src`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (str) - Required - The name of the CFG being built.
- **src** (str) - Required - A string containing the source code to build the CFG from.

### Response
#### Success Response (200)
- **CFG** (py2cfg.model.CFG) - The CFG produced from the source code.
```

--------------------------------

### Visit While Loop for CFG

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Constructs the CFG for a 'while' loop, including a loop guard, the loop body, and the block after the loop. It manages the loop stack for break and continue statements.

```python
def visit_While(self, node: While) -> None:
        # TODO while/else

        loop_guard = self.new_loopguard()
        self.current_block = loop_guard
        self.add_statement(self.current_block, node)

        if isinstance(node.test, ast.Call):
            self.visit(node.test)
        # New block for the case where the test in the while is True.
        while_block = self.new_block()
        self.add_exit(self.current_block, while_block, node.test)

        # New block for the case where the test in the while is False.
        afterwhile_block = self.new_block()
        self.add_exit(self.current_block, afterwhile_block, invert(node.test))

        # Populate the while block.
        self.current_block = while_block
        self.loop_stack.appendleft((afterwhile_block, loop_guard))
        for child in node.body:
            self.visit(child)
        top = self.loop_stack.popleft()
        assert top == (afterwhile_block, loop_guard)
        self.add_exit(self.current_block, loop_guard)

        # Continue building the CFG in the after-while block.
        self.current_block = afterwhile_block
```

--------------------------------

### Visit ImportFrom Statement for CFG

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Adds an 'import from' statement node to the current block in the CFG.

```python
def visit_ImportFrom(self, node: ImportFrom) -> None:
        self.add_statement(self.current_block, node)
```

--------------------------------

### CFG Model API

Source: https://py2cfg.readthedocs.io/en/latest/genindex.html

Methods for interacting with and querying existing Control Flow Graph objects.

```APIDOC
## CFG Model Methods

### Description
The CFG class represents the graph structure and provides methods for analysis and visualization.

### Methods
- **bsearch()**: Performs a search within the CFG structure.
- **build_visual()**: Generates a visual representation of the CFG.
- **highlight_blocks()**: Highlights specific blocks within the graph.
- **outline_block()**: Returns an outline of the blocks contained in the CFG.
```

--------------------------------

### Link class methods

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

Methods for retrieving source and target line numbers and the source code of the exit condition.

```python
    def jumpfrom(self) -> Optional[int]:
        """Return the line of source end"""
        return self.source.end()

    def jumpto(self) -> Optional[int]:
        """Return the line of target start"""
        return self.target.at()

    def get_exitcase(self) -> str:
        """
        Get a string containing the Python source code corresponding to the
        exitcase of the Link.

        Returns:
            A string containing the source code.
        """
        if self.exitcase:
            return astor.to_source(self.exitcase)
        return ""
```

--------------------------------

### Manage Statements and Exits

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Utility methods for appending statements to blocks and defining control flow transitions between blocks.

```python
    def add_statement(self, block: Block, statement: Union[stmt, Call]) -> None:
        """
        Add a statement to a block.

        Args:
            block: A Block object to which a statement must be added.
            statement: An AST node representing the statement that must be
                       added to the current block.
        """
        block.statements.append(statement)
```

```python
    def add_exit(
        self,
        block: Block,
        nextblock: Block,
        exitcase: Union[Compare, None, ast.BoolOp, ast.expr] = None,
    ) -> None:
        """
        Add a new exit to a block.

        Args:
            block: A block to which an exit must be added.
            nextblock: The block to which control jumps from the new exit.
            exitcase: An AST node representing the 'case' (or condition)
                      leading to the exit from the block in the program.
        """
        newlink = Link(block, nextblock, exitcase)
        block.exits.append(newlink)
        nextblock.predecessors.append(newlink)
```

--------------------------------

### Visualize Function Calls

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

Creates a subgraph for function calls, processing and displaying call statements. Generates control flow edges for function arguments.

```Python
        if calls and block.func_calls:
            calls_node = str(block.id) + "_calls"

            # Remove any duplicates by splitting on newlines and creating a set
            calls_label = block.get_calls().strip()

            # Create a new subgraph for call statement
            calls_subgraph = gv.Digraph(
                name=f"cluster_{block.id}",
                format=format,
                graph_attr={
                    "rankdir": "TB",
                    "ranksep": "0.02",
                    "style": "filled",
                    "color": self.fillcolor(block, interactive, "purple"),
                    "compound": "true",
                    "shape": self.node_styles[ast.Call][0],
                    "label": "",
                },
            )
            # Generate control flow edges for function arguments
            for func_block in block.func_blocks:
                graph.edge(
                    str(block.id),
                    str(func_block.id),
                    label="calls",
                    _attributes={"style": "dashed"},
                )
                self._visit_func(
                    calls_subgraph,
                    func_block,
                    visited=set(),
                    interactive=interactive,
                )
            graph.subgraph(calls_subgraph)
```

--------------------------------

### Visit Class Definition in AST

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Handles the visit of a ClassDef node in the AST. Adds the statement to the current block and creates a new CFG for the class.

```python
    def visit_ClassDef(self, node: ClassDef) -> None:
        self.add_statement(self.current_block, node)
        self.new_classCFG(node, asynchr=False)
```

--------------------------------

### Generate Control Flow Edges

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

Recursively visits blocks and adds edges to the graph, applying specified styles and labels based on the exit conditions.

```Python
        # Recursively visit all the blocks of the CFG.
        for exit in block.exits:
            assert block == exit.source
            self._visit_blocks(
                graph,
                exit.target,
                visited,
                calls=calls,
                format=format,
                interactive=interactive,
            )
            edgeshape, edgecolor, edgelabel = self.stylize_edge(exit)
            graph.edge(
                str(block.id),
                str(exit.target.id),
                label=edgelabel,
                _attributes={"color": edgecolor},
            )
```

--------------------------------

### Visit Function Definition for CFG

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Handles function definitions by adding the function definition node and creating a new CFG for the function.

```python
def visit_FunctionDef(self, node: FunctionDef) -> None:
        self.add_statement(self.current_block, node)
        self.new_functionCFG(node, asynchr=False)
```

--------------------------------

### new_block

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Creates a new block with a unique identifier.

```APIDOC
## new_block

### Description
Creates a new block with a new unique id. Optionally adds a statement to the block.

### Parameters
#### Request Body
- **statement** (any) - Optional - An AST node representing a statement to add to the block.

### Response
- **Block** (object) - A Block object with a new unique id.
```

--------------------------------

### Visualize CFG

Source: https://py2cfg.readthedocs.io/en/latest/index.html

Python code to visualize a built CFG object into a specified format (e.g., PDF).

```python
cfg.build_visual('exampleCFG', 'pdf')

```

--------------------------------

### Strict Type Hinting Check

Source: https://py2cfg.readthedocs.io/en/latest/index.html

Command to enforce strict type-hinting standards using mypy.

```shell
mypy --strict --disallow-any-explicit *.py

```

--------------------------------

### Link Class

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

Represents a control flow jump between two blocks in the CFG.

```APIDOC
## Link Class

### Description
Represents a connection between a source block and a target block, potentially including an exit condition.

### Methods
- **jumpfrom()**: Returns the line number where the source block ends.
- **jumpto()**: Returns the line number where the target block starts.
- **get_exitcase()**: Returns the Python source code string corresponding to the exit condition.
```

--------------------------------

### FuncBlock and TryBlock definitions

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

Specialized block classes for function definitions and try-except structures.

```python
class FuncBlock(Block):
    __slots__ = ("args", "name")

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.args: List[FuncBlock] = []
        self.name: Optional[str] = None

class TryBlock(Block):
    __slots__ = ("except_blocks",)

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.except_blocks: Dict[Optional[Exception], Block] = {}
    def get_source(self) -> str:
        """
        Get a string containing the Python source code corresponding to the
        statements in the block.

        Returns:
            A string containing the source code of the statements.
        """
        if not self.statements[1:]:
            return "try:"
        src = ""
        for statement in self.statements[1:]:  # We just want try body
            if type(statement) in [ast.If, ast.For, ast.While]:
                src += astor.to_source(statement).split("\n")[0] + "\n"
            elif (
                type(statement) == ast.FunctionDef
                or type(statement) == ast.AsyncFunctionDef
            ):
                src += (astor.to_source(statement)).split("\n")[0] + "...\n"
            else:
                src += astor.to_source(statement)
        return src
```

--------------------------------

### Handle Try-Except Blocks

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

Recursively visits except blocks within a TryBlock to include them in the graph visualization.

```Python
        if isinstance(block, TryBlock):
            for except_block in block.except_blocks.values():
                self._visit_blocks(graph, except_block, visited, calls, format)
```

--------------------------------

### Process Input Calls

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

Handles 'input' calls by creating a dedicated node for them and an edge connecting it to the current block. Other call lines are formatted and appended.

```Python
            tmp = ""
            for line in calls_label.splitlines():
                if "input" in line:
                    input_node = str(block.id) + "_input"
                    nodeshape, nodecolor = self.node_styles["input"]
                    graph.node(
                        input_node,
                        label=line,
                        _attributes={
                            "style": f"filled,{self.border_style(block, interactive)}",
                            "shape": nodeshape,
                            "fillcolor": self.fillcolor(block, interactive, nodecolor),
                        },
                    )
                    graph.edge(input_node, str(block.id))  # yellow
                    # _attributes={'style': 'dashed'})

                else:
                    line += "\l"
                    tmp += line
```

--------------------------------

### Block Highlight API

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/model.html

Provides functionality to highlight blocks based on a list of lines in interactive mode.

```APIDOC
## highlight_blocks API

### Description
In interactive mode, highlights blocks corresponding to the provided lines. It first clears any previous highlights, then iterates through the lines, identifies associated blocks, marks them for highlighting, and stores them.

### Method
Not applicable (Python method)

### Endpoint
Not applicable (Python method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Assuming 'obj' is an instance of the class containing this method
lines_to_highlight = [5, 10, 15]
result = obj.highlight_blocks(lines=lines_to_highlight)
```

### Response
#### Success Response (0)
Returns 0 upon successful execution.

#### Response Example
```json
0
```
```

--------------------------------

### Clean CFG

Source: https://py2cfg.readthedocs.io/en/latest/builder_link.html

Removes redundant blocks from a Control Flow Graph.

```APIDOC
## Function: clean_cfg

### Description
Removes useless (empty) blocks from a Control Flow Graph (CFG) by traversing it starting from a given block.

### Method
`clean_cfg(block, visited)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None (This function modifies the CFG in place and returns None).

#### Response Example
None
```

--------------------------------

### Visit For Loop for CFG

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Generates the CFG for a 'for' loop, establishing blocks for the loop guard, the loop body, and the code following the loop. It uses the loop stack to handle break and continue.

```python
def visit_For(self, node: For) -> None:
        # TODO for/else

        loop_guard = self.new_loopguard()
        self.current_block = loop_guard
        self.add_statement(self.current_block, node)

        if isinstance(node.iter, ast.Call):
            self.visit(node.iter)
        # New block for the body of the for-loop.
        for_block = self.new_block()
        self.add_exit(self.current_block, for_block, node.iter)

        # Block of code after the for loop.
        afterfor_block = self.new_block()
        self.add_exit(self.current_block, afterfor_block)
        self.current_block = for_block

        # Push exit destinations for break/continue statements.
        # On break, control jumps to afterfor_block.
        # On continue, control jumps to loop_guard
        self.loop_stack.appendleft((afterfor_block, loop_guard))

        # Populate the body of the for loop.
        for child in node.body:
            self.visit(child)

        top = self.loop_stack.popleft()
        assert top == (afterfor_block, loop_guard)
        self.add_exit(self.current_block, loop_guard)

        # Continue building the CFG in the after-for block.
        self.current_block = afterfor_block
```

--------------------------------

### Visit Assert Statement (Python)

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Handles 'assert' statements by creating separate control flow paths for assertion success and failure. The failure path is marked as a final block in the CFG.

```python
    def visit_Assert(self, node):
        self.add_statement(self.current_block, node)
        # New block for the case in which the assertion 'fails'.
        failblock = self.new_block()
        self.add_exit(self.current_block, failblock, invert(node.test))
        # If the assertion fails, the current flow ends, so the fail block is a
        # final block of the CFG.
        self.cfg.finalblocks.append(failblock)
        # If the assertion is True, continue the flow of the program.
        successblock = self.new_block()
        self.add_exit(self.current_block, successblock, node.test)
        self.current_block = successblock
        self.generic_visit(node)
```

--------------------------------

### new_loopguard

Source: https://py2cfg.readthedocs.io/en/latest/builder_link.html

Creates a new block for a loop's guard and links it to the current block.

```APIDOC
## new_loopguard

### Description
Create a new block for a loop’s guard if the current block is not empty. Links the current block to the new loop guard.

### Response
- **Returns** (py2cfg.model.Block) - The block to be used as new loop guard.
```

--------------------------------

### Insertion into a Sorted List in Python

Source: https://py2cfg.readthedocs.io/en/latest/builder_link.html

This snippet demonstrates the insertion logic within a merge sort context, specifically handling the placement of an element (`key`) into its correct sorted position within a partially sorted list (`src`). It's used as part of the merge process.

```python
i = j - 1
key = src[j]
while i >= 0 and src[i] > key:
    src[i + 1] = src[i]
    i -= 1
src[i + 1] = key
```

--------------------------------

### Visit Continue Statement for CFG

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Handles the 'continue' statement in CFG generation. It adds the continue node and directs the control flow to the loop guard block.

```python
def visit_Continue(self, node):
        assert self.loop_stack
        loop_guard: Block
        _, loop_guard = self.loop_stack[0]
        self.add_statement(self.current_block, node)
        self.add_exit(self.current_block, loop_guard)
        self.current_block = self.new_block()
```

--------------------------------

### Visit If Statement for CFG

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Handles the 'if' statement by creating blocks for the test, body, and else branches, and connecting them appropriately in the CFG. It manages the exit to the block after the if statement.

```python
def visit_If(self, node: If) -> None:
        if_block = self.new_block()
        self.add_exit(self.current_block, if_block, node.test)

        afterif_block = self.new_block()
        if node.orelse:
            # Visit the children in the body of the else to populate the block.
            for child in node.orelse:
                self.visit(child)
            self.add_exit(self.current_block, afterif_block)
        else:
            self.add_exit(self.current_block, afterif_block, invert(node.test))

        # Visit children to populate the if block.
        self.current_block = if_block
        for child in node.body:
            self.visit(child)
        self.add_exit(self.current_block, afterif_block)

        # Continue building the CFG in the after-if block.
        self.current_block = afterif_block
```

--------------------------------

### Visit Try Node in py2cfg

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Manages 'try' blocks, including handlers, 'else' clauses, and 'finally' blocks, by creating appropriate control flow graph structures.

```python
    def visit_Try(self, node: Try):
        try_block = self.new_try_block(node)
        after_tryblock = self.new_block()
        self.current_block.add_exit(try_block)
        stackobj = TryStackObject(try_block, after_tryblock, bool(node.finalbody))
        self.try_stack.appendleft(stackobj)

        stackobj.iter_state = TryEnum.EXCEPT
        for child in node.handlers:
            self.current_block = self.new_block()
            # If we encounter a raise statement during body iteration,
            # we can link the raise block to the appropriate exception block (if any).
            try_block.except_blocks[
                None if child.type is None else child.type.id
            ] = self.current_block
            self.visit(child)

        stackobj.iter_state = TryEnum.BODY
        self.current_block = try_block
        for child in node.body:
            self.visit(child)

        if node.orelse:
            stackobj.iter_state = TryEnum.ELSE
            else_block = self.new_block()
            self.current_block.add_exit(else_block)
            self.current_block = else_block
            for child in node.orelse:
                self.visit(child)

        self.current_block.add_exit(after_tryblock)
        self.current_block = after_tryblock
        if node.finalbody:
            stackobj.iter_state = TryEnum.FINAL
            for child in node.finalbody:
                if isinstance(child, ast.Raise):
                    top = self.try_stack.popleft()
                    self.visit_Raise(child)
                    self.try_stack.appendleft(top)
                    break
                self.visit(child)
            else:
                next_block = self.new_block()
                self.current_block.add_exit(next_block)
                self.current_block = next_block

        del self.try_stack[0]
```

--------------------------------

### Create Sub-CFGs

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Methods for creating nested CFGs for class and function definitions.

```python
    def new_classCFG(self, node: ClassDef, asynchr: bool = False) -> None:
        """
        Create a new sub-CFG for a class definition and add it to the
        class CFGs of the CFG being built.

        Args:
            node: The AST node containing the class definition.
            async: Boolean indicating whether the class for which the CFG is
                   being built is asynchronous or not.
        """
        self.current_id += 1
        # A new sub-CFG is created for the body of the class definition and
        # added to the class CFGs of the current CFG.
        class_body = ast.Module(body=node.body)
        class_builder = CFGBuilder(self.isShort, self._treebuf)
        self.cfg.classcfgs[node.name] = class_builder.build(
            node.name, class_body, asynchr, self.current_id
        )
        self.current_id = class_builder.current_id + 1
```

```python
    def new_functionCFG(self, node: FunctionDef, asynchr: bool = False) -> None:
        """
        Create a new sub-CFG for a function definition and add it to the
        function CFGs of the CFG being built.

        Args:
            node: The AST node containing the function definition.
            async: Boolean indicating whether the function for which the CFG is
                   being built is asynchronous or not.
        """
        self.current_id += 1
        # A new sub-CFG is created for the body of the function definition and
        # added to the function CFGs of the current CFG.
        func_body = ast.Module(body=node.body)
        func_builder = CFGBuilder(self.isShort, self._treebuf)
```

--------------------------------

### new_classCFG

Source: https://py2cfg.readthedocs.io/en/latest/builder_link.html

Creates a new sub-CFG for a class definition and adds it to the class CFGs of the CFG being built.

```APIDOC
## new_classCFG

### Description
Create a new sub-CFG for a class definition and add it to the class CFGs of the CFG being built.

### Parameters
- **node** (_ast.ClassDef) - Required - The AST node containing the class definition.
- **asynchr** (bool) - Optional - Boolean indicating whether the class for which the CFG is being built is asynchronous or not.
```

--------------------------------

### Visit Assignment Node in AST

Source: https://py2cfg.readthedocs.io/en/latest/_modules/py2cfg/builder.html

Handles the visit of an Assign node in the AST. Adds the assignment statement to the current block and then visits its children.

```python
    def visit_Assign(self, node: Assign) -> None:
        self.add_statement(self.current_block, node)
        self.generic_visit(node)
```

--------------------------------

### Format Code with Black

Source: https://py2cfg.readthedocs.io/en/latest/index.html

Command to format Python code in the py2cfg directory using the Black code formatter.

```shell
black py2cfg/*.py

```
Tokens:
Raw