release.notes¶

The release notes of a release repository.

The notes of a release are generated from the difference between the previous release, the last tag of the release repository, and the new build in its working tree: the core libraries (ReleaseSettings.core_libraries) with a summary of their own release notes, the locked libraries, the study data, the models, the experiments and the adopted fits, and the sections of the release hook of the project. A previous release of an old layout lacks parts (e.g. the fit records); what cannot be compared is stated in the notes, not omitted.

Git and gh are called through a Runner; the release notes of the core libraries come from a Fetch, so the tests run offline.

MAX_BULLETS `module-attribute` ¶

MAX_BULLETS = 5

The maximal number of bullets of the summary of a core library.

NOTES_DIR `module-attribute` ¶

NOTES_DIR = 'release-notes'

The folder of the release notes in the release repository.

Fetch `module-attribute` ¶

Fetch = Callable[[str], dict[str, str]]

Get the release notes of a library, the body by version, from its repository.

LibraryChange `dataclass` ¶

LibraryChange(name, old, new)

The changed version of a locked library.

Attributes:

Name	Type	Description
`name`	`str`	the name of the package.
`old`	`str \| None`	the version in the previous release, `None` if it was added.
`new`	`str \| None`	the version in the new release, `None` if it was removed.

CoreSummary `dataclass` ¶

CoreSummary(name, old, new, bullets, fetched=True, total=0)

The summary of the release notes of a core library between two versions.

Attributes:

Name	Type	Description
`name`	`str`	the name of the library.
`old`	`str \| None`	the version in the previous release, `None` if it was not used.
`new`	`str \| None`	the version in the new release, `None` if it is no longer used.
`bullets`	`list[str]`	the first sentences of the top level bullets of the releases.
`fetched`	`bool`	whether the release notes of the library could be fetched.
`total`	`int`	the number of bullets of the releases, more than `bullets` if they were cut to `MAX_BULLETS`.

DataChanges `dataclass` ¶

DataChanges(added=list(), removed=list(), changed=list())

The studies of the data, <data dir>/<folder> by default, which changed.

Attributes:

Name	Type	Description
`added`	`list[str]`	the studies which are new.
`removed`	`list[str]`	the studies which are gone.
`changed`	`list[str]`	the studies with added, removed or changed files.

ModelChange `dataclass` ¶

ModelChange(
    file,
    added,
    removed,
    changed_parameters,
    status="changed",
)

The changes of an SBML model of the release.

Attributes:

Name	Type	Description
`file`	`str`	the name of the SBML file in `models/`.
`added`	`dict[str, int]`	the number of species, reactions and parameters which are new.
`removed`	`dict[str, int]`	the number of species, reactions and parameters which are gone.
`changed_parameters`	`list[tuple[str, float \| None, float \| None]]`	the parameters with another value, `(id, old, new)`.
`status`	`Literal['added', 'removed', 'changed']`	whether the model is new, gone or changed.

FitChange `dataclass` ¶

FitChange(old_id, new_id, parameters)

The change of the adopted fit of a fit problem.

Attributes:

Name	Type	Description
`old_id`	`str \| None`	the adopted fit of the previous release, `None` without a record.
`new_id`	`str \| None`	the adopted fit of the new release, `None` if the problem has none.
`parameters`	`list[tuple[str, float \| None, float \| None]]`	the fitted parameters which moved, `(id, old, new)`; `None` for a parameter which is not fitted in one of the fits.

subset `property` ¶

subset

The fit problem of the fits.

library_changes ¶

library_changes(old_lock, new_lock)

Compare the locked versions of the libraries of two releases.

Parameters:

Name	Type	Description	Default
`old_lock`	`str \| None`	the `uv.lock` of the previous release, `None` without one.	required
`new_lock`	`str`	the `uv.lock` of the new release.	required

Returns:

Type	Description
`list[LibraryChange]`	The libraries which were added, removed or changed their version, sorted
`list[LibraryChange]`	by name; empty without a previous lock file.

version_key ¶

version_key(version)

Get the numbers of a version, None for a text which is no version.

github_releases ¶

github_releases(
    repository, runner=run, owner="matthiaskoenig"
)

Get the release notes of a library from GitHub.

One call of gh api lists all releases, so the releases between two versions need no further call. A leading v of a tag is removed.

Parameters:

Name	Type	Description	Default
`repository`	`str`	the name of the repository, e.g. `sbmlsim`.	required
`runner`	`Runner`	runs `gh`.	`run`
`owner`	`str`	the owner of the repository on GitHub, see `ReleaseSettings.library_owner`.	`'matthiaskoenig'`

Returns:

Type	Description
`dict[str, str]`	The body of the release notes by version.

Raises:

Type	Description
`ReleaseError`	if `gh` is missing or fails, e.g. without network.

core_summaries ¶

core_summaries(
    changes,
    fetch=github_releases,
    libraries=("sbmlsim", "sbmlutils"),
)

Summarize the release notes of the core libraries which changed.

For every release after the old up to the new version, newest first, the first sentences of the top level bullets (-) are taken, at most MAX_BULLETS per library. A library whose release notes cannot be fetched gets a summary without bullets and fetched=False, it never fails the release. A library which was added or removed gets a summary without bullets.

Parameters:

Name	Type	Description	Default
`changes`	`Iterable[LibraryChange]`	the changed libraries, see `library_changes`.	required
`fetch`	`Fetch`	gets the release notes of a library by version.	`github_releases`
`libraries`	`Sequence[str]`	the core libraries, in their order.	`('sbmlsim', 'sbmlutils')`

Returns:

Type	Description
`list[CoreSummary]`	The summaries of the core libraries which changed.

data_changes ¶

data_changes(
    release,
    package_dir,
    data_dirs,
    runner=run,
    study=_default_study,
)

Compare the studies of the data of the previous release and the new build.

A study is the group of the files of the data folders which study gives one name, by default a folder of the package below a data folder (sbmlsim.release.hooks.ReleaseHook.data_study); it changed if a file was added, removed or changed. The files are keyed by their path in the release repository: the files of the previous release are compared by the git blob hashes at the last tag with the hashes git gives the files of the working tree (git hash-object), ignored files are skipped.

Parameters:

Name	Type	Description	Default
`release`	`ReleaseRepo`	the release repository.	required
`package_dir`	`str \| PurePosixPath`	the folder of the package in the release repository, e.g. `src/pkg/models/hctz`.	required
`data_dirs`	`Sequence[str \| PurePosixPath]`	the data folders, relative to the package (`data_dirs`).	required
`runner`	`Runner`	runs git.	`run`
`study`	`Study`	the study of a file, by its data folder relative to the package and its path relative to the data folder.	`_default_study`

Returns:

Type	Description
`DataChanges`	The added, removed and changed studies.

experiment_changes ¶

experiment_changes(release, runner=run)

Compare the experiments of the previous release and the new build.

The experiments are the folders of simulations/, without the folders whose name starts with _ (e.g. _figures).

Parameters:

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

Returns:

Type	Description
`tuple[list[str], list[str]]`	The added and the removed experiments.

model_changes ¶

model_changes(release, runner=run)

Compare the SBML models of the previous release and the new build.

The models are the files models/*.xml; a model whose file is unchanged is not listed.

Parameters:

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

Returns:

Type	Description
`list[ModelChange]`	The models which are new, gone or changed, sorted by file: the number of
`list[ModelChange]`	species, reactions and parameters added and removed and the parameters
`list[ModelChange]`	with another value; a parameter which an assignment rule or an initial
`list[ModelChange]`	assignment sets has no value of its own and is not compared.

Raises:

Type	Description
`ReleaseError`	if a file is no SBML model.

fits_prefix ¶

fits_prefix(project)

Get the folder of the adopted fits in the release repository.

Raises:

Type	Description
`ReleaseError`	for a project without a folder of fit records or one outside of the package, which is not released.

fit_changes ¶

fit_changes(release, project, runner=run)

Compare the adopted fits of the previous release and the new build.

The fits are matched by their fit problem (fit_subset); a fit problem without a record in the previous release gives a change with old_id=None. The values are the best parameter set of the parameters.json of a record.

Parameters:

Name	Type	Description	Default
`release`	`ReleaseRepo`	the release repository.	required
`project`	`Project`	the project, its adopted fits are the ones of the new release.	required
`runner`	`Runner`	runs git.	`run`

Returns:

Type	Description
`list[FitChange]`	The changed fits, sorted by fit problem.

Raises:

Type	Description
`ReleaseError`	if the record of an adopted fit lacks `parameters.json`.

dependency_names ¶

dependency_names(dependencies)

Get the normalized names of the packages of requirements.

Parameters:

Name	Type	Description	Default
`dependencies`	`Iterable[str]`	requirements as in `[project].dependencies`, e.g. `"sbmlsim[docs]>=0.7"`.	required

Returns:

Type	Description
`set[str]`	The names, lower case with runs of `-`, `_` and `.` as `-` (as in `uv.lock`).

data_dirs ¶

data_dirs(project)

Get the folders of the data of a project which a release has.

The folders are the data paths of the project (Project.data_path) inside of its package; a folder outside of the package is not released.

Parameters:

Name	Type	Description	Default
`project`	`Project`	the project.	required

Returns:

Type	Description
`list[PurePosixPath]`	The folders relative to the root of the package.

write_release_notes ¶

write_release_notes(
    context, release, runner=run, fetch=None
)

Write the release notes of the new release into the release repository.

Parameters:

Name	Type	Description	Default
`context`	`ProjectContext`	the project context, with the version of the release and the commit of the source repository it is made from.	required
`release`	`ReleaseRepo`	the release repository with the new build in its working tree and the previous release as `last_tag`.	required
`runner`	`Runner`	runs git.	`run`
`fetch`	`Fetch \| None`	gets the release notes of a core library by version, by default from GitHub with `gh` (see `github_releases`).	`None`

Returns:

Type	Description
`Path`	The written file `release-notes/<version>.md`.

Raises:

Type	Description
`ReleaseError`	if the new build has no `uv.lock`.

release.notes¶

MAX_BULLETS module-attribute ¶

NOTES_DIR module-attribute ¶

Fetch module-attribute ¶

LibraryChange dataclass ¶

CoreSummary dataclass ¶

DataChanges dataclass ¶

ModelChange dataclass ¶

FitChange dataclass ¶

subset property ¶

library_changes ¶

version_key ¶

github_releases ¶

core_summaries ¶

data_changes ¶

experiment_changes ¶

model_changes ¶

fits_prefix ¶

fit_changes ¶

dependency_names ¶

data_dirs ¶

write_release_notes ¶

MAX_BULLETS `module-attribute` ¶

NOTES_DIR `module-attribute` ¶

Fetch `module-attribute` ¶

LibraryChange `dataclass` ¶

CoreSummary `dataclass` ¶

DataChanges `dataclass` ¶

ModelChange `dataclass` ¶

FitChange `dataclass` ¶

subset `property` ¶