project
Description
Project management for SysML v2 and KerML based on Sysand.
Index
Classes
An index refused the request for lack of (accepted) credentials. |
||
The |
||
An index answered, but not with what the protocol requires
(discovery document, |
||
The project (its |
||
A project could not be resolved from the configured sources. |
||
Dependency resolution found no solution. |
||
|
||
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.
- Parameters:
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.
ProjectError – the project could not be found or read, publisher, name or version_constraint is not valid, or the projects could not be installed.
SolveError – no compatible set of versions exists.
AuthError – an index refused the credentials, or the SYSAND_CRED_* variables are malformed.
IndexProtocolError, ResolutionError – an index could not be used.
- 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.
- Parameters:
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.
- Parameters:
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.
ProjectError – the project could not be found or read, or the lockfile could not be written.
SolveError – no compatible set of versions exists.
AuthError – an index refused the credentials, or the SYSAND_CRED_* variables are malformed.
IndexProtocolError, ResolutionError – an index could not be used.
- 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.
- Parameters:
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.
ProjectError – the project could not be found or read, or the lockfile is not valid or could not be written.
SolveError – there was no lockfile, and no compatible set of versions exists.
AuthError – an index refused the credentials, or the SYSAND_CRED_* variables are malformed.
IndexProtocolError, ResolutionError – an index could not be used.
SyncError – installation failed part-way; its partial lists what was installed and pruned before the failure.
EnvError – the environment could not be read or written.
Enumerations
- class ProjectKind
The kinds of project init creates.
PROJECT_JSON¶The kinds of project init creates.
Used by: