release¶

The release of a model repository, see Release of a model repository. A model package uses the release settings; the command pkpd_release is main, release is the release as a function.

The release metadata of a model: what the monorepo does not know.

A model package sets PKPDModel.release to a ReleaseSettings. The module uses the standard library only, so importing the model object stays light.

Author `dataclass` ¶

Author(name, orcid=None, affiliation=None)

An author of the citation of a model.

Attributes:

Name	Type	Description
`name`	`str`	the name as `"Family, Given"`, as Zenodo wants it.
`orcid`	`str \| None`	the ORCID of the author.
`affiliation`	`str \| None`	the affiliation of the author.

citation_name `property` ¶

citation_name

The name with the initial of the given name, "Family, G.".

display_name `property` ¶

display_name

The name as "Given Family".

ReleaseSettings `dataclass` ¶

ReleaseSettings(
    *,
    title,
    repository,
    doi,
    authors,
    keywords,
    docker_image,
    funding,
    description,
    exclude=("TODO.md", "literature", "thesis"),
    first_year,
)

The metadata of the release of a model.

All fields are keyword-only; the sequences are stored as tuples, so a list can be passed and the settings are hashable.

Attributes:

Name	Type	Description
`title`	`str`	the title of the release: the Zenodo record, the citation, the README and the docs site.
`repository`	`str`	the GitHub repository as `owner/name`.
`doi`	`str`	the concept DOI of Zenodo.
`authors`	`Sequence[Author]`	the authors of the citation, in order.
`keywords`	`Sequence[str]`	the keywords of the Zenodo record.
`docker_image`	`str`	the Docker image of the model.
`funding`	`str`	the funding text.
`description`	`str`	one paragraph about the model.
`exclude`	`Sequence[str]`	paths of the model folder which are not released.
`first_year`	`int`	the year of the first release, the start of the copyright.

owner `property` ¶

owner

The owner of the repository.

repo_name `property` ¶

repo_name

The name of the repository.

site_url `property` ¶

site_url

The URL of the docs site on GitHub pages.

author_names `property` ¶

author_names

The authors as "Given Family", the last joined with and.

raw_url `property` ¶

raw_url

The base URL of the raw files of the main branch.

missing ¶

missing()

Get the names of the fields a release lacks, sorted.

A field is missing if it is empty; exclude may be empty (everything is released), first_year is missing unless it is a positive int.

The command pkpd_release: the complete release of a model repository.

pkpd_release pkdb_models.models.hctz --version 0.8.0 --no-publish
pkpd_release pkdb_models.models.hctz --version 0.8.0
pkpd_release pkdb_models.models.hctz --repo ../hctz-model --version 0.8.0

The command checks the source and the release repository, builds the release in the release repository (export of the model package, project files, models, simulations, fit reports, release notes, docs, manifest) and publishes it (commit, tag, GitHub Pages, push, Docker image, GitHub release). --no-publish stops before the commit, so the build can be reviewed; a later run without the flag publishes the reviewed build without building it again. A run which failed while publishing is finished by running the same command again. See release for the order of the steps.

Publisher `module-attribute` ¶

Publisher = Callable[
    [ReleaseSettings, Path, str, Path, Runner], list[str]
]

Publishes a built release, see pkpdsim.release.publish.publish.

release ¶

release(
    model,
    *,
    version,
    repo,
    publish,
    pkpdsim_path,
    workers,
    runner=run,
    publisher=publish,
)

Make the complete release of a model repository.

The steps, in order; the first failure stops the release:

Checks, before anything is changed: the version is X.Y.Z, the release settings of the model are complete, the source repository is clean (source_repo), the release repository is a checkout of the repository on main and up to date (release_repo, cloned when missing) without local commits besides the release commit of a resumed release, the version is greater than the last release (check_version), every adopted fit has its record; when publishing, the model declares its COMBINE archive and docker, its buildx plugin and gh are ready (check_tools), so a missing tool fails before the long build.
The build, skipped if a publishing run finds a build of this release (matches, i.e. a reviewed --no-publish build) with a publishable lock; the mark of an unfinished build is removed then. Otherwise the release repository must be clean, changed only by an earlier build of this version or by an unfinished build (changed_by_build). The stages write, in this order: the export of the package, the project files, the build (uv.lock, models, simulations, fit reports), the release notes and the docs. A written file which git ignores is refused (check_not_ignored), the commit would lack it. prune then removes every file which no stage wrote, and the manifest release.json is written last, so it hashes the final tree which matches compares.
--no-publish stops here, before the commit.
The lock is checked (check_lock, it exists only after the build), then the release is published (publisher).

A build which failed or was interrupted is rebuilt by the next run: the build marks its start in the git folder and removes the mark after the manifest (start_build, finish_build); a build which fails or is interrupted records the paths it changed in the mark (stop_build), so a file added by hand afterwards is still refused.

If HEAD is the release commit of the version (clean, with its manifest) and its tag is missing or at HEAD, an earlier run failed while publishing: the version check, the fit records and the build are skipped and the publishing steps resume, whatever the source commit or the pkpdsim version is now.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model which is released, with its release settings.	required
`version`	`str`	the version of the release, `X.Y.Z`.	required
`repo`	`Path \| None`	the checkout of the release repository, default is a sibling of the source repository named like the release repository.	required
`publish`	`bool`	publish the release; `False` stops before the commit.	required
`pkpdsim_path`	`Path \| None`	a local checkout of pkpdsim instead of the released pkpdsim, only without `publish`.	required
`workers`	`str`	the number of workers of the simulations, `auto` or a number.	required
`runner`	`Runner`	runs git, uv, the commands of the model, docker and gh.	`run`
`publisher`	`Publisher`	publishes the built release.	`publish`

Returns:

Type	Description
`Path`	The checkout of the release repository.

Raises:

Type	Description
`ReleaseError`	if a check or a step fails; the message is for the user.

parser ¶

parser()

Get the parser of the command pkpd_release.

main ¶

main(argv=None)

The console script pkpd_release, see release.

Parameters:

Name	Type	Description	Default
`argv`	`Sequence[str] \| None`	the command line arguments, `sys.argv[1:]` by default.	`None`

Raises:

Type	Description
`SystemExit`	with 2 for a usage error, with 1 if the release fails.

release¶

Author dataclass ¶

citation_name property ¶

display_name property ¶

ReleaseSettings dataclass ¶

owner property ¶

repo_name property ¶

site_url property ¶

author_names property ¶

raw_url property ¶