Specifying models

py-capellambse and tools using it generally support multiple ways of specifying a model to load and use. Which way to use depends on the specific situation. This page lists all the ways that are commonly supported.

Simple paths

A model can be specified by the path to its main *.aird file.

/home/username/models/coffee-machine/coffee-machine.aird
C:\Capella\workspace\coffee-machine\coffee-machine.aird
./model/model.aird
model.aird

This is equivalent to specifying the path and entrypoint arguments to the MelodyModel constructor, e.g.:

model = capellambse.MelodyModel(
    path="/home/username/models/coffee-machine",
    entrypoint="coffee-machine.aird",
)

Just like how the entrypoint argument is optional if there is only one *.aird file in the given path, the file name here may be omitted in this case as well:

/home/username/models/coffee-machine/
C:\Capella\workspace\coffee-machine
./model
.

Make sure to escape any special characters such as whitespace or backslashes when specifying paths on the command line.

Remote URLs

Models can also be loaded from various remote locations by specifying a URL in the form of protocol://host.name/path/to/model.aird. Out of the box, py-capellambse supports the following protocols:

Click on a protocol to get to the detailed documentation including supported additional arguments, which can be passed in using JSON (see below).

JSON

For more complex cases, like remote models that require credentials, it is possible to pass a JSON-encoded dictionary. This dictionary can contain any key that the MelodyModel constructor and the underlying FileHandler understands.

Note that, when passing such JSON as command line argument, it is necessary to escape the whole JSON string to prevent the Shell from interpreting it, removing quotes, replacing variables, etc. In bash-like shells, this is usually accomplished by wrapping it in single quotes, like this:

python -m capellambse.repl '{"path": "git@example.com:demo-model.git", "revision": "dev", ...}'

Known models

A model can be given a short name by placing a JSON file in the user’s ‘known_models’ folder. This is the exact same JSON as described above, just put into a file instead of passed as string.

Run the following command to find out where to put the files:

python -m capellambse.cli_helpers

This will show the folder for custom ‘known_models’ files, and list the names of all files found in either the custom or built-in folder. These names can then be passed to any CLI command in place of the full model definition.

For example, to start a capellambse REPL using the built-in “coffee-machine” model definition, you can run:

python -m capellambse.repl coffee-machine

The most common keys to use include path and entrypoint, as well as credential-related keys like username, password or identity_file. Refer to the documentation of MelodyModel, as well as the respective FileHandler class you want to use for more details:

CLI support

In order to make it easy to support model loading from the CLI, py-capellambse exposes a few functions and classes in the capellambse.cli_helpers module.

Standalone functions

These functions help with loading a model from arbitrary user-supplied strings, such as command line arguments.

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.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.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]

Click parameter types

There are also Click parameter types available that encapsulate the loadinfo and loadcli functions, respectively:

class capellambse.cli_helpers.ModelInfoCLI

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)
__init__()
class capellambse.cli_helpers.ModelCLI

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:
    ...
__init__()