Feature request

Description

Python-semantic-release operates primarily as a CLI tool, which works well for standard CI/CD pipelines but limits integration with custom Python scripts and applications. This proposal adds a programmatic Python API allowing users to import and call semantic release functionality directly from code.

The API would expose a SemanticReleaseContext configuration object and functions for building release history, rendering changelogs and release notes, and computing the next version.

Use cases

Teams often want to post release notes to Slack, Discord, or other services after a release. Today this requires parsing CLI output or reading generated files. A programmatic API would let them call render_release_notes() and pass the result directly to their notification client.

Monorepo maintainers sometimes need custom release coordination beyond what the CLI supports. A programmatic API lets them orchestrate releases with Python scripts, calling core functions in whatever order their workflow requires.

Testing release configuration currently means mocking subprocess calls. With a programmatic API, teams can import functions directly and write unit tests that verify their commit parser produces expected version bumps.

Possible implementation

A SemanticReleaseContext class would encapsulate configuration, loadable from pyproject.toml or constructed with explicit parameters:

from semantic_release import SemanticReleaseContext

# Load from pyproject.toml
ctx = SemanticReleaseContext.from_config_file()

# Or construct directly
ctx = SemanticReleaseContext(
    repo_dir=Path("."),
    hvcs_client=Github(remote_url="https://github.com/owner/repo"),
    commit_parser=ConventionalCommitParser(),
    version_translator=VersionTranslator(),
)

Core functions would accept the context and return Python objects:

from semantic_release import (
    SemanticReleaseContext,
    build_release_history,
    render_release_notes,
    compute_next_version,
)

ctx = SemanticReleaseContext.from_config_file()
history = build_release_history(ctx)

# Post release notes to Slack
latest_version = list(history.released.keys())[0]
notes = render_release_notes(ctx, history, latest_version)
slack_client.post_message(channel="#releases", text=notes)

# Conditional logic before releasing
next_ver = compute_next_version(ctx)
if next_ver.major > current_version.major:
    require_manual_approval()

Existing approaches in the JS ecosystem

The JavaScript semantic-release package provides a programmatic API returning a result object with release information, commits, and changelog content.

Nx Release programmatic API exposes separate functions for versioning, changelog generation, and publishing through their programmatic API, allowing custom logic between phases.

Both recognize that releases involve special cases a CLI cannot fully address. A programmatic API lets users build exactly what they need.

Invoking the CLI via subprocess.run() is possible but has drawbacks: string parsing is fragile, intermediate results are inaccessible, exceptions become exit codes, and testing is harder. A native Python API provides proper types, meaningful exceptions, IDE integration, and composability with other tools.