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

jupyter_releaser.python.start_local_pypi()#: 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.

jupyter_releaser.npm.extract_package(path)#: Get the package json info from the tarball

jupyter_releaser.npm.get_package_versions(version)#: Get the formatted list of npm package names and versions

jupyter_releaser.npm.handle_npm_config(npm_token)#: Handle npm_config

jupyter_releaser.npm.tag_workspace_packages()#: 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

jupyter_releaser.changelog.extract_current(changelog_path)#: Extract the current changelog entry

jupyter_releaser.changelog.extract_current_version(changelog_path)#: 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.

Parameters:

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.

Returns:

A formatted PR entry

Return type:

str

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.

Parameters:

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.

Returns:

A formatted changelog entry with markers

Return type:

str

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.

Parameters:

repo (str) – The GitHub owner/repo
auth (str) – The GitHub authorization token
changelog_path (str) – The changelog file path
dry_run (bool)

Returns:

Number of placeholders removed

Return type:

int

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

jupyter_releaser.util.compute_sha256(path)#: 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

jupyter_releaser.util.ensure_mock_github()#: 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.

jupyter_releaser.util.get_branch()#: Get the appropriate git branch

jupyter_releaser.util.get_default_branch()#: Get the default remote branch

jupyter_releaser.util.get_first_commit(source)#: 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

jupyter_releaser.util.get_mock_github_url()#: Get the mock github url.

jupyter_releaser.util.get_remote_name(dry_run)#: Get the appropriate remote git name.

jupyter_releaser.util.get_repo()#: Get the remote repo owner and name

jupyter_releaser.util.get_version()#: Get the current package version

jupyter_releaser.util.handle_since() → str#: Capture the “since” argument in case we add tags before checking changelog.

jupyter_releaser.util.is_prerelease(version)#: 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

jupyter_releaser.util.normalize_path(path)#: Normalize a path to use backslashes

jupyter_releaser.util.parse_release_url(release_url)#: Parse a release url into a regex match

jupyter_releaser.util.prepare_environment(fetch_draft_release=True)#: Prepare the environment variables, for use when running one of the action scripts.

jupyter_releaser.util.read_config()#: 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.