release.manifest¶

The manifest of a release and the removal of what the release did not build.

The build writes release.json (the version, the commit of the source, the library versions and a hash of every generated file). The publishing finds a build which is not committed yet and publishes it as it is when the manifest still matches, so a reviewed build needs no new simulations. prune makes the release repository hold only what the command generates.

BUILD_MARKER `module-attribute` ¶

BUILD_MARKER = 'sbmlsim_release_build'

The file in the git folder which marks a build which has not finished.

LEGACY_FRAMEWORK `module-attribute` ¶

LEGACY_FRAMEWORK = 'pkpdsim'

The framework of a manifest of pkpdsim 0.19, which has the field pkpdsim.

MAX_FILE_SIZE `module-attribute` ¶

MAX_FILE_SIZE = 100 * 1024 * 1024

The largest file a release may hold: GitHub rejects a push of a larger one.

Manifest `dataclass` ¶

Manifest(
    version,
    source_commit,
    framework,
    framework_version,
    libraries=dict(),
    files=dict(),
)

What a build of the release repository produced.

Attributes:

Name	Type	Description
`version`	`str`	the released version.
`source_commit`	`str`	the commit of the source repository.
`framework`	`str`	the name of the framework of the release, see `sbmlsim.release.settings.ReleaseSettings.framework`.
`framework_version`	`str`	the version of the framework in the lock of the release.
`libraries`	`Mapping[str, str]`	the versions of the framework and the core libraries in the lock of the release by their name.
`files`	`Mapping[str, str]`	the sha256 of every generated file by its POSIX path relative to the release repository.

to_dict ¶

to_dict()

Get the manifest as JSON data.

to_json ¶

to_json()

Serialise the manifest.

Returns:

Type	Description
`str`	The JSON text with sorted keys and a final newline.

from_dict `staticmethod` ¶

from_dict(data)

Get a manifest from its JSON data, also the one of pkpdsim 0.19.

A manifest of pkpdsim 0.19 has the versions of pkpdsim, sbmlsim and sbmlutils as fields of their own; its framework is pkpdsim (LEGACY_FRAMEWORK).

Parameters:

Name	Type	Description	Default
`data`	`Mapping[str, Any]`	the JSON data of `release.json`.	required

Returns:

Type	Description
`Manifest`	The manifest.

Raises:

Type	Description
`TypeError`	for data which is no manifest.
`KeyError`	for a manifest of pkpdsim 0.19 without a version of a library.

read `staticmethod` ¶

read(path)

Read a manifest, also the one of pkpdsim 0.19 (see from_dict).

Parameters:

Name	Type	Description	Default
`path`	`Path`	the `release.json` file.	required

Returns:

Type	Description
`Manifest \| None`	The manifest, `None` if the file is missing.

Raises:

Type	Description
`ReleaseError`	if the file is not a manifest.

write_manifest ¶

write_manifest(
    release_path,
    version,
    source,
    written,
    *,
    framework,
    core_libraries=(),
)

Write release.json with a hash of every generated file.

Parameters:

Name	Type	Description	Default
`release_path`	`Path`	the release repository.	required
`version`	`str`	the released version.	required
`source`	`SourceRepo`	the source repository the release is built from.	required
`written`	`Iterable[Path]`	the files (or folders) the stages wrote, absolute or relative to the release repository.	required
`framework`	`str`	the framework of the release.	required
`core_libraries`	`Sequence[str]`	the core libraries of the release.	`()`

Returns:

Type	Description
`Manifest`	The manifest which was written.

Raises:

Type	Description
`ReleaseError`	if `uv.lock` lacks the framework or a core library.

matches ¶

matches(
    release_path,
    version,
    source_commit,
    framework,
    framework_version,
    runner=run,
)

Tell whether the release repository holds the build of this release.

Parameters:

Name	Type	Description	Default
`release_path`	`Path`	the release repository.	required
`version`	`str`	the version to release.	required
`source_commit`	`str`	the commit of the source repository.	required
`framework`	`str`	the name of the framework of the release.	required
`framework_version`	`str \| None`	the version of the framework which the source locks (see `sbmlsim.release.source.source_framework`), `None` matches no build.	required
`runner`	`Runner`	runs git.	`run`

Returns:

Type	Description
`bool`	`True` if the manifest exists, version, commit, framework and its
`bool`	version are equal, every listed file hashes the same and git status
`bool`	lists no file outside the manifest (besides `release.json`).

start_build ¶

start_build(release_path, version, runner=run)

Mark the start of a build, before the first file is written.

The marker lies in the git folder, so it is never committed or pruned.

Parameters:

Name	Type	Description	Default
`release_path`	`Path`	the release repository.	required
`version`	`str`	the version which is built.	required
`runner`	`Runner`	runs git.	`run`

stop_build ¶

stop_build(release_path, runner=run)

Record the paths a build changed before it failed or was interrupted.

The marker keeps the paths which git status lists, so the next run tells the changes of the build from a file added by hand (changed_by_build). A build which could not record them (it was killed) leaves a marker without paths.

Parameters:

Name	Type	Description	Default
`release_path`	`Path`	the release repository.	required
`runner`	`Runner`	runs git.	`run`

finish_build ¶

finish_build(release_path, runner=run)

Remove the marker of a build, after the manifest is written.

Parameters:

Name	Type	Description	Default
`release_path`	`Path`	the release repository.	required
`runner`	`Runner`	runs git.	`run`

changed_by_build ¶

changed_by_build(release_path, version, runner=run)

Tell whether the release repository is clean or changed only by a build.

A build of the same version may be rebuilt, the files may differ from their hashes (e.g. after a hand edit during the review). Deleted files are no change, a build deletes what it did not generate. A build which failed or was interrupted left its marker with the paths it had changed (stop_build), these are rebuilt as well; a build which was killed left no paths, then every change is taken as its change.

Parameters:

Name	Type	Description	Default
`release_path`	`Path`	the release repository.	required
`version`	`str`	the version to release.	required
`runner`	`Runner`	runs git.	`run`

Returns:

Type	Description
`bool`	`True` if git status lists no file, or lists only files of the manifest
`bool`	of `version`, `release.json` and the paths of an unfinished build.

check_not_ignored ¶

check_not_ignored(release_path, written, runner=run)

Refuse a build which wrote files that git ignores.

The commit of the release (git add -A) leaves an ignored file out, e.g. a tracked results/ folder of a model package below an ignore pattern of the release repository.

Parameters:

Name	Type	Description	Default
`release_path`	`Path`	the release repository.	required
`written`	`Iterable[Path]`	the files (or folders) the stages wrote.	required
`runner`	`Runner`	runs git.	`run`

Raises:

Type	Description
`ReleaseError`	if git ignores a written file; the message names them.

check_file_sizes ¶

check_file_sizes(
    release_path, written, max_size=MAX_FILE_SIZE
)

Refuse a build which wrote a file above the size GitHub accepts.

GitHub rejects a push with a file above 100 MB, after the commit and the tag of the release; e.g. the netCDF results of the simulations of a model which keeps its results, gigabytes for the steps of the integrator.

Parameters:

Name	Type	Description	Default
`release_path`	`Path`	the release repository.	required
`written`	`Iterable[Path]`	the files (or folders) the stages wrote.	required
`max_size`	`int`	the largest size of a file in bytes.	`MAX_FILE_SIZE`

Raises:

Type	Description
`ReleaseError`	if a written file is larger; the message names them with their size.

prune ¶

prune(release_path, written, runner=run)

Remove every file of the release repository the command did not generate.

Kept are .git, ignored files (.gitignore), release-notes/*.md, release.json and written. Folders left empty are removed.

Parameters:

Name	Type	Description	Default
`release_path`	`Path`	the release repository.	required
`written`	`Iterable[Path]`	the files (or folders) the stages wrote.	required
`runner`	`Runner`	runs git.	`run`

Returns:

Type	Description
`list[Path]`	The removed files and folders (absolute).

release.manifest¶

BUILD_MARKER module-attribute ¶

LEGACY_FRAMEWORK module-attribute ¶

MAX_FILE_SIZE module-attribute ¶

Manifest dataclass ¶

to_dict ¶

to_json ¶

from_dict staticmethod ¶

read staticmethod ¶

write_manifest ¶

matches ¶

start_build ¶

stop_build ¶

finish_build ¶

changed_by_build ¶

check_not_ignored ¶

check_file_sizes ¶

prune ¶

BUILD_MARKER `module-attribute` ¶

LEGACY_FRAMEWORK `module-attribute` ¶

MAX_FILE_SIZE `module-attribute` ¶

Manifest `dataclass` ¶

from_dict `staticmethod` ¶

read `staticmethod` ¶