| file_format |
|---|
mystnb |
One way to work with models is through the GUI. However, you may also be interested in getting more out of your models by interacting with them through Python scripts and Jupyter notebooks.
You can use scripts to:
- Explore the model, check for (in)valid conditions.
- Generate code, as is done for Gaphor’s data model.
- Update a model from another source, like a CSV file.
Since Gaphor is written in Python, it also functions as a library.
To get started, you’ll need a Python console. You can use the interactive console in Gaphor, use a Jupyter notebook, although that will require setting up a Python development environment.
The first step is to load a model. For this you’ll need an
{obj}gaphor.core.modeling.ElementFactory. The
ElementFactory is responsible to creating and maintaining the model. It acts
as a repository for the model while you’re working on it.
from gaphor.core.modeling import ElementFactory
element_factory = ElementFactory()
The module gaphor.storage contains everything to load and save models. Gaphor
supports multiple modeling languages. The
ModelingLanguageService consolidates those languages and makes it easy for the
loader logic to find the appropriate classes.
In versions before 2.13, an `EventManager` is required. In later versions, the
`ModelingLanguageService` can be initialized without event manager.
:tags: [remove-stderr]
from gaphor.core.eventmanager import EventManager
from gaphor.services.modelinglanguage import ModelingLanguageService
from gaphor.storage import storage
event_manager = EventManager()
modeling_language = ModelingLanguageService(event_manager=event_manager)
with open("../models/Core.gaphor", encoding="utf-8") as file_obj:
storage.load(
file_obj,
element_factory,
modeling_language,
)
At this point the model is loaded in the element_factory and can be queried.
A modeling language consists of the model elements, and diagram items.
Graphical components are loaded separately.
For the most basic manupilations, GTK (the GUI toolkit we use) is not required,
but you may run into situations where Gaphor tries to load the GTK library.
One trick to avoid this (when generating Sphinx docs at least) is to use
autodoc’s mock function to mock out the GTK and GDK libraries. However, Pango
needs to be installed for text rendering.
A simple query only tells you what elements are in the model. The method
ElementFactory.select() returns an iterator. Sometimes it’s easier to obtain a
list directly. For those cases you can use ElementFatory.lselect(). Here we
select the last five elements:
for element in element_factory.lselect()[:5]:
print(element)
Elements can also be queried by type and with a predicate function:
from gaphor import UML
for element in element_factory.select(UML.Class):
print(element.name)
for diagram in element_factory.select(
lambda e: isinstance(e, UML.Class) and e.name == "Diagram"
):
print(diagram)
Now, let’s say we want to do some simple (pseudo-)code generation. We can iterate class attributes and write some output.
diagram: UML.Class
def qname(element):
return ".".join(element.qualifiedName)
diagram = next(element_factory.select(lambda e: isinstance(e, UML.Class) and e.name == "Diagram"))
print(f"class {diagram.name}({', '.join(qname(g) for g in diagram.general)}):")
for attribute in diagram.attribute:
if attribute.typeValue:
# Simple attribute
print(f" {attribute.name}: {attribute.typeValue}")
elif attribute.type:
# Association
print(f" {attribute.name}: {qname(attribute.type)}")
To find out which relations can be queried, have a look at the modeling language documentation. Gaphor’s data models have been built using the UML language.
You can find out more about a model property by printing it.
print(UML.Class.ownedAttribute)
In this case it tells us that the type of UML.Class.ownedAttribute is
UML.Property. UML.Property.class_ is set to the owner class when
ownedAttribute is set. It is a bidirectional relation.
Another nice feature is drawing the diagrams. At this moment this requires a
function. This behavior is similar to the diagram directive.
from gaphor.core.modeling import Diagram
from gaphor.extensions.ipython import draw
d = next(element_factory.select(Diagram))
draw(d, format="svg")
(Requires Gaphor 2.13)
Now let's make something a little more fancy. We still have the core model loaded in the element factory. From this model we can create a custom diagram. With a little help of the auto-layout service, we can make it a readable diagram.
To create the diagram, we drop elements on the
diagram. Items on a diagram represent an element in the model. We'll also drop
all associations on the model. Only if both ends can connect, the association
will be added.
from gaphor.diagram.drop import drop
from gaphor.extensions.ipython import auto_layout
temp_diagram = element_factory.create(Diagram)
for name in ["Presentation", "Diagram", "Base"]:
element = next(element_factory.select(
lambda e: isinstance(e, UML.Class) and e.name == name
))
drop(element, temp_diagram, x=0, y=0)
# Drop all assocations, see what sticks
for association in element_factory.lselect(UML.Association):
drop(association, temp_diagram, x=0, y=0)
auto_layout(temp_diagram)
draw(temp_diagram, format="svg")
The diagram is not perfect, but you get the picture.
Updating a model always starts with the element factory: that’s where elements are created.
To create a UML Class instance, you can:
my_class = element_factory.create(UML.Class)
my_class.name = "MyClass"
To give it an attribute, create an attribute type (UML.Property) and then
assign the attribute values.
my_attr = element_factory.create(UML.Property)
my_attr.name = "my_attr"
my_attr.typeValue = "string"
my_class.ownedAttribute = my_attr
Adding it to the diagram looks like this:
my_diagram = element_factory.create(Diagram)
drop(my_class, my_diagram, x=0, y=0)
draw(my_diagram, format="svg")
If you save the model, your changes are persisted:
model_filename = "../my-model.gaphor"
with open(model_filename, "w") as out:
storage.save(out, element_factory)
If you need to update existing elements, this can be done by keeping track of the element ID. Each element in the model has a unique internal id. Once again we need some imports from Gaphor:
from pathlib import Path
from gaphor import UML
from gaphor import SysML
from gaphor.application import Session # needed to run services
from gaphor.transaction import Transaction # needed to make changes
from gaphor.storage import storage # needed to save to file
Then start up the services we will use:
session = Session(
services=[
"event_manager",
"component_registry",
"element_factory",
"element_dispatcher",
"modeling_language",
]
)
# Get services we need.
element_factory = session.get_service("element_factory")
modeling_language = session.get_service("modeling_language")
event_manager = session.get_service("event_manager")
and load in the model to the session
with open(model_filename, encoding="utf-8") as file_obj:
storage.load(
file_obj,
element_factory,
modeling_language,
)
# Now we query the model to get the element we want to change:
the_class = next(
element_factory.select(
lambda e: isinstance(e, UML.Class) and e.name == "MyClass"
))
Importantly, the changes are made as part of a Transaction. Here we find the element with the same id, and then update
the content. We then save the altered model to a file.
# change the name and write back into the model
with Transaction(event_manager) as ctx:
the_class.name = "Not My Class Anymore"
the_class.ownedAttribute[0].typeValue = "updated string"
# Write changes to file here
with open(model_filename, "w") as out:
storage.save(out, element_factory)
What else is there to know…
- Gaphor supports derived associations. For example,
element.ownerpoints to the owner element. For an attribute that would be its containing class. - All data models are described in the
Modeling Languagessection of the docs. - If you use Gaphor’s Console, you’ll need to apply all changes in a transaction, or they will result in an error.
- If you want a comprehensive example of a code generator, have a look at Gaphor’s
codermodule. This module is used to generate the code for the data models used by Gaphor. - This page is rendered with MyST-NB. It’s actually a Jupyter Notebook!
Expanding on the information above the following snippetts show how to create requirements and interfaces.
txts = ['req1', 'req2', 'bob the cat']
outfile = "requirement_example.gaphor"
with Transaction(event_manager) as ctx:
my_diagram = element_factory.create(Diagram)
my_diagram.name= 'my diagram'
reqPackage = element_factory.create(UML.Package)
reqPackage.name = "Requirements"
drop(reqPackage, my_diagram, x=0, y=0)
for req_id,txt in enumerate(txts):
my_class = element_factory.create(SysML.sysml.Requirement)
my_class.name = f"{req_id}-{txt[:3]}"
my_class.text = f"{txt}"
my_class.externalId = f"{req_id}"
drop(my_class, my_diagram, x=0, y=0)
# Save the model or export diagrams.
# get interface definitions from file into this dictionary format
interfaces = {'Interface1': ['signal1:type1', 'signal2:type1', 'signal3:type1'],
'Interface2': ['signal4:type2', 'signal5:type2', 'signal6:type2']}
outfile = 'interface_example.gaphor'
with Transaction(event_manager) as ctx:
my_diagram = element_factory.create(UML.Diagram)
my_diagram.name=' my diagram'
intPackage = element_factory.create(UML.Package)
intPackage.name = "Interfaces"
drop(intPackage, my_diagram, x=0, y=0)
for interface,signals in interfaces.items():
my_class = element_factory.create(UML.uml.Interface)
my_class.name = f"{interface}"
for s in signals:
my_attr = element_factory.create(UML.Property)
name,vtype = s.split(':')
my_attr.name = name
my_attr.typeValue = vtype
my_class.ownedAttribute = my_attr
drop(my_class, my_diagram, x=0, y=0)
# Save the model or export diagrams.
Some simple validation checks can be run using a couple of small functions to select and evaluate elements.
# As before assume we have a factory service and the model is loaded
# Define a function to select an element
def element_select(element):
return isinstance(element, UML.Class)
# Define a validation rule - names must be capatalised
def rule(element):
return element.name[0].isupper()
# Define a message to display if the element fails the validation
msg = "Class Names must be capitalised"
element = next(element_factory.select(element_select))
is_valid = rule(element)
if not is_valid:
print(msg)
Here is another example:
gaphor-services