StaticFG

0.9.5 · active · verified Fri Apr 17

StaticFG is a Python library (current version 0.9.5) designed to generate control flow graphs (CFGs) for Python 3 programs. It parses Python source code, builds an Abstract Syntax Tree (AST), and then transforms it into a CFG, which can be visualized using Graphviz. The project is actively maintained with a moderate release cadence.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'dot'
```
cause The Graphviz system package (which provides the 'dot' command) is not installed on your operating system or is not in your system's PATH.

fix Install Graphviz for your operating system (e.g., `sudo apt-get install graphviz` on Debian/Ubuntu, `brew install graphviz` on macOS, or download from graphviz.org for Windows). Ensure the `dot` command is accessible from your shell.
```
subprocess.CalledProcessError: Command '['dot', '-Tpdf', 'temp.dot']' returned non-zero exit status 1. [stderr: b'Error: test.dot: syntax error in line 1...']
```
cause While 'dot' is found, the input DOT file generated by StaticFG might be malformed due to an issue with the Python code's AST processing, or 'dot' is installed but cannot access temporary files.

fix This is less common. Try simplifying the input Python code to isolate the problematic construct. Ensure the directory where `build_visual` attempts to save the output has write permissions.
```
AttributeError: module 'staticfg' has no attribute 'CFG'
```
cause Attempting to import the `CFG` class directly from the top-level `staticfg` package.

fix Import `CFG` explicitly from `staticfg.cfg`: `from staticfg.cfg import CFG`.
```
ModuleNotFoundError: No module named 'graphviz'
```
cause The Python `graphviz` package, which `staticfg` uses for visualization bindings, is not installed.

fix Install the Python `graphviz` package: `pip install graphviz`.

Warnings

gotcha Visualizing CFGs using `build_visual()` requires the `graphviz` *system tool* (specifically the `dot` command) to be installed on your operating system and accessible in your system's PATH. This is in addition to the Python `graphviz` package. Without it, visualization methods will fail with a `FileNotFoundError` or `subprocess.CalledProcessError`.
Fix: Install Graphviz on your operating system (e.g., `sudo apt-get install graphviz` on Debian/Ubuntu, `brew install graphviz` on macOS, or download from graphviz.org for Windows). Then verify `dot -V` works in your terminal.
gotcha StaticFG builds CFGs by parsing Python Abstract Syntax Trees (ASTs). While generally robust, it might not perfectly represent all highly complex or dynamically generated Python constructs. Some advanced features or highly dynamic code might result in an incomplete or misleading CFG.
Fix: Simplify complex code structures if CFG output is unexpected, or manually verify the generated graph against the expected control flow for correctness.
gotcha The `CFG` class, which represents the generated control flow graph, is not directly importable from the top-level `staticfg` package. Attempting `from staticfg import CFG` will result in an `AttributeError`.
Fix: Import the `CFG` class explicitly from its submodule: `from staticfg.cfg import CFG`.

Install

pip install staticfg Install core StaticFG library
pip install graphviz Install Python Graphviz bindings (required for visualization)

Imports

CFGBuilder
```
from staticfg import CFGBuilder
```
CFG
wrong:
```
from staticfg import CFG
```
correct:
```
from staticfg.cfg import CFG
```
The `CFG` class, representing the generated graph, is not directly exposed at the top-level `staticfg` package. It resides in the `staticfg.cfg` submodule.

Quickstart

Demonstrates how to build a control flow graph from a Python string and attempt to visualize it as a PDF. Note that the Graphviz *system tool* (providing the `dot` command) must be installed and in your system's PATH for visualization to succeed.

import os
from staticfg import CFGBuilder

# Define a simple Python function as a string
code = """
def greet(name):
    if name:
        message = f"Hello, {name}!"
    else:
        message = "Hello, World!"
    print(message)
"""

# Build the CFG from the source string
# The first argument 'greet_cfg' is the name of the CFG (often the function name)
# The second argument is the source code string
cfg = CFGBuilder().build_from_src('greet_cfg', code)

# To visualize, you need the Graphviz system tool installed and in your PATH.
# The output will be 'greet_cfg.pdf' in the current directory.
try:
    cfg.build_visual('greet_cfg', 'pdf')
    print("CFG 'greet_cfg.pdf' generated successfully.")
except Exception as e:
    print(f"Could not build visual graph. Make sure Graphviz (dot command) is installed and in your PATH. Error: {e}")
    # In a real application, you might log this error or notify the user.

view raw JSON →