staticfg

library0.9.5pypypi✓ verified 84d ago

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.

data testing

pip install staticfg

github ↗package ↗

INSTALL

IMPORT

SIG · STATICFG

staticfg

datapythonv0.9.5

Install

1.6s avg

Import

113ms

Disk

41MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.9.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.116s · 66MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.110s · 19MB

41MB installed

● package 41MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CFGBuilder

✓ from staticfg import CFGBuilder

CFG

✓ from staticfg.cfg import CFG

✗ from staticfg 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.

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.

staticfg --version

Debug

Known issues

gotchaVisualizing 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.

affects: All versions

gotchaStaticFG 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.

affects: All versions

gotchaThe `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`.

affects: All versions

Errors

Common errors & fixes

FileNotFoundError: [Errno 2] No such file or directory: 'dot'

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...']

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'

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'

The Python `graphviz` package, which `staticfg` uses for visualization bindings, is not installed.

fix

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

Upgrade

Version history

0.9.5latest on PyPI · released Jun 11, 2020

Audit

Dependencies

graphvizrequiredRequired for building visual representations of the CFGs using Python bindings. While technically optional for core CFG object generation, it's essential for the primary visualization use case.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/coetaur0/staticfg ↗

packagehttps://pypi.org/project/staticfg/ ↗