project
Description
Project management for SysML v2 and KerML based on Sysand.
Index
Classes
The project (its |
||
Base class of every error raised by the |
Functions
Add a usage (dependency) to a project, then lock and sync it. |
||
Create a SysML v2 or KerML project. |
||
Resolve a project’s usages and write them to its lockfile. |
||
Install the projects in a project’s lockfile into its .sysand directory. |
Enumerations
The kinds of project init creates. |
Functions
- add(*, project_dir: str | pathlib.Path, publisher: str, name: str, version_constraint: str, index: Sequence[str] | None = None, default_index: Sequence[str] | None = None, no_index: bool = False) None
Add a usage (dependency) to a project, then lock and sync it.
Declares a usage of the project publisher/name in .project.json, resolves it from the indexes, writes the lockfile and installs the locked projects into the project’s .sysand directory, removing those that are no longer needed. If locking or installing fails, .project.json is left as it was. When the project already uses publisher/name, its version constraint is replaced.
Indexes, credentials and configuration are read as lock reads them.
- Args:
project_dir: The directory of the project to add the usage to. publisher: The publisher of the project to use. name: The name of the project to use. Spell publisher and name
as the project does (“Acme Labs”, “My Lib”), or in lowercase with - for spaces (“acme-labs”, “my-lib”) to take the project’s spelling.
- version_constraint: The versions of the used project to allow, such
as “1.2.3”, “<2”, “>=3” or “*”.
- index: The indexes to search before the default ones. When None,
read from SYSAND_INDEX.
- default_index: The indexes to use instead of the default index. When
None, read from SYSAND_DEFAULT_INDEX.
no_index: Do not use any index.
- Raises:
ValueError: no_index is combined with index or default_index. SysandError: the project could not be found or read, publisher,
name or version_constraint is not valid, no compatible set of versions exists, an index could not be used, or the projects could not be installed.
- init(*, project_dir: str | pathlib.Path, name: str, publisher: str, version: str, metamodel: Literal[sysml, kerml], kind: syside.project.ProjectKind, license: str | None = None) None
Create a SysML v2 or KerML project.
Writes .project.json and .meta.json to project_dir, creating the directory if it does not exist. Its parent directory must exist.
- Args:
project_dir: The directory to create the project in. name: The name of the project. publisher: The person, team or organization that develops the
project. Together with name, it identifies the project when other projects use it.
- version: The version of the project, in Semantic Versioning 2.0
format, such as “0.1.0”.
- metamodel: The metamodel the project is written in, “sysml” for
SysML v2 or “kerml” for KerML. Its current release is recorded in .meta.json.
- kind: The kind of project to create, such as
ProjectKind.PROJECT_JSON.
- license: The license of the project, as an SPDX license expression
such as “MIT OR Apache-2.0”. When None, the project declares no license.
- Raises:
- ValueError: name or publisher is not valid, version is not a
semantic version, metamodel is not one of the values above, or license is not an SPDX license expression.
- TypeError: kind is not a ProjectKind, such as its value as a
string.
FileExistsError: project_dir already contains a project. OSError: the project files could not be written.
- lock(*, path: str | pathlib.Path = '.', index: Sequence[str] | None = None, default_index: Sequence[str] | None = None, no_index: bool = False) None
Resolve a project’s usages and write them to its lockfile.
The project is the one containing path: the nearest of path and its parent directories that holds .project.json. Its usages, and theirs in turn, are resolved to exact versions and written to sysand-lock.toml in the project directory. The SysML v2 and KerML standard libraries are not locked: Syside provides them.
Indexes are authenticated with the SYSAND_CRED_* environment variables and with the credentials in the operating system’s credential store. Configuration is read from the file SYSAND_CONFIG_FILE names, and from sysand.toml in the user’s configuration directory and in the project directory unless SYSAND_NO_CONFIG is set.
- Args:
path: Where to start looking for the project. index: The indexes to search before the default ones. When None,
read from the comma-separated SYSAND_INDEX environment variable.
- default_index: The indexes to use instead of the default index,
https://sysand.com. When None, read from the comma-separated SYSAND_DEFAULT_INDEX environment variable.
- no_index: Do not use any index. Cannot be combined with index or
default_index.
- Raises:
ValueError: no_index is combined with index or default_index. SysandError: the project could not be found or read, no compatible
set of versions exists, an index could not be used, or the lockfile could not be written.
- sync(*, path: str | pathlib.Path = '.', index: Sequence[str] | None = None, default_index: Sequence[str] | None = None, no_index: bool = False) None
Install the projects in a project’s lockfile into its .sysand directory.
The project is the one containing path, found as lock finds it. .sysand is created if it does not exist, and projects that are no longer needed are removed from it. Without a lockfile, the project is locked first, as lock does, and the lockfile is written.
Indexes, credentials and configuration are read as lock reads them.
- Args:
path: Where to start looking for the project. index: The indexes to search before the default ones, used when
there is no lockfile yet. When None, read from SYSAND_INDEX.
- default_index: The indexes to use instead of the default index. When
None, read from SYSAND_DEFAULT_INDEX.
no_index: Do not use any index.
- Raises:
ValueError: no_index is combined with index or default_index. SysandError: the project could not be found or read, the lockfile is
not valid, there was no lockfile and locking failed, an index could not be used, or the projects could not be installed.
Enumerations
- class ProjectKind
The kinds of project init creates.
PROJECT_JSON¶The kinds of project init creates.
Used by: