Skip to content

release.source

The source repository and the release repository of a model.

A release exports the tracked files of a model package from its source repository (e.g. a monorepo of models) into a checkout of the release repository. The functions here check both repositories and write the package; every refusal is a ReleaseError. Git is called through a Runner, so the tests can replace it.

ReleaseError

Bases: Exception

A refusal of the release command, the message is for the user.

Runner

Bases: Protocol

Runs a command in a folder, see run.

SourceRepo dataclass 

SourceRepo(root, commit)

The clean source repository of a model.

Attributes:

Name Type Description
root Path

the top level folder of the git repository.
commit str

the commit the release is built from.

ReleaseRepo dataclass 

ReleaseRepo(path, last_tag, ahead=0)

The checkout of the release repository.

Attributes:

Name Type Description
path Path

the folder of the checkout.
last_tag str | None

the highest released version, None without a release.
ahead int

the number of local commits which origin/main lacks.

stage 

stage(text)

Log the start of a stage of the release.

run 

run(args, cwd, *, stream=False)

Run a command and return its stdout.

A command whose output is parsed (git, gh, docker queries) is captured. A long step of the build or the publishing (uv, the analyses of the model, docker build) is streamed: its output goes to the terminal as it runs. The command does not inherit VIRTUAL_ENV: the environment the release runs in is the one of the source repository, uv in the release repository uses its own.

Parameters:

Name Type Description Default
args Sequence[str]

the command and its arguments.

 required
cwd Path

the working directory.

 required
stream bool

show the output of the command instead of capturing it.

 False

Returns:

Type Description
str

The standard output of the command, empty if it is streamed.

Raises:

Type Description
ReleaseError

if the command fails or does not exist; the message has the command and the tail of its standard error (a streamed command has shown its standard error already).

current_runner 

current_runner()

Get the runner of the commands of a release in this context.

Returns:

Type Description
Runner

The runner of an enclosing using_runner, the real one, run, without.

using_runner 

using_runner(runner)

Run the commands of the kind release with a runner in this context.

The kind runs inside of sbmlsim.run.execute, which takes no runner; the build of a release through the run layer (sbmlsim.release.workflow.execute_release) passes its runner so.

Parameters:

Name Type Description Default
runner Runner

runs git, uv and the analyses of the build.

 required

Yields:

Type Description
Generator[None]

Nothing; the runner holds until the block ends.

source_repo 

source_repo(project, runner=run)

Find the source repository of a project and check it is clean.

Parameters:

Name Type Description Default
project Project

the project, its root lies in the repository.

 required
runner Runner

runs the git commands.

 run

Returns:

Type Description
SourceRepo

The root and the current commit of the repository.

Raises:

Type Description
ReleaseError

if there are uncommitted or untracked files.

clone_url 

clone_url(repository)

The URL the release repository is cloned from.

Parameters:

Name Type Description Default
repository str

the GitHub repository as owner/name.

 required

Returns:

Type Description
str

The https URL of the repository.

parse_version 

parse_version(version)

Parse a version of a release.

Parameters:

Name Type Description Default
version str

the version X.Y.Z.

 required

Returns:

Type Description
tuple[int, int, int]

The three numbers of the version.

Raises:

Type Description
ReleaseError

if the version is not X.Y.Z.

locked_version 

locked_version(package)

Get the version of a package of uv.lock.

uv locks a local package (a path, directory or editable source) whose version is dynamic without a version, e.g. a checkout of the framework given as framework_path; its version is then the kind and the location of its source, e.g. editable /home/user/sbmlsim.

Parameters:

Name Type Description Default
package Mapping[str, Any]

a [[package]] table of uv.lock.

 required

Returns:

Type Description
str

The locked version or the description of the local source.

source_framework 

source_framework(source, framework)

Get the version of the framework which the source repository locks.

The release repository is locked to the library versions of the source (see sbmlsim.release.project), so this is the framework of the release, whichever version runs the command.

Parameters:

Name Type Description Default
source SourceRepo

the source repository.

 required
framework str

the name of the framework, see sbmlsim.release.settings.ReleaseSettings.framework.

 required

Returns:

Type Description
str | None

The locked version (see locked_version), None without uv.lock or
str | None

without the framework in it.

release_repo 

release_repo(settings, path, runner=run, *, checkout=None)

Find or clone the release repository and bring it to origin/main.

The clone is the one of an out, <out>/repository: a missing one is cloned (_clone), and a fresh or reused clone is brought to origin/main (_to_origin), so a checkout it was cloned from is only a cache.

Parameters:

Name Type Description Default
settings ReleaseSettings

the release settings of the model.

 required
path Path

the clone the release is built in, cloned when it does not exist.

 required
runner Runner

runs the git commands.

 run
checkout Path | None

a checkout of the release repository which a missing path is cloned from instead of the repository on GitHub, see _clone; its main must have no commit the release repository lacks (_check_pushed).

 None

Returns:

Type Description
ReleaseRepo

The clone, its highest released version and the number of its
ReleaseRepo

commits which are not pushed (only the release commit of a release
ReleaseRepo

which failed while publishing may be, see sbmlsim.release.workflow).

An empty repository (a new repository on GitHub without a commit) has no release and no commit ahead.

Raises:

Type Description
ReleaseError

if origin is another repository, the clone cannot be brought to origin/main (_to_origin) or main of the checkout has commits which are not pushed (_check_pushed).

check_version 

check_version(version, last_tag)

Check that a version is newer than the last release.

Parameters:

Name Type Description Default
version str

the new version X.Y.Z.

 required
last_tag str | None

the last released version, None without a release.

 required

Raises:

Type Description
ReleaseError

if a version is malformed or version is not greater.

package_dirs 

package_dirs(project)

Get the folders of the package of a project, pkg/models/hctz of pkg.models.hctz.

Raises:

Type Description
ReleaseError

for a project without a package, which is not released.

export_package 

export_package(
    project, settings, source, release_path, runner=run
)

Write the tracked files of the model package into the release repository.

The files below src/<package as folders> are replaced. The parent folders of the package (and src) are namespace folders, so an __init__.py there is removed and none is created.

Parameters:

Name Type Description Default
project Project

the project, root is the folder and package the dotted name of its package.

 required
settings ReleaseSettings

the release settings, exclude lists paths of the model folder which are not released (a folder excludes everything below it).

 required
source SourceRepo

the source repository.

 required
release_path Path

the checkout of the release repository.

 required
runner Runner

runs the git commands.

 run

Returns:

Type Description
list[Path]

The written files, relative to release_path.

Raises:

Type Description
ReleaseError

for a project without a package.