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:
git://host.name/repo.git
and variants, like:git+https://host.name/repo
,git@host.name:repo
http:// and https://
, example:https://host.name/path/%s?param=arg
zip://, zip+https:// etc.
, examples:zip:///local/file.zip
,zip+https://host.name/remote/file.zip
,zip+https://host.name/remote/%s?param=arg!file.zip
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:
For local file paths:
LocalFileHandler
For Git repositories:
GitFileHandler
For simple HTTP/HTTPS servers, optionally using HTTP Basic Authentication:
HTTPFileHandler
For the Gitlab Artifacts service:
GitlabArtifactsFiles
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:
One of the following:
A str or PathLike pointing to an
.aird
fileA str or PathLike pointing to a
.json
file, which contains the arguments to instantiate aMelodyModel
The contents of such a JSON file (as string)
- Returns:
A dict with information about how to load a
MelodyModel
.- Return type:
- 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 forloadinfo()
.- Returns:
The loaded model, as described by the value.
- Return type:
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 apath
, optionally anentrypoint
, and any additional arguments that the underlyingFileHandler
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:
Click parameter types¶
There are also Click parameter types available that encapsulate the
loadinfo
and loadcli
functions, respectively:
- class capellambse.cli_helpers.ModelInfoCLI
Raise a dependency error.
- __init__(**kwargs)
- class capellambse.cli_helpers.ModelCLI
Raise a dependency error.
- __init__(**kwargs)