capellambse package

The capellambse package.

capellambse.load_model_extensions()

Load all model extensions.

This function loads all entry points in the group capellambse.model_extensions and executes them.

It is automatically called when loading a model. Calling it more than once has no effect, so it is safe (although not necessary) to explicitly call this function before loading a model.

Return type:

None

Subpackages

Submodules

capellambse.cli_helpers module

Helpers for working with models in CLI scripts.

class capellambse.cli_helpers.ModelCLI

Bases: ParamType

Declare an option that loads a model.

Use instances of this class for the type argument to click.option() etc.

See also

capellambse.cli_helpers.loadcli

A standalone function performing the same task.

Examples

@click.command()
@click.option("-m", "--model", type=capellambse.ModelCLI())
def main(model: capellambse.MelodyModel) -> None:
    ...
convert(value, param, ctx)

Convert the value to the target type.

Return type:

MelodyModel

Parameters:

value (Any)

name: str = 'CAPELLA_MODEL'

the descriptive name of this type

class capellambse.cli_helpers.ModelInfoCLI

Bases: ParamType

Declare an option that loads information about a model.

Use instances of this class for the type argument to click.option() etc.

See also

capellambse.cli_helpers.loadinfo

A standalone function performing the same task.

Examples

@click.command()
@click.open("-m", "modelinfo", type=capellambse.ModelInfoCLI())
def main(modelinfo: dict[str, t.Any]) -> None:
    # change any options, for example:
    modelinfo["diagram_cache"] = "/tmp/diagrams"
    model = capellambse.MelodyModel(**modelinfo)
convert(value, param, ctx)

Convert the value to the target type.

Return type:

dict[str, Any]

Parameters:

value (Any)

name: str = 'CAPELLA_MODEL'

the descriptive name of this type

capellambse.cli_helpers.enumerate_known_models()

Enumerate the models that are found in the known_models folders.

Two places are searched for models: The known_models folder in the user’s configuration directory, and the known_models folder in the installed capellambse package.

Run the following command to print the location of the user’s known_models folder:

python -m capellambse.cli_helpers

In order to make a custom model known, place a JSON file in one of these known_models folders. It should contain a dictionary with the keyword arguments to MelodyModel - specifically it needs a path, optionally an entrypoint, and any additional arguments that the underlying FileHandler might need to gain access to the model.

Files in the user’s configuration directory take precedence over files in the package directory. If a file with the same name exists in both places, the one in the user’s configuration directory will be used.

Be aware that relative paths in the JSON will be interpreted relative to the current working directory.

Return type:

Iterator[Traversable]

capellambse.cli_helpers.loadcli(value)

Load a model from a file or JSON string.

This function works like loadinfo(), and also loads the model for convenience.

Parameters:

value (str | PathLike[str]) – As described for loadinfo().

Returns:

The loaded model, as described by the value.

Return type:

MelodyModel

Examples

def main():
    model = capellambse.loadcli(sys.argv[1])
capellambse.cli_helpers.loadinfo(value)

Load information about how to load a model as dict.

Parameters:

value (str | PathLike[str]) –

One of the following:

  • A str or PathLike pointing to an .aird file

  • A str or PathLike pointing to a .json file, which contains the arguments to instantiate a MelodyModel

  • The contents of such a JSON file (as string)

Returns:

A dict with information about how to load a MelodyModel.

Return type:

dict[str, Any]

Raises:

  • TypeError – If the value cannot be parsed as described above.

  • ValueError – If the value looks like a “known model” name, but the name is not defined.

Examples

def main():
    modelinfo = capellambse.loadinfo(sys.argv[1])
    # change any options, for example:
    modelinfo["diagram_cache"] = "/tmp/diagrams"
    model = MelodyModel(**modelinfo)

capellambse.decl module

Support for YAML-based declarative modelling.

A YAML-based approach to describing how to create and modify capellambse compatible models.

For an in-depth explanation, please refer to the full documentation about declarative modelling.

class capellambse.decl.FindBy

Bases: object

Find an object by specific attributes.

__init__(attributes)
Parameters:

attributes (Mapping[str, Any])

Return type:

None

attributes: Mapping[str, Any]
class capellambse.decl.Metadata

Bases: TypedDict

model: ModelMetadata
written_by: WriterMetadata
class capellambse.decl.ModelMetadata

Bases: TypedDict

entrypoint: str
revision: NotRequired[str]
url: str
class capellambse.decl.Promise

Bases: object

References a model object that will be created later.

__init__(identifier)
Parameters:

identifier (str)

Return type:

None

identifier: str
class capellambse.decl.UUIDReference

Bases: object

References a model object by its UUID.

__init__(uuid)
Parameters:

uuid (UUIDString)

Return type:

None

uuid: NewType(UUIDString, str)
exception capellambse.decl.UnfulfilledPromisesError

Bases: RuntimeError

A promise could not be fulfilled.

This exception is raised when a promise is referenced via !promise, but it is never fulfilled by declaring an object with the same promise_id.

class capellambse.decl.WriterMetadata

Bases: TypedDict

capellambse: str
generator: NotRequired[str]
class capellambse.decl.YDMDumper

Bases: SafeDumper

A YAML dumper with extensions for declarative modelling.

represent_findby(data)
Return type:

Node

Parameters:

data (Any)

represent_markup(data)
Return type:

Node

Parameters:

data (Any)

represent_newobj(data)
Return type:

Node

Parameters:

data (Any)

represent_promise(data)
Return type:

Node

Parameters:

data (Any)

represent_uuidref(data)
Return type:

Node

Parameters:

data (Any)

yaml_representers = {<class 'NoneType'>: <function SafeRepresenter.represent_none>, <class 'bool'>: <function SafeRepresenter.represent_bool>, <class 'bytes'>: <function SafeRepresenter.represent_binary>, <class 'capellambse.decl.FindBy'>: <function YDMDumper.represent_findby>, <class 'capellambse.decl.Promise'>: <function YDMDumper.represent_promise>, <class 'capellambse.decl.UUIDReference'>: <function YDMDumper.represent_uuidref>, <class 'capellambse.model._descriptors.NewObject'>: <function YDMDumper.represent_newobj>, <class 'datetime.date'>: <function SafeRepresenter.represent_date>, <class 'datetime.datetime'>: <function SafeRepresenter.represent_datetime>, <class 'dict'>: <function SafeRepresenter.represent_dict>, <class 'float'>: <function SafeRepresenter.represent_float>, <class 'int'>: <function SafeRepresenter.represent_int>, <class 'list'>: <function SafeRepresenter.represent_list>, <class 'markupsafe.Markup'>: <function YDMDumper.represent_markup>, <class 'set'>: <function SafeRepresenter.represent_set>, <class 'str'>: <function SafeRepresenter.represent_str>, <class 'tuple'>: <function SafeRepresenter.represent_list>, None: <function SafeRepresenter.represent_undefined>}
class capellambse.decl.YDMLoader

Bases: SafeLoader

A YAML loader with extensions for declarative modelling.

construct_findby(node)
Return type:

FindBy

Parameters:

node (Node)

construct_markup(node)
Return type:

Markup

Parameters:

node (Node)

construct_newobj(node)
Return type:

NewObject

Parameters:

node (Node)

construct_promise(node)
Return type:

Promise

Parameters:

node (Node)

construct_uuidref(node)
Return type:

UUIDReference

Parameters:

node (Node)

yaml_constructors = {'!find': <function YDMLoader.construct_findby>, '!html': <function YDMLoader.construct_markup>, '!new_object': <function YDMLoader.construct_newobj>, '!promise': <function YDMLoader.construct_promise>, '!uuid': <function YDMLoader.construct_uuidref>, 'tag:yaml.org,2002:binary': <function SafeConstructor.construct_yaml_binary>, 'tag:yaml.org,2002:bool': <function SafeConstructor.construct_yaml_bool>, 'tag:yaml.org,2002:float': <function SafeConstructor.construct_yaml_float>, 'tag:yaml.org,2002:int': <function SafeConstructor.construct_yaml_int>, 'tag:yaml.org,2002:map': <function SafeConstructor.construct_yaml_map>, 'tag:yaml.org,2002:null': <function SafeConstructor.construct_yaml_null>, 'tag:yaml.org,2002:omap': <function SafeConstructor.construct_yaml_omap>, 'tag:yaml.org,2002:pairs': <function SafeConstructor.construct_yaml_pairs>, 'tag:yaml.org,2002:seq': <function SafeConstructor.construct_yaml_seq>, 'tag:yaml.org,2002:set': <function SafeConstructor.construct_yaml_set>, 'tag:yaml.org,2002:str': <function SafeConstructor.construct_yaml_str>, 'tag:yaml.org,2002:timestamp': <function SafeConstructor.construct_yaml_timestamp>, None: <function SafeConstructor.construct_undefined>}
capellambse.decl.apply(model, file, *, strict=False)

Apply a declarative modelling file to the given model.

Parameters:

  • model (MelodyModel) – The model to apply the instructions to.

  • file (Union[str, PathLike[Any], IO[str]]) –

    An open file-like object to read YAML instructions from, or a path to such a file. Files will be read with UTF-8 encoding.

    The full format of these files is documented in the section about declarative modelling.

  • strict (bool) – Verify metadata contained in the file against the used model, and raise an error if they don’t match.

Return type:

dict[Promise, ModelObject]

Notes

This function is not transactional: If an exception occurs during this function, the model will be left partially modified, with no reliable way to know how much of the YAML input has been consumed. It is therefore advised to reload or discard the model immediately in these cases, to avoid working with an inconsistent state.

Even though the YAML layout suggests linear execution from top to bottom, the actual order in which modifications are executed is implementation defined. This is necessary to support promises with !promise, but reorderings are still possible even if no promises are used in an input document.

capellambse.decl.dump(instructions, *, metadata=None, generator=None)

Dump an instruction stream to YAML.

Optionally dump metadata with the instruction stream to YAML.

Return type:

str

Parameters:
capellambse.decl.load(file)

Load an instruction stream from a YAML file.

Parameters:

file (Union[str, PathLike[Any], IO[str]]) – An open file-like object containing decl instructions, or a path or PathLike pointing to such a file. Files are expected to use UTF-8 encoding.

Return type:

list[dict[str, Any]]

capellambse.decl.load_with_metadata(file)

Load an instruction stream and its metadata from a YAML file.

If the file does not have a metadata section, an empty dict will be returned.

Parameters:

file (Union[str, PathLike[Any], IO[str]]) – An open file-like object containing decl instructions, or a path or PathLike pointing to such a file. Files are expected to use UTF-8 encoding.

Return type:

tuple[Metadata, list[dict[str, Any]]]

Returns:

  • dict[str, Any] – The metadata read from the file, or an empty dictionary if the file did not contain any metadata.

  • list[dict[str, Any]] – The instruction stream.

capellambse.diagram_cache module

CLI for the diagram cache updating feature.

capellambse.helpers module

Miscellaneous utility functions used throughout the modules.

class capellambse.helpers.EverythingContainer

Bases: Container[Any]

A container that contains everything.

class capellambse.helpers.UUIDString

A string that represents a unique ID within the model.

alias of str

capellambse.helpers.deterministic_ids(*, seed=None)

Enter a context during which generated IDs are deterministic.

This function is primarily intended for testing.

It can be used as a context manager, where deterministic IDs will be generated until the context ends:

Return type:

Iterator[None]

Parameters:

seed (Any)

>>> with deterministic_ids():
...     print(generate_id())
...     print(generate_id())
...
cd072cd8-be6f-4f62-ac4c-09c28206e7e3
5594aa6b-342f-4d0a-ba5e-4842fab428f7
>>> with deterministic_ids():
...     print(generate_id())
...     print(generate_id())
...
cd072cd8-be6f-4f62-ac4c-09c28206e7e3
5594aa6b-342f-4d0a-ba5e-4842fab428f7

It can also be used to annotate a function, in which case deterministic IDs will be generated while that function is being called:

>>> @deterministic_ids()
... def print_the_same_ids():
...     print(generate_id())
...     print(generate_id())
...
>>> print_the_same_ids()
cd072cd8-be6f-4f62-ac4c-09c28206e7e3
5594aa6b-342f-4d0a-ba5e-4842fab428f7
>>> print_the_same_ids()
cd072cd8-be6f-4f62-ac4c-09c28206e7e3
5594aa6b-342f-4d0a-ba5e-4842fab428f7

A seed for the PRNG may be passed using the seed keyword argument:

>>> with deterministic_ids(seed=1234):
...     print(generate_id())
...     print(generate_id())
...
b97f69f7-5edf-45c7-9fda-d37066eae91d
14f6ea01-456b-4417-b0b8-35e942f549f1
>>> @deterministic_ids(seed=1234)
... def print_the_same_ids():
...     print(generate_id())
...     print(generate_id())
...
>>> print_the_same_ids()
b97f69f7-5edf-45c7-9fda-d37066eae91d
14f6ea01-456b-4417-b0b8-35e942f549f1
capellambse.helpers.embed_images(markup, /, resources)

Embed images into description text.

This function replaces <img> tags linking to an image file in one of the given resources with a base64-encoded data URI containing the image data directly. The original path is preserved in the data-capella-path attribute. :rtype: Markup

See also

unembed_images

The inverse operation.

Parameters:
Return type:

Markup

capellambse.helpers.escape_linked_text(loader, attr_text)

Transform simple HTML with object links into LinkedText.

This is the inverse operation of unescape_linked_text().

Return type:

str

Parameters:
capellambse.helpers.extent_func(text, fonttype='OpenSans-Regular.ttf', size=10)

Calculate the display size of the given text.

Parameters:

  • text (str) – Text to calculate pixel size on

  • fonttype (str) – The font type / face

  • size (int) – Font size (px)

Return type:

tuple[float, float]

Returns:

  • width – The calculated width of the text (px).

  • height – The calculated height of the text (px).

capellambse.helpers.flatten_html_string(text)

Convert an HTML-string to plain text.

Return type:

str

Parameters:

text (str)

capellambse.helpers.flock(file)
Return type:

Iterator[None]

Parameters:

file (Path)

capellambse.helpers.generate_id()

Generate a new, random ID to be used in the model.

Return type:

str

capellambse.helpers.get_term_cell_size(stream=None)

Get the cell size of the terminal.

Parameters:

stream – The stream that the terminal is connected to. If None, the stderr stream will be probed.

Returns:

The width and height of a cell.

Return type:

tuple[int, int]

Raises:

ValueError – Raised if the cell size could not be determined.

capellambse.helpers.get_text_extent(text, width=inf, fonttype='OpenSans-Regular.ttf', fontsize=10)

Calculate the bounding box size of text after line wrapping.

Parameters:

  • text (str) – Text to calculate the size for.

  • width (float | int) – Maximum line length (px).

  • fonttype (str) – The font type / face

  • fontsize (int) – Font size (px)

Return type:

tuple[float, float]

Returns:

  • width – The width of the text after word wrapping (px).

  • height – The height of the text after word wrapping (px).

capellambse.helpers.get_transformation(class_, pos, size)

Calculate transformation for class.

The Scaling factor .725, translation constants (6, 5) are arbitrarily chosen to fit. Currently only ChoicePseudoState is tranformed.

Parameters:
Return type:

dict[str, str]

capellambse.helpers.is_uuid_string(string)

Validate that string is a valid UUID.

Return type:

TypeGuard[NewType(UUIDString, str)]

Parameters:

string (Any)

capellambse.helpers.load_font(fonttype, size)
Return type:

FreeTypeFont

Parameters:
capellambse.helpers.make_short_html(clsname, uuid, name='', value='', *, icon='', iconsize=None)

Make HTML that briefly describes an element.

The layout of the generated HTML string is:

[icon and/or clsname] [name]: [value] ([uuid])

If an icon is used, the clsname is used for its alt and hover text.

All values passed except for icon will be HTML-escaped.

Parameters:

  • clsname (str) – The name of the object’s class.

  • uuid (str) – The object’s UUID.

  • name (str) – The human-readable name of the object.

  • value (str) – If the object contains a value of some sort, which is more interesting to the end user than the fact that the object exists, this parameter can be used to display the value.

  • icon (str) – The icon to use, encoded as data: URI. Note that this value must already be HTML-safe.

  • iconsize (int | None) – Fix the width and height of the icon to this pixel value. Needed if the client application has dumb CSS rules.

Return type:

Markup

capellambse.helpers.normalize_pure_path(path, *, base='/')

Make a PurePosixPath relative to base and collapse .. components.

Parameters:

  • path (str | PurePosixPath) – The input path to normalize.

  • base (str | PurePosixPath) – The base directory to which relative paths should be interpreted. Ignored if the input path is not relative.

Returns:

The normalized path.

Return type:

pathlib.PurePosixPath

capellambse.helpers.ntuples(num, iterable, *, pad=False)

Yield N items of iterable at once.

Parameters:

  • num (int) – The number of items to yield at once.

  • iterable (Iterable[TypeVar(_T)]) – An iterable.

  • pad (bool) – If the items in iterable are not evenly divisible by n, pad the last yielded tuple with Nones. If False, the last tuple will be discarded.

Yields:

items – A num long tuple of items from iterable.

Return type:

Iterator[tuple[Optional[TypeVar(_T)], ...]]

capellambse.helpers.process_html_fragments(markup, node_callback)

Repair and modify HTML markup.

The original markup, which can be an HTML fragment (without a root element), is parsed and processed, and then reassembled into a Markup instance. If the original markup contained any errors or inconsistencies, these are repaired in the returned Markup instance.

Parameters:

  • markup (str) – The markup string to modify.

  • node_callback (Callable[[_Element], None]) –

    A callback function to process each node in the parsed markup. The function should accept a single lxml.etree._Element as argument; its return value is ignored.

    Note that, since the markup is parsed as fragments, more than the first element passed to the callback may have no parent.

    The callback will not be invoked for leading text, if there is any, and thus it has no ability to influence it.

Returns:

The processed markup.

Return type:

markupsafe.Markup

capellambse.helpers.qtype_of(element)

Get the qualified type of the element.

Return type:

QName | None

Parameters:

element (_Element)

capellambse.helpers.relpath_pure(path, start)

Calculate the relative path between two pure paths.

Unlike pathlib.PurePath.relative_to(), this method can cope with path not being a subpath of start. And unlike the os.path.relpath() function, it does not involve any filesystem access.

Return type:

PurePosixPath

Parameters:
capellambse.helpers.repair_html(markup)

Try to repair broken HTML markup to prevent parse errors.

Parameters:

markup (str) – The markup to try and repair.

Returns:

The repaired markup.

Return type:

markupsafe.Markup

Replace hlink:// links with arbitrary other links.

Parameters:

  • markup (str) – The markup to process.

  • model (MelodyModel) – The model to use for resolving UUIDs.

  • make_href (Callable[[ModelElement], str | None]) – A function that maps objects to URLs. This function is called once for each link (possibly multiple times for the same object), and must return a URL to be inserted in place of the original hlink://... URL.

  • broken_link_css (str) – Broken links (links to objects that have been deleted, and links where the make_href callback returned None or an empty string) are indicated by a <span> element with this CSS style applied to it.

Return type:

Markup

capellambse.helpers.resolve_namespace(tag)

Resolve a ‘:’-delimited symbolic namespace to its canonical form.

Parameters:

tag (str) – Symbolic namespace delimited by ‘:’.

Returns:

Tag string in canonical form.

Return type:

str

Split a string containing intra- and inter-fragment links.

Intra-fragment links are simply “#UUID”, whereas inter-fragment links look like “xtype fragment#UUID”. Multiple such links are space-separated in a single long string to form a list. This function splits such a string back into its individual components (each being either an intra- or inter-fragment link), and yields them.

Yields:

str – A single link from the list.

Return type:

Iterator[str]

Parameters:

links (str)

capellambse.helpers.ssvparse(string, cast, *, parens=('', ''), sep=',', num=0)

Parse a string of sep-separated values wrapped in parens.

Parameters:

  • string (str) – The input string.

  • cast (Callable[[str], TypeVar(_T)]) – A type to cast the values into.

  • parens (Sequence[str]) – The parentheses that must exist around the input. Either a two-character string or a 2-tuple of strings.

  • sep (str) – The separator between values.

  • num (int) – If non-zero, only accept exactly this many values.

Returns:

A list of values cast into the given type.

Return type:

list[_T]

Raises:

ValueError – If the parentheses are missing around the input string, or if the expected number of values doesn’t match the actual number.

capellambse.helpers.unembed_images(markup, /, resources)

Unembed images from description text.

This function replaces <img> tags containing data URIs with links that can be interpreted by Capella, and writes the image data into files in the provided model’s resources. :rtype: Markup

See also

embed_images

The inverse operation.

Parameters:
Return type:

Markup

capellambse.helpers.unescape_linked_text(loader, attr_text)

Transform the linkedText into regular HTML.

Return type:

Markup

Parameters:
capellambse.helpers.word_wrap(text, width)

Perform word wrapping for proportional fonts.

Whitespace at the beginning of input lines is preserved, but other whitespace is collapsed to single spaces. Words are kept as a whole, possibly leading to exceeding width bound.

Parameters:

  • text (str) – The text to wrap.

  • width (float | int) – The width in pixels to wrap to.

Returns:

A list of strings, one for each line, after wrapping.

Return type:

list[str]

capellambse.helpers.xpath_fetch_unique(xpath, tree, elm_name, elm_uid=None, *, optional=False)

Fetch an XPath result from the tree, ensuring that it’s unique.

Parameters:

  • xpath (str | XPath) – The lxml.etree.XPath object to apply, or an XPath expression as str.

  • tree (_Element) – The (sub-)tree to which the XPath will be applied.

  • elm_name (str) – A human-readable element name for error messages.

  • elm_uid (str | None) – UID of the element which triggered this lookup. Will be included in the error message if an error occured.

  • optional (bool) – True to return None in case the element is not found. Otherwise a ValueError will be raised.

Returns:

The Element found by given xpath.

Return type:

lxml.etree._Element | None

Raises:

ValueError – If more than one element was found matching the xpath, or if optional is False and no matching element was found.

capellambse.helpers.xtype_of(elem)

Return the xsi:type of the element.

If the element has an xsi:type attribute, its value is returned.

If the element does not have an xsi:type, this function resolves the tag’s namespace to the symbolic name and reconstructs the type with the namespace:tag template.

Parameters:

elem (_Element) – The lxml.etree._Element object to return the xsi:type for.

Raises:

  • capellambse.UnsupportedPluginError – If the plugin is unknown and therefore not supported.

  • capellambse.UnsupportedPluginVersionError – If the plugin’s version is not supported.

Returns:

The xsi:type string of the provided element or None if the type could not be determined.

Return type:

str | None