API Docs#

Library Functions#

Library functions for Jupyter Releaser.

jupyter_releaser.lib.bump_version(version_spec, version_cmd, changelog_path, tag_format, package_name=None)#

Bump the version and verify new version

jupyter_releaser.lib.delete_release(auth, release_url, dry_run=False)#

Delete a draft GitHub release by url to the release page

jupyter_releaser.lib.draft_changelog(version_spec, ref, branch, repo, since, since_last_stable, auth, changelog_path, dry_run, post_version_spec, post_version_message, silent, tag_format)#

Create a changelog entry PR

jupyter_releaser.lib.extract_changelog(dry_run, auth, changelog_path, release_url, silent=False)#

Extract the changelog from the draft GH release body and update it.

> If the release must is silent, the changelog entry will be replaced by > a placeholder

jupyter_releaser.lib.extract_release(auth, dist_dir, dry_run, release_url)#

Download and verify assets from a draft GitHub release

jupyter_releaser.lib.forwardport_changelog(auth, ref, branch, repo, username, changelog_path, dry_run, release_url)#

Forwardport Changelog Entries to the Default Branch

jupyter_releaser.lib.make_changelog_pr(auth, branch, repo, title, commit_message, body, dry_run=False)#

Make a changelog PR.

jupyter_releaser.lib.populate_release(ref, branch, repo, version_cmd, auth, changelog_path, dist_dir, dry_run, release_url, post_version_spec, post_version_message, assets, tag_format, silent=False)#

Populate release assets and push tags and commits

jupyter_releaser.lib.prep_git(ref, branch, repo, auth, username, url)#

Set up git

jupyter_releaser.lib.publish_assets(auth, dist_dir, npm_token, npm_cmd, twine_cmd, npm_registry, twine_repository_url, npm_tag, dry_run, release_url, python_package)#

Publish release asset(s)

jupyter_releaser.lib.publish_changelog(branch, repo, auth, changelog_path, dry_run)#

Remove changelog placeholder entries.

jupyter_releaser.lib.publish_release(auth, dry_run, release_url, silent)#

Publish GitHub release

jupyter_releaser.lib.tag_release(dist_dir, release_message, tag_format, tag_message, no_git_tag_workspace)#

Create release commit and tag

Python Utility Functions#

Python-related utilities.

jupyter_releaser.python.build_dist(dist_dir, clean=True)#

Build the python dist files into a dist folder

jupyter_releaser.python.check_dist(dist_file, test_cmd='', python_imports=None, check_cmd='pipx run twine check --strict {dist_file}', extra_check_cmds=None, resource_paths=None)#

Check a Python package locally (not as a cli)

jupyter_releaser.python.fetch_pypi_api_token() str#

Fetch the PyPI API token for trusted publishers

This implements the manual steps described in https://docs.pypi.org/trusted-publishers/using-a-publisher/ as of June 19th, 2023.

It returns an empty string if it fails.

jupyter_releaser.python.get_pypi_token(release_url, python_package)#

Get the PyPI token

Note: Do not print the token in CI since it will not be sanitized if it comes from the PYPI_TOKEN_MAP


Start a local PyPI server

NPM Utility Functions#

npm-related utilities.

jupyter_releaser.npm.build_dist(package, dist_dir)#

Build npm dist file(s) from a package

jupyter_releaser.npm.check_dist(dist_dir, install_options, repo)#

Check npm dist file(s) in a dist dir

jupyter_releaser.npm.extract_dist(dist_dir, target, repo='')#

Extract dist files from a dist_dir into a target dir

If repo is provided, check that the repository URL is ending by it.


Get the package json info from the tarball


Get the formatted list of npm package names and versions


Handle npm_config


Generate tags for npm workspace packages

Changelog Utility Functions#

Changelog utilities for Jupyter Releaser.

jupyter_releaser.changelog.build_entry(ref, branch, repo, auth, changelog_path, since, since_last_stable, resolve_backports)#

Build a python version entry

jupyter_releaser.changelog.check_entry(ref, branch, repo, auth, changelog_path, since, since_last_stable, resolve_backports, output)#

Check changelog entry


Extract the current changelog entry


Extract the current released version from the changelog

jupyter_releaser.changelog.format(changelog: str) str#

Clean up changelog formatting

jupyter_releaser.changelog.format_pr_entry(target, number, auth=None, dry_run=False)#

Format a PR entry in the style used by our changelogs.

  • target (str) – The GitHub owner/repo

  • number (int) – The PR number to resolve

  • auth (str, optional) – The GitHub authorization token

  • dry_run (bool, optional) – Whether this is a dry run.


A formatted PR entry

Return type:


jupyter_releaser.changelog.get_version_entry(ref, branch, repo, version, *, since=None, since_last_stable=None, until=None, auth=None, resolve_backports=False, dry_run=False)#

Get a changelog for the changes since the last tag on the given branch.

  • branch (str) – The target branch

  • ref (str) – The source reference

  • repo (str) – The GitHub owner/repo

  • version (str) – The new version

  • since (str) – Use PRs with activity since this date or git reference

  • since_last_stable – Use PRs with activity since the last stable git tag

  • until (str, optional) – Use PRs until this date or git reference

  • auth (str, optional) – The GitHub authorization token

  • resolve_backports (bool, optional) – Whether to resolve backports to the original PR

  • dry_run (bool, optional) – Whether this is a dry run.


A formatted changelog entry with markers

Return type:


jupyter_releaser.changelog.insert_entry(changelog: str, entry: str, version: str | None = None, silent: bool = False) str#

Insert the entry into the existing changelog.

jupyter_releaser.changelog.remove_placeholder_entries(repo: str, auth: str | None, changelog_path: str, dry_run: bool) int#

Replace any silent marker with the GitHub release body if the release has been published.

  • repo (str) – The GitHub owner/repo

  • auth (str) – The GitHub authorization token

  • changelog_path (str) – The changelog file path

  • dry_run (bool)


Number of placeholders removed

Return type:


jupyter_releaser.changelog.splice_github_entry(orig_entry, github_entry)#

Splice an entry created on GitHub into one created by build_entry

jupyter_releaser.changelog.update_changelog(changelog_path, entry, silent=False)#

Update a changelog with a new entry.

Global Utility Functions#

Jupyter Releaser Utils.

jupyter_releaser.util.actions_output(name, value)#

Handle setting an action output on GitHub

jupyter_releaser.util.bump_version(version_spec, *, changelog_path='', version_cmd='')#

Bump the version


Compute the sha256 of a file

jupyter_releaser.util.create_release_commit(version, release_message=None, dist_dir='dist')#

Generate a release commit that has the sha256 digests for the release files


Check for or start a mock github server.

jupyter_releaser.util.ensure_sha(dry_run, expected_sha, branch)#

Ensure the sha of the remote branch matches the expected sha

jupyter_releaser.util.extract_metadata_from_release_url(gh, release_url, auth)#

Extract the metadata for a release given a url.

jupyter_releaser.util.fetch_release_asset(target_dir, asset, auth)#

Fetch a release asset into a target directory.

jupyter_releaser.util.fetch_release_asset_data(asset, auth)#

Fetch the data for a release asset.


Get the appropriate git branch


Get the default remote branch


Get the default ‘since’ value for a branch

jupyter_releaser.util.get_gh_object(dry_run=False, **kwargs)#

Get a properly configured GhAPi object

jupyter_releaser.util.get_latest_tag(source, since_last_stable=False)#

Get the default ‘since’ value for a branch


Get the mock github url.


Get the appropriate remote git name.


Get the remote repo owner and name


Get the current package version

jupyter_releaser.util.handle_since() str#

Capture the “since” argument in case we add tags before checking changelog.


Test whether a version is a prerelease version

jupyter_releaser.util.latest_draft_release(gh, branch=None)#

Get the latest draft release for a given repo

jupyter_releaser.util.log(*outputs, **kwargs)#

Log an output to stderr


Normalize a path to use backslashes


Parse a release url into a regex match


Prepare the environment variables, for use when running one of the action scripts.


Read the jupyter-releaser config data

jupyter_releaser.util.release_for_url(gh, url)#

Get release response data given a release url

jupyter_releaser.util.retry(cmd, **kwargs)#

Run a command with retries

jupyter_releaser.util.run(cmd, **kwargs)#

Run a command as a subprocess and get the output as a string

jupyter_releaser.util.upload_assets(gh, assets, release, auth)#

Upload assets to a release.