project

Description

Project management for SysML v2 and KerML based on Sysand.

Index

Classes

AuthError

An index refused the request for lack of (accepted) credentials.

EnvError

The .sysand environment is missing, unreadable or malformed.

IndexProtocolError

An index answered, but not with what the protocol requires (discovery document, versions.json, digests, JSON shape).

ProjectError

The project (its .project.json, .meta.json or location) is missing, malformed, or does not contain what the call needs.

ResolutionError

A project could not be resolved from the configured sources.

SolveError

Dependency resolution found no solution.

SyncError

sync failed part-way.

SysandError

Base class of every error raised by the sysand package.

Functions

add

Add a usage (dependency) to a project, then lock and sync it.

init

Create a SysML v2 or KerML project.

lock

Resolve a project’s usages and write them to its lockfile.

sync

Install the projects in a project’s lockfile into its .sysand directory.

Enumerations

ProjectKind

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.

The kinds of project init creates.

Used by: