NodeGraphQt - Moses Yebei

The Problem

Building node-based UIs (DCC tools, data pipelines, shader graphs) from scratch on Qt means reimplementing the same hard parts every time: scene management, pipe routing, node selection, undo/redo, and property panels. NodeGraphQt packages those pieces into a reusable framework so you build the node logic instead of the graph plumbing.

What This Does

NodeGraphQt is a node graph UI framework for Python/Qt. The core lives in NodeGraphQt/base/graph.py (graph management, 135 functions) and NodeGraphQt/widgets/viewer.py (the QGraphicsView wrapper). Rendering is split across NodeGraphQt/qgraphics/ — node_base.py, port.py, pipe.py — while NodeGraphQt/base/commands.py implements undo/redo with 13 command classes. The examples/ folder has a basic_example.py entry point and custom node/widget samples.

How It Is Wired

Execution starts at main in examples/basic_example.py:18, which reaches 253 functions. The graph object routes most traffic: NodeGraphQt/base/graph.py is called from 26 files and calls into 21, making it the primary hub. High-blast-radius functions include scene (38 call sites), name (35), boundingRect (31), and set_property (28).

The import graph shows 14 modules in circular dependencies, including __init__.py, base/graph.py, and nodes/base_node.py. Breaking a cycle means touching several files at once. constants.py is imported by 32 modules — keep it stable.

The only traced filesystem effect is main -> set_context_menu_from_file, which reads a JSON menu file. No database or network I/O was found in the resolved call graph.

File map: base/graph.py owns graph lifecycle and context menus; base/commands.py owns undo/redo; widgets/viewer.py owns the viewport and context menu building; qgraphics/* owns rendering and interaction; custom_widgets/properties_bin/* owns the property panel.

How To Use It

Setup: Install with pip install NodeGraphQt (per README), or clone and run pip install -r requirements.txt from requirements.txt. No lockfile is present, so builds are not fully reproducible.

Running it: python examples/basic_example.py — creates a NodeGraphWidget, registers a custom node class, and displays the viewer. No environment variables or config files are required.

Real-World Use

A DCC integration script that registers tool-specific nodes:

from NodeGraphQt import NodeGraphWidget, BaseNode

class MyNode(BaseNode):
    __identifier__ = "com.example"
    NODE_NAME = "My Node"
    def run(self):
        # tool-specific logic
        pass

graph = NodeGraphWidget()
graph.register_node(MyNode)
node = graph.create_node("com.example.MyNode")
graph.set_node_selected(node, True)

Code Health & Issues

Static analysis (78 modules, 148 import edges) found 54 findings: 34 high, 20 medium. Key issues:

High - Import cycles (14 modules): __init__.py, nodes/base_node.py, base/node.py participate in circular imports. Fix: extract shared types or defer imports.
High - Deep nesting (32 files): qgraphics/node_base.py hits indentation depth 9. Fix: early returns/guard clauses.
High - Oversized files (5): nodes/base_node.py at 758 lines. Fix: split by responsibility.
High - Duplicated code (24 files): 425 repeated 6-line blocks. Fix: extract shared helpers.

SDLC observations: no test suite exists (56 source files, zero tests); CI uses unpinned third-party actions (pypa/gh-action-pypi-publish@release/v1, ts-graphviz/setup-graphviz@v1); sphinx_doc_build.yml pushes directly to the pages branch; no Dependabot/Renovate configured. These are structural facts from the file tree and workflow files.

The Bottom Line

Solid, well-documented framework for Qt-based node graphs, with working examples and a real PyPI release. The lack of tests and the import cycles make it risky to modify internals without a safety net. Use it if you need a node UI and can tolerate adding your own test coverage.

What the analyser found

Deployment readiness

4/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

186 files

Python75
reStructuredText25
HTML16
CSS5
JavaScript3
YAML2

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["NodeGraphQt<br/>55 modules"] g1["docs<br/>13 modules"] g2["examples<br/>9 modules"] g2 -->|7| g0 g1 -->|1| g0

Module dependencies

The 10 most depended-upon modules of 78, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_NodeGraphQt_constants["constants"] n1_NodeGraphQt___init__["__init__"] n2_NodeGraphQt_errors["errors"] n3_NodeGraphQt_nodes_base_node["base_node"] n4_eGraphQt_qgraphics_node_base["node_base"] n5_NodeGraphQt_base_node["node"] n6_NodeGraphQt_base_commands["commands"] n7_NodeGraphQt_qgraphics_port["port"] n8_es_bin_prop_widgets_abstract["prop_widgets_abstract"] n9_sphinxawesome_theme___init__["__init__"] n1_NodeGraphQt___init__ --> n5_NodeGraphQt_base_node n1_NodeGraphQt___init__ --> n3_NodeGraphQt_nodes_base_node n6_NodeGraphQt_base_commands --> n0_NodeGraphQt_constants n5_NodeGraphQt_base_node --> n6_NodeGraphQt_base_commands n5_NodeGraphQt_base_node --> n0_NodeGraphQt_constants n5_NodeGraphQt_base_node --> n1_NodeGraphQt___init__ n3_NodeGraphQt_nodes_base_node --> n6_NodeGraphQt_base_commands n3_NodeGraphQt_nodes_base_node --> n5_NodeGraphQt_base_node n3_NodeGraphQt_nodes_base_node --> n0_NodeGraphQt_constants n3_NodeGraphQt_nodes_base_node --> n2_NodeGraphQt_errors n3_NodeGraphQt_nodes_base_node --> n4_eGraphQt_qgraphics_node_base n3_NodeGraphQt_nodes_base_node --> n1_NodeGraphQt___init__ n4_eGraphQt_qgraphics_node_base --> n0_NodeGraphQt_constants n4_eGraphQt_qgraphics_node_base --> n2_NodeGraphQt_errors n4_eGraphQt_qgraphics_node_base --> n7_NodeGraphQt_qgraphics_port n7_NodeGraphQt_qgraphics_port --> n0_NodeGraphQt_constants classDef cyc stroke:#ef4444,stroke-width:2px; class n1_NodeGraphQt___init__,n3_NodeGraphQt_nodes_base_node,n5_NodeGraphQt_base_node cyc;

Findings

MediumNo test files detected - untested code paths repository-wide
LowDependencies declared without a lockfile - non-reproducible builds requirements.txt

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium4

low1

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

pypa/gh-action-pypi-publish@release/v1, ts-graphviz/setup-graphviz@v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Add a test suite; this repository has nonehigh56 occurrences

56 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Open a pull request instead of pushing to the default branchhigh

.github/workflows/sphinx_doc_build.yml

git push origin $PAGES_BRANCH

Automated commits land on the branch that deploys, with no test having run against the result.

Fix: Push to a bot branch and open a pull request, or restrict the push to a tag ref.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/sphinx_doc_build.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/pypi_publish.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/pypi_publish.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.