query

Description

syside.query: read-only queries over a loaded model.

Use this package to ask questions about a model that syside.load_model() has produced: find elements by name or metadata, walk generalization and containment hierarchies, and inspect features, connections, and variation points. No function here modifies the model.

Three kinds of names are exported:

  • Traversal primitives (get_specialized_elements(), find_specializing_elements(), and walk_containment()), which walk the type and ownership hierarchies.

  • Query functions built on those primitives, such as find_by_name() and find_by_type(). The model-wide lookups search the documents the model itself loaded, or the model’s and environment’s documents of the given tiers (syside.DocumentTier, e.g. PROJECT_TIERS), or with scope only one element’s subtree, and drop library elements under LibraryElementFilter.EXCLUDE.

  • Index types (NameIndex, TypeIndex, MetadataIndex) with matching build_*_index builders. Without an index, each query scans the model; when you repeat lookups, build the index once and pass it via the index= parameter to make each later lookup a dictionary read. An index never changes a query’s result, only its cost.

Every function returns a plain, fully materialized value (a list, set, bool, scalar, or None), never a lazy view of the model.

The get_ and find_ prefixes mark worst-case cost, not miss behavior (both return None on a miss). A get_* call never looks beyond the element it is handed: its cost is linear in path depth (get_by_path()) or in that element’s own relationships, never in the size of a model, document or subtree. A find_* call may search: its worst case is linear in the scope it searches. The prefix names the worst case, not every call; syside.query._functions gives each lookup’s cost. The accessors of the high-level API, in syside.experimental.query, follow the same rule.

Index

Classes

MetadataIndex

Metadata usages by definition, built once by build_metadata_index().

MultiplicityBounds

The declared multiplicity bounds of a feature.

NameIndex

Elements by name, built once by build_name_index().

TypeIndex

Elements by exact Python class, built once by build_type_index().

Unbounded

The unbounded (*) upper multiplicity bound: a top element ordered above every int.

Attributes

ALL_TIERS

R

PROJECT_TIERS

R

UNBOUNDED

R

The singleton Unbounded upper bound (*).

Functions

find_by_type

Return every element whose metaclass is X or a metamodel subtype of X, where element_type is X.STD.

get_declared_member

Return the member that namespace itself declares under name, or None, in constant time.

actors

Return the actor parameters in effect for element, in parameter order.

declared_actors

Return the actor parameters element declares itself, in declaration order.

containers

Yield the owner chain above element, nearest first.

annotated_elements

Return the elements metadata_usage annotates, linear in the number of annotated elements.

find_annotating_elements

Return every element annotating element, wherever it is owned (inverse of the annotated-element direction).

build_metadata_index

Build a MetadataIndex for model in one pass over the indexed documents.

build_name_index

Build a NameIndex for model in one pass over the indexed documents.

build_type_index

Build a TypeIndex for model in one pass over the indexed documents.

contains

Return whether container contains element (at any depth).

contents

Return the direct contents (owned elements) of element, linear in the number of owned elements.

connection_ends

Return the end features of connection (its connector_ends) as a list.

find_bindings_of

Find the binding connectors touching element and the bound counterpart.

cross_subsets

Return the features feature cross-subsets (via cross subsetting), linear in the number of cross-subsetted features.

find_features_crossing_through

Return the features whose crossed feature is feature or a feature chain through feature.

find_types_with_feature

Return every type that has feature among its features (inverse of features_of()).

find_features_with_featuring_type

Return every feature that has type_ among its featuring types (inverse of featured_in()).

all_contents

Deprecated since 1.1 (removed in 2.0): use scan_all_contents(), the same function, renamed to mark that it scans everything below element, the whole model from a root package. Returns scan_all_contents(element).

scan_all_contents

Yield every element below element in ownership, breadth-first.

description

Return the concatenated body text of element’s documentation, or None.

declared_types_of

Return the types feature declares, linear in the number of declared typings.

all_types_of

Return the types of feature: its declared typings and the types of the features it subsets or redefines, directly or indirectly.

documentation

Return the documentation elements owned by element, linear in the number of documentation elements.

enumeration_values

Return the enumerated values of enum_def, linear in the number of values.

exposed_elements

Return the elements exposed by view (its exposed_elements), linear in the number of exposed elements.

feature_chain

Return the chaining features of feature (the feature-chain links), linear in the chain length.

featured_in

Return the types that feature is featured by (KerML Feature::featuringType), linear in their number.

features_of

Return the visible features of type_, its own and the inherited ones (KerML Type::feature), linear in the feature count.

find_by_name

Return an element whose simple name is name, or None.

find_by_name_and_type

Deprecated

Deprecated since 1.1 (removed in 2.0): use find_by_name(model, name, element_type=...), which also takes scope, tiers, and X.STD metaclass tuples.

find_by_qualified_name

Return the element whose qualified name is exactly qualified_name, or None.

get_by_path

Return the element reached from root by following path, a list of simple names, or None.

find_elements_of_type

Deprecated

Deprecated since 1.1 (removed in 2.0): use find_by_type(model, X.STD), which also matches metamodel subtypes that are not Python subclasses (this function misses ConnectionUsage when asked for PartUsage) and takes scope and tiers.

find_metadata_usages

Return the metadata usages in scope and below it, optionally only those of one metadata definition.

find_relationships

Return every relationship of relationship_type, less those of exclude_subtypes_of.

has_metadata_prefix

Return whether element carries a metadata prefix named prefix_name.

find_connectors_of

Find every connector one of whose ends attaches to element.

find_connectors_to

Find the connectors with element on their target side.

find_connectors_from

Find the connectors with element on their source side.

inherited_features

Return the core Type.inherited_features view, linear in its size.

is_contained_in

Return whether element is nested anywhere inside container.

metadata_prefixes

Return element’s prefix metadata usages (the #Name prefixes), linear in the number of prefixes.

metadata_usages

Return all metadata usages owned by element (prefix and body), linear in the number of metadata usages.

multiplicity_bounds

Return the multiplicity bounds feature itself declares, or None.

implicit_multiplicity_bounds

Return 1..1 if SysML implicitly declares that multiplicity for usage, else None.

generalization_names

Return the rendered qualified names of the direct heritage targets.

find_redefining_features

Return the features that redefine feature (inverse of redefinition).

redefined_by

Deprecated since 1.1 (removed in 2.0): use find_redefining_features(), the same function, renamed to mark that it scans the model. Returns find_redefining_features(model, feature).

redefines

Return the features feature redefines (via redefinition), linear in the number of redefined features.

referenced_feature

Return the feature referenced by expression.

siblings

Return the other direct contents of element’s owner.

specializes

Return whether type_ specializes candidate_supertype, directly or indirectly.

superclassifiers

Return the classifiers type_ directly subclassifies (KerML superclassifiers), linear in their number.

subject_of

Return the subject parameter in effect for element, constant time.

declared_subject_of

Return the subject element declares itself, or None, constant time.

subsets

Return the features feature subsets, linear in the number of subsetted features.

find_subclassifiers

Return the classifiers that directly subclassify type_ (KerML subclassifiers).

specializations

Deprecated since 1.1 (removed in 2.0): use find_specializing_elements(), the same function, renamed to mark that it scans the model. Returns find_specializing_elements(model, target, via=via).

subclassifiers

Deprecated since 1.1 (removed in 2.0): use find_subclassifiers(), the same function, renamed to mark that it scans the model. Returns find_subclassifiers(model, type_).

supertypes

Return every type type_ inherits from, directly or indirectly, nearest first.

textual_representation

Return the body of element’s textual representation in language.

variants

Return the variant usages of a variation variation, linear in the number of variants.

find_specializing_elements

Return the elements that directly specialize target: the inverse of one step of get_specialized_elements().

generalizations

Deprecated since 1.1 (removed in 2.0): use get_specialized_elements(), the same function, renamed because it returns elements, not Generalization relationships. Returns get_specialized_elements(element, via=via, exclude=exclude, transitive=transitive).

get_specialized_elements

Return the heritage targets declared by element: the elements it specializes.

walk_containment

Walk the ownership tree from element, yielding the elements reached.

Enumerations

LibraryElementFilter

Whether a lookup returns elements that have is_library_element set.

LibraryElements

Which documents, and which library elements within them, the find_* lookups that take it and the index builders cover (the lookups are listed in the syside.query._functions module docstring).


Attributes

ALL_TIERS: Final[frozenset[syside.DocumentTier]] = 'frozenset(...)'

Every syside.DocumentTier: project, external, and standard library.

PROJECT_TIERS: Final[frozenset[syside.DocumentTier]] = 'frozenset(...)'

Every document whose tier is DocumentTier.Project.

That is the model’s and the environment’s Project documents: an environment document keeps tier Project when it is a document of another model passed in through Model.to_environment. Third-party libraries (External) and the standard library are not included.

This is not the default. A lookup or builder given no tiers covers the documents the model itself loaded (model.documents less the environment’s), whatever their tier, exactly as in 1.0; environment documents are covered only when tiers is passed.

UNBOUNDED: Final = 'Unbounded(...)'

The singleton Unbounded upper bound (*).

Functions

find_by_type(model: syside.Model, element_type: tuple[type[syside.query.find_by_type.ElementT], ...], *, scope: syside.Element | None = None, tiers: frozenset[syside.DocumentTier] | None = None, library_elements: syside.query.LibraryElementFilter = LibraryElementFilter.INCLUDE, index: syside.query.TypeIndex | None = None) → list[syside.query.find_by_type.ElementT]

Return every element whose metaclass is X or a metamodel subtype of X, where element_type is X.STD.

Given the SysML:

package P {
    part def A;
    part a : A;
    part b : A;
    connection c connect a to b;
    package Q {
        part def A;
    }
    library package L {
        part def LibA;
    }
}

each call returns the elements listed in its comment:

inner = find_by_qualified_name(model, "P::Q")

# A connection usage is a part usage in the metamodel.
find_by_type(model, syside.PartUsage.STD)        # P::a, P::b, P::c
find_by_type(model, syside.ConnectionUsage.STD)  # P::c
find_by_type(model, syside.PartUsage)            # TypeError

find_by_type(model, syside.PartDefinition.STD)   # P::A, P::Q::A, P::L::LibA
find_by_type(
    model, syside.PartDefinition.STD, scope=inner
)                                                # P::Q::A
find_by_type(
    model,
    syside.PartDefinition.STD,
    library_elements=LibraryElementFilter.EXCLUDE,
)                                                # P::A, P::Q::A

index = build_type_index(model)
find_by_type(
    model, syside.PartDefinition.STD, index=index
)                                                # P::A, P::Q::A, P::L::LibA

Without tiers the documents the model itself loaded are searched. tiers selects the model’s and environment’s documents of those syside.DocumentTier values instead, and an index must have been built with the same tiers, else ValueError.

Cost: linear in the searched documents, or in scope’s subtree; with an index, linear in the matching buckets. The order of the results may differ with and without an index.

get_declared_member(namespace: syside.Element, name: str) → syside.Element | None

Return the member that namespace itself declares under name, or None, in constant time.

Given the SysML:

package Lib {
    part def Imported;
}
package P {
    private import Lib::*;
    part def A;
    alias AP for A;
    package Q {
        part def B;
    }
}

and package = find_by_qualified_name(model, "P"):

get_declared_member(package, "A")         # P::A
get_declared_member(package, "AP")        # P::A, the target of the alias
get_declared_member(package, "B")         # None: P::Q declares it
get_declared_member(package, "Imported")  # None: P imports it

An element that is not a syside.Namespace has no members and yields None. No tier or library filtering applies.

actors(element: syside.query._CaseLike) → list[syside.PartUsage]

Return the actor parameters in effect for element, in parameter order.

Cost is O(a), where a is the number of actors returned. Reads the core actor_parameters accessor, present on requirement and case usages/definitions (and their subtypes: use-case, verification-case, analysis-case, …). The result is the effective list, not a union: actors are parameters, and an actor element declares redefines the inherited actor at the same position and replaces it, while inherited actors beyond the declared ones are kept. For use case def Base { subject s; actor driver; actor passenger; } and use case def Sub :> Base { subject :>> s; actor mech; }, actors(Sub) is [Sub::mech, Base::passenger] and driver is not returned. For only the actors element declares itself, use declared_actors().

declared_actors(element: syside.query._CaseLike) → list[syside.PartUsage]

Return the actor parameters element declares itself, in declaration order.

Cost is O(a), where a is the number of actors in effect for element (the inherited ones are visited and dropped).

Only the actor declarations written in element’s own body; inherited actors are left out. For every actor in effect, inherited ones included, use actors().

containers(element: syside.Element) → Iterator[syside.Element]

Yield the owner chain above element, nearest first.

annotated_elements(metadata_usage: syside.MetadataUsage) → list[syside.Element]

Return the elements metadata_usage annotates, linear in the number of annotated elements.

find_annotating_elements(model: syside.Model, element: syside.Element) → list[syside.AnnotatingElement | syside.MetadataUsage]

Return every element annotating element, wherever it is owned (inverse of the annotated-element direction).

That is every comment, documentation, textual representation and metadata usage whose annotated elements include element: those it owns (a doc, a #Tag prefix, which annotate their owning namespace) and those owned elsewhere (comment about X, metadata Tag about X;).

Linear in the model’s number of annotating elements. Results are in scan order, each once.

build_metadata_index(model: syside.Model, *, tiers: frozenset[syside.DocumentTier] | None = None, library_elements: syside.query.LibraryElements | None = None) → syside.query.MetadataIndex

Build a MetadataIndex for model in one pass over the indexed documents.

Given the SysML:

package P {
    metadata def Tag;
    part a { @Tag; }
    part b { @Tag; }
}

the index serves find_metadata_usages():

package = find_by_qualified_name(model, "P")
tag = find_by_qualified_name(model, "P::Tag")

index = build_metadata_index(model)
find_metadata_usages(package, definition=tag, index=index)
# @Tag on a, @Tag on b

tiers and the deprecated library_elements are as in build_name_index().

build_name_index(model: syside.Model, *, tiers: frozenset[syside.DocumentTier] | None = None, library_elements: syside.query.LibraryElements | None = None) → syside.query.NameIndex

Build a NameIndex for model in one pass over the indexed documents.

Given a model that declares part def Car; and part car : Car; in package P:

index = build_name_index(model)
find_by_qualified_name(model, "P::Car", index=index)  # P::Car
find_by_name(model, "car", index=index)               # P::car

# The standard library does not change, so its index never goes stale.
stdlib = frozenset({syside.DocumentTier.StandardLibrary})
stdlib_index = build_name_index(model, tiers=stdlib)
find_by_qualified_name(
    model, "ScalarValues::String", tiers=stdlib, index=stdlib_index
)                                                     # ScalarValues::String

Without tiers the documents the model itself loaded are indexed; with tiers, the model’s and environment’s documents of those syside.DocumentTier values. A lookup must ask for the same tiers as the index it is given (none, for an index built without), else ValueError. Library elements are indexed; lookups filter them with LibraryElementFilter.

library_elements is deprecated (since 1.1, removed in 2.0): it selects the 1.0 LibraryElements scope. Passing it together with tiers raises TypeError.

build_type_index(model: syside.Model, *, tiers: frozenset[syside.DocumentTier] | None = None, library_elements: syside.query.LibraryElements | None = None) → syside.query.TypeIndex

Build a TypeIndex for model in one pass over the indexed documents.

Given a model that declares part def Vehicle; and part def Car :> Vehicle; in package P:

index = build_type_index(model)
find_by_type(
    model, syside.PartDefinition.STD, index=index
)                                         # [P::Vehicle, P::Car]
find_relationships(
    model, syside.Subclassification.STD, index=index
)                                         # Car :> Vehicle, Vehicle :> Parts::Part

tiers and the deprecated library_elements are as in build_name_index().

contains(container: syside.Element, element: syside.Element) → bool

Return whether container contains element (at any depth).

The inverse reading of is_contained_in(): contains(a, b) == is_contained_in(b, a).

contents(element: syside.Element) → list[syside.Element]

Return the direct contents (owned elements) of element, linear in the number of owned elements.

connection_ends(connection: syside.ConnectionUsage) → list[syside.Feature]

Return the end features of connection (its connector_ends) as a list.

connector_ends is a syside.LazyIterator. .collect() drains it into a Python list in a single O(n) pass over the n ends, which is what you want when you need every end materialized: to index it, take its length, hold it, or walk it more than once. (Most connections have only two ends, so the cost is negligible here; the guidance matters for the larger lazy collections these query helpers also wrap.)

.for_each(callback) on the underlying connection.connector_ends is the alternative, but it is worth it only when the callback can stop early: it allocates no list and short-circuits when the callback returns a stop signal, yet it pays a Python call per element where .collect() builds the list in native code. For a full drain it is therefore the slower of the two, measured at 561 us against 392 us for .collect() at n=4000. Prefer .collect() unless you genuinely short-circuit, and expect the crossover only on large collections.

Do not read the ends back with repeated .at(i) / [i] indexing in a loop. A LazyIterator re-seeks from the head on each index, so an index-per-element loop is O(n²), measured ~67x slower than .collect() at n=4000 (74 ms vs 1.1 ms). A LazyIterator is not a Python iterable, so .collect() or .for_each() is the only correct way to walk all ends.

find_bindings_of(model: syside.Model, element: syside.Feature) → list[tuple[syside.ConnectorAsUsage, syside.Feature]]

Find the binding connectors touching element and the bound counterpart.

Every document of the user model is scanned (the same scope as find_connectors_of()), at a cost linear in the model’s size. Returns one (connector, other) pair per syside.BindingConnectorAsUsage in the model one of whose ends attaches to element, where other is the feature the opposite end references. Ends attach exactly as for find_connectors_of(), so a chained end (bind a.p = b.p) attaches to every link of its chain, and the same connectors are found by find_connectors_of(model, element, kind=syside.BindingConnectorAsUsage). For a chained opposite end other is the chain feature (b.p), whose links are available through feature_chain(). A binding both of whose ends attach to element contributes a pair with other being the second end’s feature (element itself for bind x = x).

cross_subsets(feature: syside.Feature) → list[syside.Feature]

Return the features feature cross-subsets (via cross subsetting), linear in the number of cross-subsetted features.

Cross subsetting is the connection/association-end crosses (=>) relationship; its target is the cross feature, typically a feature chain (the other end followed by that end’s cross feature). An ordinary feature yields [].

find_features_crossing_through(model: syside.Model, feature: syside.Feature) → list[syside.Feature]

Return the features whose crossed feature is feature or a feature chain through feature.

Given the SysML:

package P {
    part def A { part x : B[*]; }
    part def B { part y : A[*]; part w; }
    connection def Conn {
        end a : A crosses b.y;
        end b : B => a.x;
    }
}

each call returns the list in its comment:

y, w, b = (
    find_by_qualified_name(model, f"P::{name}")
    for name in ("B::y", "B::w", "Conn::b")
)

find_features_crossing_through(model, y)  # [P::Conn::a]
find_features_crossing_through(model, b)  # [P::Conn::a]
find_features_crossing_through(model, w)  # []

a crosses the chain b.y, which is what cross_subsets() returns for a. This function returns a for each link of that chain, so it is a superset of the inverse of cross_subsets().

Linear in the model’s number of cross subsettings. Results are in scan order, each once.

find_types_with_feature(model: syside.Model, feature: syside.Feature) → list[syside.Type]

Return every type that has feature among its features (inverse of features_of()).

Given the SysML:

package P {
    part def V {
        part w [2];
    }
    part def W :> V;
    part def X :> V {
        part redefines w;
    }
}

each call returns the list in its comment:

w = find_by_qualified_name(model, "P::V::w")

find_types_with_feature(model, w)               # [P::V, P::W]
find_types_with_feature(model, w.multiplicity)  # []

X is not returned: its own w redefines V::w, which features_of() therefore omits for X. The multiplicity is featured by V (see featured_in()) but is a feature of no type.

Linear in the total size of every type’s feature list. Only the model’s own documents are scanned, so a standard-library type is never returned. Results are in scan order, each once.

find_features_with_featuring_type(model: syside.Model, type_: syside.Type) → list[syside.Feature]

Return every feature that has type_ among its featuring types (inverse of featured_in()).

Given the SysML:

package P {
    part def V {
        part w [2];
    }
    part def W :> V;
}

each call returns the list in its comment:

V = find_by_qualified_name(model, "P::V")
W = find_by_qualified_name(model, "P::W")

find_features_with_featuring_type(model, V)
# [the literal 2, the multiplicity [2], P::V::w]
find_features_with_featuring_type(model, W)
# []: W inherits w but is not one of its featuring types

The multiplicity and its bound are not in features_of(V); see featured_in().

Linear in the total number of featuring types over every feature. Only the model’s own documents are scanned, so a standard-library feature is never returned. Results are in scan order, each once.

all_contents(element: syside.Element) → Iterator[syside.Element]

Deprecated since 1.1 (removed in 2.0): use scan_all_contents(), the same function, renamed to mark that it scans everything below element, the whole model from a root package. Returns scan_all_contents(element).

scan_all_contents(element: syside.Element) → Iterator[syside.Element]

Yield every element below element in ownership, breadth-first.

Linear in the size of element’s subtree, which from a root package is the model’s size. Each element is yielded once.

description(element: syside.Element) → str | None

Return the concatenated body text of element’s documentation, or None.

The bodies of every syside.Documentation owned by element are joined, in owned order, with a blank line between them, matching the way a VS Code hover concatenates multiple doc comments rather than showing only the first. None if element has no documentation.

declared_types_of(feature: syside.Feature) → list[syside.Type]

Return the types feature declares, linear in the number of declared typings.

Only the targets of feature’s own feature typings: what is written after : in the declaration (KerML FeatureTyping). A feature that declares no typing yields [], even when it conforms to types through subsetting or redefinition. For every type the feature conforms to, use all_types_of().

all_types_of(feature: syside.Feature) → list[syside.Type]

Return the types of feature: its declared typings and the types of the features it subsets or redefines, directly or indirectly.

Given the SysML:

package P {
    part def Vehicle;
    part def Car :> Vehicle;
    part car : Car;
    part spare :> car;
}

each call returns the value in its comment:

Vehicle, car, spare = (
    find_by_qualified_name(model, f"P::{name}")
    for name in ("Vehicle", "car", "spare")
)

declared_types_of(car)  # [P::Car]
all_types_of(car)
# [P::Car, Parts::Part, Items::Item, Objects::Object,
#  Occurrences::Occurrence, Base::Anything]

# car subsets Parts::parts, whose types are Parts::Part and the rest.
# A supertype of a typing is not added.
Vehicle in all_types_of(car)  # False

# spare declares no typing and has the types of car, which it subsets.
declared_types_of(spare)             # []
all_types_of(spare) == all_types_of(car)  # True

# The subsetted feature is a supertype of spare, not one of its types.
car in all_types_of(spare)  # False
car in supertypes(spare)    # True

KerML’s derived Feature::type (KerML 1.1 deriveFeatureType) is the same union with every type removed that another of them specializes. This function keeps those, Parts::Part next to P::Car above, so it returns a superset of Feature::type.

documentation(element: syside.Element) → list[syside.Documentation]

Return the documentation elements owned by element, linear in the number of documentation elements.

enumeration_values(enum_def: syside.EnumerationDefinition) → list[syside.EnumerationUsage]

Return the enumerated values of enum_def, linear in the number of values.

exposed_elements(view: syside.ViewUsage) → list[syside.Element]

Return the elements exposed by view (its exposed_elements), linear in the number of exposed elements.

feature_chain(feature: syside.Feature) → list[syside.Feature]

Return the chaining features of feature (the feature-chain links), linear in the chain length.

A feature that is not a chain yields [].

featured_in(feature: syside.Feature) → list[syside.Type]

Return the types that feature is featured by (KerML Feature::featuringType), linear in their number.

Given the SysML:

package P {
    part def V {
        part w [2];
    }
    part def W :> V;
}

each call returns the list in its comment:

w = find_by_qualified_name(model, "P::V::w")

featured_in(w)               # [P::V]
featured_in(w.multiplicity)  # [P::V]

This is not the inverse of features_of(), in both directions. w is a feature of W, which inherits it, but W is not one of its featuring types. The multiplicity [2] is featured by V but is not a feature of V: KerML gives a multiplicity, its bounds, and a feature-value expression the featuring types of their owner (KerML 1.1 checkMultiplicityTypeFeaturing, checkMultiplicityRangeExpressionTypeFeaturing, checkExpressionTypeFeaturing). The inverse is find_features_with_featuring_type().

features_of(type_: syside.Type) → list[syside.Feature]

Return the visible features of type_, its own and the inherited ones (KerML Type::feature), linear in the feature count.

Given the SysML:

package P {
    part def V {
        part w [2];
    }
    part def W :> V;
    part def X :> V {
        part redefines w;
    }
}

each call returns the list in its comment:

V, W, X = (
    find_by_qualified_name(model, f"P::{name}") for name in ("V", "W", "X")
)

features_of(V)  # [P::V::w, Parts::Part::self, ...]
features_of(W)  # [P::V::w, Parts::Part::self, ...]: w is inherited
features_of(X)  # [P::X::w, Parts::Part::self, ...]: V::w is redefined

The features inherited from the standard library are included. Only features held through a FeatureMembership count, so the multiplicity [2] of w is not a feature of V, although V is one of its featuring types (see featured_in()). The inverse is find_types_with_feature().

find_by_name(model: syside.Model, name: str, *, scope: syside.Element | None = None, tiers: frozenset[syside.DocumentTier] | None = None, library_elements: syside.query.LibraryElementFilter = LibraryElementFilter.INCLUDE, index: syside.query.NameIndex | None = None) → syside.Element | None
find_by_name(model: syside.Model, name: str, *, element_type: tuple[type[syside.query.find_by_name.ElementT], ...], scope: syside.Element | None = None, tiers: frozenset[syside.DocumentTier] | None = None, library_elements: syside.query.LibraryElementFilter = LibraryElementFilter.INCLUDE, index: syside.query.NameIndex | None = None) → syside.query.find_by_name.ElementT | None
find_by_name(model: syside.Element, name: str, *, recursive: bool = False) → syside.Element | None
find_by_name(*, scope: syside.Element, name: str, recursive: bool = False) → syside.Element | None

Return an element whose simple name is name, or None.

Given the SysML:

package P {
    part def A;
    part a : A;
    part b : A;
    connection c connect a to b;
    package Q {
        part def A;
    }
    library package L {
        part def LibA;
    }
}

each call returns the element named in its comment:

inner = find_by_qualified_name(model, "P::Q")

find_by_name(model, "a")                                  # P::a
find_by_name(model, "nope")                               # None
find_by_name(model, "A", scope=inner)                     # P::Q::A

# A connection usage is a part usage in the metamodel.
find_by_name(
    model, "c", element_type=syside.PartUsage.STD
)                                                         # P::c
find_by_name(
    model, "c", element_type=syside.PartDefinition.STD
)                                                         # None

find_by_name(model, "LibA")                               # P::L::LibA
find_by_name(
    model, "LibA", library_elements=LibraryElementFilter.EXCLUDE
)                                                         # None

index = build_name_index(model)
find_by_name(model, "a", index=index)                     # P::a

When several elements have the name (A above), which one is returned is unspecified; index.by_simple_name[name] lists them all.

Without tiers the documents the model itself loaded are searched. tiers selects the model’s and environment’s documents of those syside.DocumentTier values instead, and an index must have been built with the same tiers, else ValueError.

Cost: linear in the searched documents, or in scope’s subtree; one bucket read with an index. get_declared_member() finds a member a namespace declares in constant time.

Deprecated (since 1.1, removed in 2.0): find_by_name(scope, name, recursive=...) with an element as first argument, also written find_by_name(scope=scope, name=name). recursive=False is get_declared_member(); recursive=True returns the first element named name below scope, breadth-first.

find_by_name_and_type(model: syside.Model, name: str, element_type: type[syside.query.find_by_name_and_type.ElementT], *, library_elements: syside.query.LibraryElements = LibraryElements.WORKSPACE, index: syside.query.NameIndex | None = None) → syside.query.find_by_name_and_type.ElementT | None

Deprecated since 1.1 (removed in 2.0): use find_by_name(model, name, element_type=...), which also takes scope, tiers, and X.STD metaclass tuples.

Find the first model element of type element_type named name.

Returns the first (scan-order) element whose simple name equals name and which is an instance of element_type (Python subclasses included, metamodel subtypes that are not Python subclasses missed), or None. library_elements selects which documents are scanned and which library elements within them are matched (see LibraryElements). With an index this is a single name-bucket read; without one it is linear in the scanned documents’ size.

find_by_qualified_name(model: syside.Model, qualified_name: str, *, tiers: frozenset[syside.DocumentTier] | None = None, library_elements: syside.query.LibraryElementFilter | syside.query.LibraryElements = LibraryElementFilter.INCLUDE, index: syside.query.NameIndex | None = None) → syside.Element | None

Return the element whose qualified name is exactly qualified_name, or None.

Given the SysML:

package P {
    part def A;
    alias AP for A;
    library package L {
        part def LibA;
    }
}

each call returns the element named in its comment:

find_by_qualified_name(model, "P::A")                     # P::A
find_by_qualified_name(model, "P::nope")                  # None

# An alias is not the element's own name; get_by_path follows aliases.
find_by_qualified_name(model, "P::AP")                    # None

find_by_qualified_name(model, "P::L::LibA")               # P::L::LibA
find_by_qualified_name(
    model, "P::L::LibA", library_elements=LibraryElementFilter.EXCLUDE
)                                                         # None

# Without tiers, only the documents the model itself loaded are searched.
stdlib = frozenset({syside.DocumentTier.StandardLibrary})
find_by_qualified_name(model, "ScalarValues::String")     # None
find_by_qualified_name(
    model, "ScalarValues::String", tiers=stdlib
)                                                         # ScalarValues::String

# An index must have been built with the same tiers as the lookup.
index = build_name_index(model)
find_by_qualified_name(model, "P::A", index=index)        # P::A
find_by_qualified_name(
    model, "P::A", tiers=stdlib, index=index
)                                                         # ValueError

tiers selects the model’s and environment’s documents of those syside.DocumentTier values: a document passed in through Model.to_environment is searched only when tiers contains its tier.

When several documents declare a root package of the same name, the bare name returns the first in document order; the members of each are found by their own qualified names.

Cost: without an index, one member lookup per name segment per searched document; with one, a dict read.

Passing a LibraryElements is deprecated (since 1.1, removed in 2.0) and keeps its 1.0 document selection; it cannot be combined with tiers.

get_by_path(root: syside.Element, path: list[str]) → syside.Element | None

Return the element reached from root by following path, a list of simple names, or None.

Given the SysML:

package P {
    part def A;
    alias AP for A;
    package Q {
        part def B;
    }
}

and package = find_by_qualified_name(model, "P"):

get_by_path(package, ["Q", "B"])     # P::Q::B
get_by_path(package, ["AP"])         # P::A
get_by_path(package, ["Q", "nope"])  # None
get_by_path(package, [])             # P

Each name is looked up with get_declared_member(), so an alias is followed and an imported member is not found. No tier or library filtering applies. Linear in the path length.

find_elements_of_type(model: syside.Model, element_type: type[syside.query.find_elements_of_type.ElementT], *, include_subtypes: bool = True, library_elements: syside.query.LibraryElements = LibraryElements.WORKSPACE, index: syside.query.TypeIndex | None = None) → list[syside.query.find_elements_of_type.ElementT]

Deprecated since 1.1 (removed in 2.0): use find_by_type(model, X.STD), which also matches metamodel subtypes that are not Python subclasses (this function misses ConnectionUsage when asked for PartUsage) and takes scope and tiers.

Return every element of type element_type that library_elements covers. With include_subtypes=True (the default) instances of Python subclasses are included. With a TypeIndex this unions the relevant exact-type buckets; without one it is linear in the scanned documents’ size.

find_metadata_usages(scope: syside.Element, *, name: str | None = None, definition: syside.MetadataDefinition | None = None, specializes: syside.Type | None = None, tiers: frozenset[syside.DocumentTier] | None = None, library_elements: syside.query.LibraryElementFilter | syside.query.LibraryElements = LibraryElementFilter.INCLUDE, index: syside.query.MetadataIndex | None = None) → list[syside.MetadataUsage]

Return the metadata usages in scope and below it, optionally only those of one metadata definition.

Given the SysML:

package P {
    metadata def Tag;
    metadata def Sub :> Tag;
    part a { @Tag; }
    part b { @Sub; }
    library package L {
        part c { @Tag; }
    }
}

each call returns the usages listed in its comment:

package = find_by_qualified_name(model, "P")
tag = find_by_qualified_name(model, "P::Tag")
part_a = find_by_qualified_name(model, "P::a")

find_metadata_usages(package)                    # @Tag on a, @Sub on b, @Tag on c
find_metadata_usages(part_a)                     # @Tag on a

find_metadata_usages(package, definition=tag)    # @Tag on a, @Tag on c
find_metadata_usages(package, specializes=tag)   # @Tag on a, @Sub on b, @Tag on c
find_metadata_usages(package, name="Tag")        # @Tag on a, @Tag on c

# A usage inside a library package is a library element; the location
# of its definition does not matter.
find_metadata_usages(
    package, library_elements=LibraryElementFilter.EXCLUDE
)                                                # @Tag on a, @Sub on b

# An index gives the same results faster when the lookup is repeated.
index = build_metadata_index(model)
find_metadata_usages(part_a, index=index)        # @Tag on a

tiers selects documents as in find_by_type(): the result is empty when scope lies in a document outside tiers, and an index must have been built with the same tiers, else ValueError. Without tiers, usages in standard-library documents are left out. This function takes no model, so without tiers it cannot tell an environment document from one the model loaded: a scope inside an environment document is searched without an index and yields nothing with one.

Passing a LibraryElements is deprecated (since 1.1, removed in 2.0): NONE and WORKSPACE leave out standard-library usages, and NONE also library elements. It cannot be combined with tiers or with an index built with tiers= (ValueError), except LibraryElements.ALL with an index built with tiers=ALL_TIERS.

find_relationships(model: syside.Model, relationship_type: tuple[type[syside.query.find_relationships.RelationshipT], ...] | type[syside.query.find_relationships.RelationshipT], *, exclude_subtypes_of: tuple[type[syside.Element], ...] | type[syside.Relationship] | None = None, scope: syside.Element | None = None, tiers: frozenset[syside.DocumentTier] | None = None, library_elements: syside.query.LibraryElementFilter | syside.query.LibraryElements = LibraryElementFilter.INCLUDE, index: syside.query.TypeIndex | None = None) → list[syside.query.find_relationships.RelationshipT]

Return every relationship of relationship_type, less those of exclude_subtypes_of.

Given the SysML:

package R {
    part def A;
    part def B :> A;
    part a : A;
    part b :> a;
}

each call returns the relationships listed in its comment, among them the ones SysML implies to the standard library:

find_relationships(model, syside.Subclassification.STD)
# B :> A, A :> Parts::Part

find_relationships(model, syside.FeatureTyping.STD)
# a : A

find_relationships(model, syside.Specialization.STD)
# B :> A, A :> Parts::Part, b :> a, a :> Parts::parts, a : A

find_relationships(
    model,
    syside.Specialization.STD,
    exclude_subtypes_of=syside.Subsetting.STD,
)
# B :> A, A :> Parts::Part, a : A

Both arguments take X.STD and match X and its metamodel subtypes. scope, tiers, library_elements and index are as in find_by_type(); library_elements is tested against the relationship, not against the elements it relates.

Deprecated (since 1.1, removed in 2.0):

  • A bare class X in either argument. It matches Python instances of X only, which leaves out metamodel subtypes such as Connector for Relationship.

  • A LibraryElements. It keeps its 1.0 document selection, cannot be combined with tiers or scope, and matches both metaclass arguments as Python classes only.

has_metadata_prefix(element: syside.Namespace, prefix_name: str) → bool

Return whether element carries a metadata prefix named prefix_name.

Matches prefix_name against the simple name of each prefix usage’s resolved metadata_definition (its metaclass).

find_connectors_of(model: syside.Model, element: syside.Feature) → list[syside.ConnectorAsUsage]
find_connectors_of(model: syside.Model, element: syside.Feature, *, kind: type[syside.query._ConnectorT]) → list[syside.query._ConnectorT]

Find every connector one of whose ends attaches to element.

Every document of the user model is scanned, so a connector in another document that attaches to element (package B { connect A::x to A::y; } in a second file) is returned. The cost is linear in the model’s size; the result is in model.nodes order. Standard-library connectors are outside the user model and are never returned. Without kind this covers the whole connector family (connect connections, bind bindings, flow transfers, and successions); pass kind to keep one branch of it, e.g. kind=syside.BindingConnectorAsUsage, and the result is typed accordingly. Subtypes of kind are included, so kind=syside.FlowUsage also matches SuccessionFlowUsage; drop them afterwards with an exact type(c) is test if only the base kind is wanted. An end attaches to the feature it references and, when that feature is a chain, to every link of the chain: connect a.pa to b.pb is returned for the parts a/b and for the ports pa/pb alike. This is broader than KerML’s relatedFeature, which names the end features themselves (here the two chains), not their links. Use this for “everything attached to element”; use find_connectors_from() / find_connectors_to() when the source/target split matters: for a flow or succession that split is the model’s direction, and merging the two sides here loses it.

find_connectors_to(model: syside.Model, element: syside.Feature) → list[syside.ConnectorAsUsage]
find_connectors_to(model: syside.Model, element: syside.Feature, *, kind: type[syside.query._ConnectorT]) → list[syside.query._ConnectorT]

Find the connectors with element on their target side.

Every document of the user model is scanned (the same scope as find_connectors_of()), at a cost linear in the model’s size; the result is in model.nodes order. kind restricts the result to one connector kind, subtypes included, as for find_connectors_of(). What the target side means depends on the connector kind: for a flow it is the destination of the payload and for a succession the successor, which is real model semantics. connect connections and bind bindings are not directed, so there to reflects only the order the ends were declared (connect a to b and connect b to a mean the same connection, and bind x = y asserts a symmetric equality). A chained end attaches to every link of its chain (see find_connectors_of()). For every connector touching element regardless of side, use find_connectors_of().

find_connectors_from(model: syside.Model, element: syside.Feature) → list[syside.ConnectorAsUsage]
find_connectors_from(model: syside.Model, element: syside.Feature, *, kind: type[syside.query._ConnectorT]) → list[syside.query._ConnectorT]

Find the connectors with element on their source side.

Every document of the user model is scanned (the same scope as find_connectors_of()), at a cost linear in the model’s size; the result is in model.nodes order. kind restricts the result to one connector kind, subtypes included, as for find_connectors_of(). What the source side means depends on the connector kind: the origin of a flow’s payload, a succession’s predecessor, or (for connect connections and bind bindings, which are not directed) merely the first-declared end; see find_connectors_to() for the same caveat and find_connectors_of() for the side-independent set. A chained end attaches to every link of its chain (see find_connectors_of()).

inherited_features(type_: syside.Type) → list[syside.Feature]

Return the core Type.inherited_features view, linear in its size.

Not a subset of features_of(): this view lists what the supertypes contribute regardless of visibility in type_, so it still contains every feature that one of type_’s own features redefines – which features_of(), listing visible members, correctly omits. To enumerate the visible non-owned features, subtract type_’s own features from features_of() instead of calling this.

is_contained_in(element: syside.Element, container: syside.Element) → bool

Return whether element is nested anywhere inside container.

True when container is element’s owner, its owner’s owner, and so on, i.e. element appears (at any depth) within container’s braces.

metadata_prefixes(element: syside.Namespace) → list[syside.MetadataUsage]

Return element’s prefix metadata usages (the #Name prefixes), linear in the number of prefixes.

The core prefixes view yields (membership, feature) pairs; only syside.MetadataUsage features are returned.

metadata_usages(element: syside.Element) → list[syside.MetadataUsage]

Return all metadata usages owned by element (prefix and body), linear in the number of metadata usages.

Reads the core metadata view and keeps the syside.MetadataUsage entries.

multiplicity_bounds(feature: syside.Feature) → syside.query.MultiplicityBounds | None

Return the multiplicity bounds feature itself declares, or None.

Declared only, no resolution: None means feature declares no multiplicity (or declares one whose bounds are not available), not that the effective multiplicity is absent. In SysML a feature with no declared multiplicity may default to 1..1 (see implicit_multiplicity_bounds()), and one that subsets or redefines another is constrained by that feature’s multiplicity; neither is applied here, so always branch on None before reading .lower/.upper. Both returned bounds are inclusive (an unbounded * upper bound is UNBOUNDED).

implicit_multiplicity_bounds(usage: syside.Usage) → syside.query.MultiplicityBounds | None

Return 1..1 if SysML implicitly declares that multiplicity for usage, else None.

Given the SysML:

package P {
    part def A {
        part x;
        attribute n;
        part y [0..2];
        part z :> x;
    }
    part top;
}

each call returns the value in its comment:

x, n, y, z, top = (
    find_by_qualified_name(model, f"P::{name}")
    for name in ("A::x", "A::n", "A::y", "A::z", "top")
)

implicit_multiplicity_bounds(x)    # MultiplicityBounds(lower=1, upper=1)
implicit_multiplicity_bounds(n)    # MultiplicityBounds(lower=1, upper=1)
implicit_multiplicity_bounds(y)    # None: y declares [0..2]
implicit_multiplicity_bounds(z)    # None: z subsets x
implicit_multiplicity_bounds(top)  # None: a package owns top

SysML 2.0 7.6.3 implicitly declares [1..1] for a usage that declares no multiplicity when all of the following hold:

  1. usage is an attribute, item (including part, but not connection), or port usage.

  2. usage is owned by a definition or another usage (not a package).

  3. usage has no explicit owned subsettings or owned redefinitions. Implied ones (such as the subsetting of Parts::parts every part usage has) do not count, and a typing : T is not a subsetting.

None does not mean 0..*: a usage the rule does not cover inherits the multiplicity constraints of the usages it subsets or redefines, which this function does not resolve. Read a declared multiplicity with multiplicity_bounds().

Cost: linear in the number of usage’s owned specializations.

generalization_names(type_: syside.Type) → list[str]

Return the rendered qualified names of the direct heritage targets.

A target with no qualified name is skipped.

find_redefining_features(model: syside.Model, feature: syside.Feature) → list[syside.Feature]

Return the features that redefine feature (inverse of redefinition).

Linear in the model’s relationship count.

redefined_by(model: syside.Model, feature: syside.Feature) → list[syside.Feature]

Deprecated since 1.1 (removed in 2.0): use find_redefining_features(), the same function, renamed to mark that it scans the model. Returns find_redefining_features(model, feature).

redefines(feature: syside.Feature) → list[syside.Feature]

Return the features feature redefines (via redefinition), linear in the number of redefined features.

referenced_feature(expression: syside.FeatureReferenceExpression) → syside.Feature

Return the feature referenced by expression.

Raises ValueError if the reference is unresolved (the core referent is None), so the return type is a non-optional syside.Feature.

siblings(element: syside.Element) → list[syside.Element]

Return the other direct contents of element’s owner.

element itself is excluded. An element with no owner has no siblings.

specializes(type_: syside.Type, candidate_supertype: syside.Type) → bool

Return whether type_ specializes candidate_supertype, directly or indirectly.

Given the SysML:

package P {
    part def A;
    part def B :> A;
    part def C :> B;
    part a : A;
    part b :> a;
    port def PD;
    part def Q {
        port cp : ~PD;
    }
}

each call returns the value in its comment:

A, C, a, b, PD, cp = (
    find_by_qualified_name(model, f"P::{name}")
    for name in ("A", "C", "a", "b", "PD", "Q::cp")
)

specializes(C, A)    # True, through B
specializes(A, C)    # False
specializes(a, A)    # True, by typing
specializes(b, A)    # True, by subsetting a
specializes(cp, PD)  # True, through the conjugation ~PD
specializes(A, A)    # False

The result equals candidate_supertype in supertypes(type_). Conjugation is crossed as in KerML Type::specializes() (KerML 1.1 8.3.3.1.10), although cp’s PD features run in the opposite direction; to ignore conjugations, test membership in get_specialized_elements(type_, transitive=True, exclude=syside.Conjugation). Unlike Type::specializes(), a type does not specialize itself here.

superclassifiers(type_: syside.Type) → list[syside.Classifier]

Return the classifiers type_ directly subclassifies (KerML superclassifiers), linear in their number.

Given the SysML:

package P {
    part def A;
    part def B :> A;
    part def C :> B;
    part a : A;
}

each call returns the list in its comment:

A, B, C, a = (
    find_by_qualified_name(model, f"P::{name}") for name in ("A", "B", "C", "a")
)

superclassifiers(C)  # [P::B]
superclassifiers(B)  # [P::A]
superclassifiers(A)  # [Parts::Part], the subclassification SysML implies
superclassifiers(a)  # []: only a classifier subclassifies

For the declared ones alone, keep the type_.owned_subclassifications whose is_implied is false. For a usage see subsets(), redefines() and declared_types_of(); supertypes() returns everything inherited from, directly or indirectly, through every kind of specialization.

subject_of(element: syside.query._CaseLike) → syside.Usage | None

Return the subject parameter in effect for element, constant time.

Reads the core subject_parameter accessor, present on requirement and case usages/definitions (and their subtypes). SysML gives these types exactly one subject, inherited when not declared (the SysML derive...SubjectParameter constraints of requirement and case definitions and usages all read the KerML featureMembership, which includes inherited memberships): an element with no subject of its own yields the inherited standard-library parameter (e.g. Requirements::RequirementCheck::subj), not None. To ask whether element declares a subject itself, use declared_subject_of(). None is only the core accessor’s miss case and does not occur for a well-formed model.

declared_subject_of(element: syside.query._CaseLike) → syside.Usage | None

Return the subject element declares itself, or None, constant time.

None means element writes no subject in its own body, so its effective subject is inherited (see subject_of(), which returns that inherited parameter). A declared subject is also the effective one, since SysML has it redefine every inherited subject parameter.

subsets(feature: syside.Feature) → list[syside.Feature]

Return the features feature subsets, linear in the number of subsetted features.

Follows subsetting heritage including its subtypes: KerML defines redefinition as a kind of subsetting, so a redefined feature appears here as well as in redefines(); unioning the two counts the redefined feature twice.

find_subclassifiers(model: syside.Model, type_: syside.Type) → list[syside.Classifier]

Return the classifiers that directly subclassify type_ (KerML subclassifiers).

The inverse of subclassification only (the inverse counterpart of superclassifiers(), not of supertypes()): a feature that subsets, redefines, or is typed by type_ is not returned.

Linear in the model’s relationship count.

specializations(model: syside.Model, target: syside.Element, *, via: type[syside.Specialization] | type[syside.Conjugation] | None = None) → list[syside.Element]

Deprecated since 1.1 (removed in 2.0): use find_specializing_elements(), the same function, renamed to mark that it scans the model. Returns find_specializing_elements(model, target, via=via).

subclassifiers(model: syside.Model, type_: syside.Type) → list[syside.Classifier]

Deprecated since 1.1 (removed in 2.0): use find_subclassifiers(), the same function, renamed to mark that it scans the model. Returns find_subclassifiers(model, type_).

supertypes(type_: syside.Type) → list[syside.Type]

Return every type type_ inherits from, directly or indirectly, nearest first.

Given the SysML:

package P {
    part def Vehicle;
    part def Car :> Vehicle;
    part car : Car;
    port def PD;
    part def Q {
        port cp : ~PD;
    }
}

each call returns the value in its comment:

Car, car, PD, cp = (
    find_by_qualified_name(model, f"P::{name}")
    for name in ("Car", "car", "PD", "Q::cp")
)

supertypes(Car)
# [P::Vehicle, Parts::Part, Items::Item, Objects::Object,
#  Occurrences::Occurrence, Base::Anything]

# Every kind of specialization is followed: here the typing by Car and
# the subsetting of Parts::parts that SysML implies for a part usage.
supertypes(car)
# [P::Car, Parts::parts, P::Vehicle, Parts::Part, Items::items,
#  Items::Item, ..., Base::things, Base::Anything]

# Conjugation is crossed.
PD in supertypes(cp)  # True

Each type appears once, in the order the walk first reaches it: the direct ones, then theirs, and so on. type_ itself is not included.

Differences from KerML: Type::allSupertypes() includes the type itself, and Type::supertypes() returns only the original type for a conjugated type, where this function also follows the conjugated type’s own specializations.

superclassifiers() follows one step of subclassification alone. get_specialized_elements() follows one kind with via= and stops at conjugations with exclude=syside.Conjugation.

textual_representation(element: syside.Namespace, language: str) → str | None

Return the body of element’s textual representation in language.

Matches language case-insensitively (KerML defines language names as case-insensitive). Returns the body of the first matching representation, or None if none matches. Linear in the number of owned textual representations.

variants(variation: syside.Definition | syside.Usage) → list[syside.Element]

Return the variant usages of a variation variation, linear in the number of variants.

Both syside.Usage and syside.Definition expose a variants accessor.

find_specializing_elements(model: syside.Model, target: syside.Element, *, via: type[syside.Specialization] | type[syside.Conjugation] | None = None) → list[syside.Element]

Return the elements that directly specialize target: the inverse of one step of get_specialized_elements().

Given the SysML:

package P {
    part def A;
    part def B :> A;
    part def C :> B;
    part a : A;
    part b :> a;
}

each call returns the list in its comment:

A, C, a = (
    find_by_qualified_name(model, f"P::{name}") for name in ("A", "C", "a")
)

find_specializing_elements(model, A)  # [P::B, P::a]
find_specializing_elements(
    model, A, via=syside.Subclassification
)                                     # [P::B]
find_specializing_elements(
    model, A, via=syside.FeatureTyping
)                                     # [P::a]
find_specializing_elements(model, a)  # [P::b]
find_specializing_elements(model, C)  # []

via filters by relationship type exactly as in get_specialized_elements() (subtypes included; None accepts every kind).

Cost and scope: linear in the model’s relationship count. Every document the model itself loaded is searched, so a subtype declared in another document is found; standard-library documents are not searched. Elements are matched by identity, not by name. Each result appears once, in scan order, and target itself is never included.

generalizations(element: syside.Type, *, via: type[syside.Specialization] | type[syside.Conjugation] | None = None, exclude: type[syside.Specialization] | type[syside.Conjugation] | None = None, transitive: bool = False) → list[syside.Element]

Deprecated since 1.1 (removed in 2.0): use get_specialized_elements(), the same function, renamed because it returns elements, not Generalization relationships. Returns get_specialized_elements(element, via=via, exclude=exclude, transitive=transitive).

get_specialized_elements(element: syside.Type, *, via: type[syside.Specialization] | type[syside.Conjugation] | None = None, exclude: type[syside.Specialization] | type[syside.Conjugation] | None = None, transitive: bool = False) → list[syside.Element]

Return the heritage targets declared by element: the elements it specializes.

The heritage of a syside.Type is the set of specialization and conjugation relationships it declares; each one points at a target type (the general of a specialization, the original_type of a conjugation). This returns those targets. KerML does not count a conjugation as a specialization; its original type is returned too because the conjugated type inherits from it.

via filters to relationships that are instances of the given relationship type, e.g. syside.FeatureTyping, syside.Subsetting, syside.Redefinition, syside.Subclassification or syside.CrossSubsetting. Subtypes of the given type are included (e.g. via=syside.Subsetting also matches Redefinition and CrossSubsetting). via=None accepts every heritage kind. Only heritage relationships, meaning subtypes of syside.Specialization or syside.Conjugation, are valid; a non-heritage kind such as syside.Disjoining is a static type error (it never appears in heritage, so it could only ever yield []).

exclude is the complement of via: relationships that are instances of the given type (and its subtypes) are skipped. A transitive walk does not cross an excluded relationship, so the result is the closure reachable without that heritage kind. For example, exclude=syside.ReferenceSubsetting follows every other specialization (including plain syside.Subsetting, of which ReferenceSubsetting is a subtype) but never the reference-subsetting edge a connector introduces. That is the basis for asking what types a feature has independently of what a connection imposes on it.

``via`` and ``exclude`` are conjunctive (ANDed). A relationship is followed if and only if it satisfies both restrictions: it is an instance of via (or via is None) and it is not an instance of exclude (or exclude is None). Passing the same type to both, or a via that is a subtype of exclude, therefore matches nothing and yields [].

With transitive=False (the default) only the direct targets are returned. With transitive=True the chain is followed to its closure: each target’s own heritage targets are added, transitively. The via and exclude filters apply at every step of a transitive walk.

Results are de-duplicated by object identity and returned in first-seen order; element itself is never included. Cyclic heritage (which a malformed model can contain) terminates rather than looping forever.

element is a syside.Type: only types declare heritage. This is linear in the number of heritage relationships visited (the direct count, or the reachable closure when transitive is set), each step constant time.

walk_containment(element: syside.Element, *, direction: Literal[up, down], max_depth: int | None = None) → Iterator[syside.Element]

Walk the ownership tree from element, yielding the elements reached.

With direction="up" the walk follows the owner chain: it yields element’s owner, then that owner’s owner, and so on up to the root namespace. With direction="down" it traverses owned_elements breadth-first: first the direct contents, then their contents, and so on. In neither direction is element itself yielded.

max_depth bounds the walk. max_depth=1 yields only the elements one step away (the owner, or the direct contents); max_depth=None (the default) is unbounded. max_depth=0 yields nothing. A negative max_depth is treated as 0.

The downward walk de-duplicates by object identity and is cycle-safe: a well-formed ownership tree is acyclic, but a malformed model is still guaranteed to terminate and to yield each element at most once. The upward walk likewise stops if the owner chain ever revisits an element.

Downward traversal drains each owned_elements LazyIterator with a single .collect() (linear per node), never per-element Python iteration over the live iterator.

Enumerations

class LibraryElementFilter

Whether a lookup returns elements that have is_library_element set.

Independent of which documents are scanned (tiers): a library package declared in the user’s own file lies in a DocumentTier.Project document, and it and its contents are library elements; every element of a DocumentTier.StandardLibrary document is one too.

  • INCLUDE (the default) – library elements are returned like any other.

  • EXCLUDE – every element with is_library_element set is dropped.

The filter is applied when a lookup runs, never when an index is built, so one index serves both values.

Whether a lookup returns elements that have is_library_element set.

Independent of which documents are scanned (tiers): a library package declared in the user’s own file lies in a DocumentTier.Project document, and it and its contents are library elements; every element of a DocumentTier.StandardLibrary document is one too.

  • INCLUDE (the default) – library elements are returned like any other.

  • EXCLUDE – every element with is_library_element set is dropped.

The filter is applied when a lookup runs, never when an index is built, so one index serves both values.

Whether a lookup returns elements that have is_library_element set.

Independent of which documents are scanned (tiers): a library package declared in the user’s own file lies in a DocumentTier.Project document, and it and its contents are library elements; every element of a DocumentTier.StandardLibrary document is one too.

  • INCLUDE (the default) – library elements are returned like any other.

  • EXCLUDE – every element with is_library_element set is dropped.

The filter is applied when a lookup runs, never when an index is built, so one index serves both values.

class LibraryElements

Which documents, and which library elements within them, the find_* lookups that take it and the index builders cover (the lookups are listed in the syside.query._functions module docstring).

  • NONE – the documents WORKSPACE scans (environment documents are not scanned, exactly as under WORKSPACE, with the same find_metadata_usages() exception), minus every element with is_library_element set, including the workspace’s own library package namespaces and their contents – a library package is itself a library element.

  • WORKSPACE (the default everywhere) – every document the model itself loaded (model.documents), including its own library package namespaces. Documents supplied through the model’s environment are not scanned: the SysML/KerML standard libraries, and any third-party documents added to the environment (e.g. via Model.to_environment) alike. Environment membership is the discriminator, not DocumentTier – with one exception: find_metadata_usages() walks containment from a scope element and has no model to consult, so it can only recognise the standard library by DocumentTier.StandardLibrary; see its docstring.

  • ALL – workspace and every environment document both.

The value is tested against each element a lookup finds or a builder indexes, never against the elements it reaches through references (see the syside.query._functions module docstring). A lookup and the index backing it must use the same value; a mismatch is a caller error (see the module docstring’s contract).

Which documents, and which library elements within them, the find_* lookups that take it and the index builders cover (the lookups are listed in the syside.query._functions module docstring).

  • NONE – the documents WORKSPACE scans (environment documents are not scanned, exactly as under WORKSPACE, with the same find_metadata_usages() exception), minus every element with is_library_element set, including the workspace’s own library package namespaces and their contents – a library package is itself a library element.

  • WORKSPACE (the default everywhere) – every document the model itself loaded (model.documents), including its own library package namespaces. Documents supplied through the model’s environment are not scanned: the SysML/KerML standard libraries, and any third-party documents added to the environment (e.g. via Model.to_environment) alike. Environment membership is the discriminator, not DocumentTier – with one exception: find_metadata_usages() walks containment from a scope element and has no model to consult, so it can only recognise the standard library by DocumentTier.StandardLibrary; see its docstring.

  • ALL – workspace and every environment document both.

The value is tested against each element a lookup finds or a builder indexes, never against the elements it reaches through references (see the syside.query._functions module docstring). A lookup and the index backing it must use the same value; a mismatch is a caller error (see the module docstring’s contract).

Which documents, and which library elements within them, the find_* lookups that take it and the index builders cover (the lookups are listed in the syside.query._functions module docstring).

  • NONE – the documents WORKSPACE scans (environment documents are not scanned, exactly as under WORKSPACE, with the same find_metadata_usages() exception), minus every element with is_library_element set, including the workspace’s own library package namespaces and their contents – a library package is itself a library element.

  • WORKSPACE (the default everywhere) – every document the model itself loaded (model.documents), including its own library package namespaces. Documents supplied through the model’s environment are not scanned: the SysML/KerML standard libraries, and any third-party documents added to the environment (e.g. via Model.to_environment) alike. Environment membership is the discriminator, not DocumentTier – with one exception: find_metadata_usages() walks containment from a scope element and has no model to consult, so it can only recognise the standard library by DocumentTier.StandardLibrary; see its docstring.

  • ALL – workspace and every environment document both.

The value is tested against each element a lookup finds or a builder indexes, never against the elements it reaches through references (see the syside.query._functions module docstring). A lookup and the index backing it must use the same value; a mismatch is a caller error (see the module docstring’s contract).

Which documents, and which library elements within them, the find_* lookups that take it and the index builders cover (the lookups are listed in the syside.query._functions module docstring).

  • NONE – the documents WORKSPACE scans (environment documents are not scanned, exactly as under WORKSPACE, with the same find_metadata_usages() exception), minus every element with is_library_element set, including the workspace’s own library package namespaces and their contents – a library package is itself a library element.

  • WORKSPACE (the default everywhere) – every document the model itself loaded (model.documents), including its own library package namespaces. Documents supplied through the model’s environment are not scanned: the SysML/KerML standard libraries, and any third-party documents added to the environment (e.g. via Model.to_environment) alike. Environment membership is the discriminator, not DocumentTier – with one exception: find_metadata_usages() walks containment from a scope element and has no model to consult, so it can only recognise the standard library by DocumentTier.StandardLibrary; see its docstring.

  • ALL – workspace and every environment document both.

The value is tested against each element a lookup finds or a builder indexes, never against the elements it reaches through references (see the syside.query._functions module docstring). A lookup and the index backing it must use the same value; a mismatch is a caller error (see the module docstring’s contract).

Used by: