Grimp

3.14 · active · verified Wed Apr 08

Grimp is a Python library (version 3.14) that builds a queryable graph of the imports within one or more Python packages. It provides tools for static analysis of import relationships and is actively maintained with regular updates for features and fixes.

Warnings

gotcha Grimp performs static analysis and may not accurately reflect imports that are dynamically loaded (e.g., using `importlib` or conditional imports based on runtime conditions). Always verify results for complex import patterns.
Fix: Manually inspect dynamic import sites or use runtime analysis tools in conjunction with Grimp for a complete picture.
breaking The internal API structure, especially module paths for core functions like `build_graph_from_path` or `ImportGraph`, might change between major or even minor versions. Always consult the release notes when upgrading.
Fix: Review the official Grimp documentation and release notes for updated import paths and API changes during upgrades. Update your import statements and method calls accordingly.
gotcha Grimp's analysis relies on the Python environment it's run in. If analyzing code that targets a different Python version or has specific `sys.path` configurations, Grimp might not resolve imports correctly. Ensure your analysis environment matches the target project's setup.
Fix: Run Grimp in a virtual environment configured with the target project's Python version and dependencies. Explicitly set `sys.path` if necessary to include all relevant source roots.

Install

pip install grimp Install Grimp

Imports

ImportGraph
```
from grimp.application.ports.import_graph import ImportGraph
```
This is a common pattern for accessing the core graph object. Exact path may vary slightly based on Grimp's internal structure; verify with official docs.
build_graph_from_path
```
from grimp.application.usecases import build_graph_from_path
```
Common function for constructing an import graph from a file path. Verify exact module path.

Quickstart

This quickstart demonstrates how to build an import graph for a sample Python package. It creates a temporary package structure, uses `build_graph_from_path` to analyze its imports, and then queries the resulting graph. The code includes a basic cleanup for the created files.

import os
from grimp.application.usecases import build_graph_from_path

# Create a dummy package structure for demonstration
os.makedirs('my_package/submodule', exist_ok=True)
with open('my_package/__init__.py', 'w') as f: f.write('')
with open('my_package/module_a.py', 'w') as f: f.write('from .module_b import B')
with open('my_package/module_b.py', 'w') as f: f.write('from my_package.submodule import C')
with open('my_package/submodule/__init__.py', 'w') as f: f.write('')
with open('my_package/submodule/module_c.py', 'w') as f: f.write('import os')


# Build the import graph for 'my_package'
package_path = 'my_package'
package_name = 'my_package'

# NOTE: The exact function signature and import path might vary slightly.
# Refer to Grimp's official documentation for the precise quickstart.
try:
    graph = build_graph_from_path(package_name, package_path)
    print(f"Nodes in graph: {graph.modules()}")
    print(f"Direct imports from module_a: {graph.direct_imports_for_module('my_package.module_a')}")
    # Cleanup dummy files
    import shutil
    shutil.rmtree('my_package')
except ImportError as e:
    print(f"Could not build graph, ensure grimp is installed and paths are correct: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →