The Builder API

The Builder API

This page covers the friendly builder API — the way you actually construct models.

Friendly names

Friendly names drop the Builder/Usage/Definition suffixes. Part, Attribute, Item, Port, Requirement, Reference, ... are builders:

from sysml2py import Part, Attribute, Item, Port

Part('Stage_1')          # part Stage_1;
Attribute('mass')        # attribute mass;
Item('payload')          # item payload;
Port('inlet')            # port inlet;

The classic explicit names are still there if you prefer them: PartUsageBuilder, ItemUsageBuilder, PortUsageBuilder, and so on.

A note on container names

Names that collide with AST node classes keep the *Builder suffix: PackageBuilder, CommentBuilder, ImportBuilder, MessageBuilder, SuccessionBuilder, AliasMemberBuilder.

Usage vs. definition via kind=

A builder defaults to a usage. Pass kind='definition' for a definition:

Part('Stage_1')                            # part Stage_1;
Part('Stage_1', kind='definition')         # part def Stage_1;
Attribute('mass', kind='definition')       # attribute def mass;

Kinds that have no definition form — Package, Comment, Actor, Reference, Transition, Import, Message, Succession, AliasMember, Subject, ObjectiveRequirement — raise a ValueError if you ask for kind='definition'. A class-name kind like kind='PartDefinition' also raises, because that would print invalid SysML. The generator never emits a definition it cannot cast back.

Composing with add()

add() appends a child, so a full model nests naturally:

from sysml2py import PackageBuilder, Part, Attribute

pkg = PackageBuilder('MyModel')
stage = Part('Stage_1')
stage.add(Attribute('mass'))
stage.add(Attribute('thrust'))
pkg.add(stage)
print(pkg.dump())

package MyModel
{
   part Stage_1
   {
      attribute mass;
      attribute thrust;
   }
}

Everything is a Node

Every builder ultimately carries a generated AST Node. The package exposes the full class hierarchy plus traversal helpers: walk, walk_preorder, walk_postorder, find_all, canonical_equals for structure-aware comparison, and normalize_text.