sgraph
sgraph contains data format, structures and algorithms to work with hierarchic graph structures. Typically it is suitable for representing software architectures.
Documentation: https://softagram.github.io/sgraph/
See also sgraph-mcp-server for enabling AI agents to utilize sgraph information.
Install
pip install sgraph
Contributions
The project is welcoming all contributions.
Core Ontology
A model, SGraph consists of a root SElement, which may have children of the same type (as in XML).
Attribute information can be stored via key-value pairs into them.
The SElement objects can be connected together via SElementAssociation objects.
Example model
nginx model has an nginx root element that represents the main directory. Inside it, there is a src element. And inside src, there is core.
https://github.com/nginx/nginx/tree/master/src inside core, there are several elements, e.g. nginx.c and nginx.h
https://github.com/nginx/nginx/blob/master/src/core/nginx.c
Because nginx.c contains #include directive to nginx.h, in the model it is formulated so that there is a relationship (also called as association) from nginx.c element to nginx.h
To make model more explicit, that particular relationship should be annotated with type "inc" to describe the dependency type.
It is also possible to have other attributes assigned to relationships other than type but typically this is rare.
XML format
In XML dataformat, minimalism is the goal to make it simple and clean. Integers are used as unique identifiers for the elements. In the example case, the nginx.h element is assigned with ID 2 and the relationship that is inside nginx.c refers this way to nginx.h
This integer reference system has been designed to make the data format highly performing even with 10 million element models.
Deps data format - line based simple format for easy scripting
In Deps data format (usually a .txt file), the above model can be described minimally this way:
/nginx/src/core/nginx.c:/nginx/src/core/nginx.h:inc
Although this might seem very compelling data format to use, it is not recommended for very large models, e.g. 10 million elements.
Using the API
Creating a simple model:
>>> from sgraph import SGraph
>>> from sgraph import SElement
>>> from sgraph import SElementAssociation
>>> x = SGraph(SElement(None, ''))
>>> x
<SGraph empty elements=0 id=0x7f2efae9ad30>
>>> x.to_deps(fname=None)
>>> e1 = x.createOrGetElementFromPath('/path/to/file.x')
>>> e2 = x.createOrGetElementFromPath('/path/to/file.y')
>>> x.to_deps(fname=None)
/path
/path/to
/path/to/file.x
/path/to/file.y
>>> x.to_xml(fname=None)
<model version="2.1">
<elements>
<e n="path" >
<e n="to" >
<e n="file.x" >
</e>
<e n="file.y" >
</e>
</e>
</e>
</elements>
</model>
>>> ea = SElementAssociation(e1, e2, 'use')
>>> ea.initElems() # ea is not connected to the model before this call.
>>> x.to_deps(fname=None)
/path/to/file.x:/path/to/file.y:use
/path
/path/to
>>>
>>> x.to_xml(fname=None)
<model version="2.1">
<elements>
<e n="path" >
<e n="to" >
<e n="file.x" >
<r r="2" t="use" />
</e>
<e i="2" n="file.y" >
</e>
</e>
</e>
</elements>
</model>
Querying with Cypher
Models can be queried using the openCypher graph query language (requires optional dependency spycy-aneeshdurg):
from sgraph import SGraph
from sgraph.cypher import cypher_query
model = SGraph.parse_xml_or_zipped_xml('model.xml')
results = cypher_query(model, 'MATCH (a)-[r:inc]->(b) RETURN a.name, b.name')
A CLI with interactive REPL is also available:
pip install spycy-aneeshdurg
python -m sgraph.cypher model.xml.zip 'MATCH (n:file) RETURN n.name' # single query
python -m sgraph.cypher model.xml.zip # interactive REPL
python -m sgraph.cypher model.xml.zip -f dot 'MATCH (a)-[r]->(b) RETURN a, r, b' | dot -Tpng -o graph.png
See the Cypher documentation for full details and query examples.
Comparing models
Two models can be compared to see what was added, removed, or changed:
from sgraph.compare.modelcompare import ModelCompare
mc = ModelCompare()
compare_model = mc.compare('old_model.xml', 'new_model.xml') # returns an SGraph
mc.printCompareInfos(compare_model)
A CLI is also available (exit codes follow git diff: 0 = no differences, 1 = differences, 2 = error):
python -m sgraph.cli.compare old_model.xml new_model.xml # human-readable summary
python -m sgraph.cli.compare old_model.xml new_model.xml -f json # machine-readable JSON
python -m sgraph.cli.compare old_model.xml new_model.xml --rename-detection
See the API reference for the full comparison API.
Current utilization
Softagram uses it for building up the information model about the analyzed software.
1 maintainer
Metadata
1 maintainer
Release files for sgraph 1.20.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sgraph-1.20.0.tar.gz | 162.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sgraph-1.20.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 331.9 kB
Release files / sgraph-1.20.0.tar.gz
| Download URL | sgraph-1.20.0.tar.gz |
|---|---|
| Size | 162.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e3f27363899e89346e0d636b2d546e7521bd7254e16c255ae57ca5b35a23a579
|
|
BLAKE2b-256 checksum How to use checksums |
73cd337afa989a97579a04bc2b70f37cb4604d888dbe74d95b85438b5742014e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.7
|
Release files / sgraph-1.20.0-py3-none-any.whl
| Download URL | sgraph-1.20.0-py3-none-any.whl |
|---|---|
| Size | 169.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
87f9149bec4873f73ab5becd99f64c41e20ab5484246b27d6eedee0e23e576f7
|
|
BLAKE2b-256 checksum How to use checksums |
c5f96cf0d77150652601930232942f8e905e093b6061e641d6030abdf34c17f3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.7
|
