syside.preview

Warning

The features presented in this module are still in active development and may have breaking changes even with minor releases.

Module implementing various proposals for how to make the SysIDE API more convenient and easier to pick up.

Package Contents

Loading

empty_model(*, warnings_as_errors: bool = False, allow_errors: bool = False, include_stdlib: bool = True) → syside.preview.LockedModel

Opens an empty model, loading only standard library elements (unless include_stdlib=False).

unlock the returned model before sharing between threads (and re-lock before use), or use a with-block to automatically unlock when exiting the block.

Parameters:

  • warnings_as_errors – if True, warnings are treated errors

  • allow_errors – if False, tries to return a partial or invalid model even in the presence of errors

  • include_stdlib – if False, tries to load the model without also loading the SysML v2 standard library

Returns:

a LockableModel representing an empty model.

open_model(paths: pathlib.Path | str | Iterable[pathlib.Path | str], *, warnings_as_errors: bool = False, allow_errors: bool = False, include_stdlib: bool = True) → syside.preview.LockedModel

Opens a model stored in paths, which can be given as a (combination of) file and directory paths. By default the model is allowed to generate warnings (warnings_as_errors) but is not allowed to contain errors (allow_errors).

unlock the returned model before sharing between threads (and re-lock before use), or use a with-block to automatically unlock when exiting the block.

Parameters:

  • paths – path or sequence of paths (given as str or Path) of source files, or directories containing source files, to be included in the model

  • warnings_as_errors – if True, warnings are treated errors

  • allow_errors – if False, tries to return a partial or invalid model even in the presence of errors

  • include_stdlib – if False, tries to load the model without also loading the SysML v2 standard library

Returns:

a LockableModel representing the model loaded from source files given in paths

Raises:

syside.ModelError – if model contains errors and allow_errors is False

open_model_unlocked(paths: pathlib.Path | str | Iterable[pathlib.Path | str], *, warnings_as_errors: bool = False, allow_errors: bool = False, include_stdlib: bool = True) → syside.preview.UnlockedModel

Opens a model stored in paths, which can be given as a (combination of) file and directory paths. By default the model is allowed to generate warnings (warnings_as_errors) but is not allowed to contain errors (allow_errors).

lock the returned model before access

Parameters:

  • paths – path or sequence of paths (given as str or Path) of source files, or directories containing source files, to be included in the model

  • warnings_as_errors – if True, warnings are treated errors

  • allow_errors – if False, tries to return a partial or invalid model even in the presence of errors

  • include_stdlib – if False, tries to load the model without also loading the SysML v2 standard library

Returns:

an UnlockedModel representing the model loaded from source files given in paths

Raises:

syside.ModelError – if model contains errors and allow_errors is False

class LockedModel

A SysML v2/KerML model interface. Top level elements (typically Packages) can be accessed through the lookup method, e.g. model.lookup("PackageName"). To create a new top level package use the new_top_level_package method.

The object is invalidated once unlocked, either explicitly or by leaving the outermost with-block when used as a context manager.

Note that LockedModel is generally not intended to be instantiated directly. Ideally, use either open_model or empty_model. Alternatively, instantiate UnlockedModel and use UnlockedModel.lock.

model : LockedModel = empty_model()

## Alternatively
unlocked_model = open_model_unlocked(...)

model : LockedModel = unlocked_model.lock()

Initialization

__enter__() → Self
__exit__(exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: types.TracebackType | None) → bool | None
unlock() → syside.preview.UnlockedModel

Unlocks the model, freeing it up for others to lock.

Returns:

UnlockedModel that can be used to re-acquire access to the model

Raises:

RuntimeError – if used after unlocking

property diagnostics: syside.Diagnostics

Diagnostics generated when the model was loaded.

top_elements() → Iterator[syside.Element]

Yields all top level named elements (typically Packages) that are owned members of a root namespace in the model. Note that imported members are not taken into account.

Returns:

sequence of top level elements

Raises:

RuntimeError – if used after unlocking

top_named_elements() → Iterator[tuple[str, syside.Element]]

Yields all named top level named elements (typically Packages) that are owned members of a root namespace in the model, together with (one of) their names. Note that imported members are not taken into account.

Prefers name over short name.

Returns:

sequence of (name, element) pairs of named top level elements

Raises:

RuntimeError – if used after unlocking

top_names() → Iterator[str]

Yields names of all top level named elements (typically Packages) that are owned members of a root namespace in the model. Note that imported members are not taken into account.

Prefers name over short name.

Returns:

sequence of names of named top level elements

Raises:

RuntimeError – if used after unlocking

lookup(name: str, *path: str) → syside.Element | None

If path is empty, yields the (unique) top-level owned member element with name name if it exists, otherwise returns None. Note that elements other than owned member elements, such as imported or inherited ones, are not taken into account.

Otherwise .lookup(name, name, path1, ..., pathn) is equal to .lookup(name).lookup(path1).[...].lookup(pathn), unless any intermediate value is None. If any intermediate value is None the whole expression evaluates to None.

Parameters:

  • name – name of element to find

  • path – sequence of names to (recursively) lookup

Returns:

(unique) element with name name or None (if not found)

Raises:

  • RuntimeError – if used after unlocking

  • TypeError – if trying to recursively look-up into a non-Namespace element.

  • NameError – if the name is ambiguous.

top_elements_from(path: str | pathlib.Path) → Iterator[syside.Element]

Yields top level owned member elements (typically Packages) loaded from the specified path(or from files below that path if it is a directory). Note that imported members are not taken into account.

Parameters:

path – source file or directory path to return elements loaded from

Returns:

sequence of (top) model elements loaded from source file(s) matching path

Raises:

RuntimeError – if used after unlocking

new_top_level_package(name: str) → syside.Package

Creates a (named) new top level package.

Parameters:

name – name of the new package

Returns:

a new syside.Package named name (in a new global namespace)

Raises:

RuntimeError – if used after unlocking

new_top_level_library_package(name: str) → syside.LibraryPackage

Creates a (named) new top level package.

Parameters:

name – name of the new package

Returns:

a new syside.LibraryPackage named name (in a new global namespace)

Raises:

RuntimeError – if used after unlocking

class UnlockedModel(documents: Iterable[syside.SharedMutex[syside.Document]], diagnostics: syside.Diagnostics)

A SysML v2/KerML model that needs to be locked before access.

Note that UnlockedModel is generally not intended to be instantiated directly. Ideally, use open_model_unlocked or LockedModel.unlock on a previously acquired LockedModel.

model : UnlockedModel = open_model_unlocked("file.sysml")

## Alternatively
locked_model : LockedModel = open_model("file.sysml")
...
model = locked_model.unlock()

Initialization

Parameters:

  • documents – sequence of syside.Documents that constitute the model

  • diagnostics – any diagnostic messages (errors or warnings) concerning the model

lock() → syside.preview.LockedModel

Locks the model, allowing access.

Returns:

a LockedModel that allows access to model elements.

Building

new_package(owner: syside.Namespace, name: Optional[str] = None, short_name: Optional[str] = None, *, visibility: Optional[Literal[private, protected, public] | syside.VisibilityKind] = None) → syside.Package

Adds a new package (Section 7.5)

new_library_package(owner: syside.Namespace, name: Optional[str] = None, short_name: Optional[str] = None, *, visibility: Optional[Literal[private, protected, public] | syside.VisibilityKind] = None) → syside.LibraryPackage

Adds a new package (Section 7.5)