Skip to main content
The Python API gives you full control over the release note generation process, allowing custom workflows and integration with other tools.

​
When to use the Python API

Custom automation

Build custom release workflows tailored to your team’s needs

Integration

Integrate release notes into existing Python applications

Advanced customization

Customize formatting, filtering, and processing beyond CLI options

Programmatic control

Generate notes from within your application or script

​
Quick example

Here’s a minimal example to get you started: 
from datetime import datetime
from pathlib import Path
from helixcommit.changelog import ChangelogBuilder
from helixcommit.formatters.markdown import render_markdown
from helixcommit.git_client import CommitRange, GitRepository

# Initialize repository
repo = GitRepository(Path("."))

# Define commit range
commit_range = CommitRange(since="v1.0.0", until="v2.0.0")

# Get commits
commits = list(repo.iter_commits(commit_range))

# Build changelog
builder = ChangelogBuilder(include_scopes=True)
changelog = builder.build(
    version="v2.0.0",
    release_date=datetime.now(),
    commits=commits,
    commit_prs={},
    pr_index={}
)

# Render to markdown
markdown = render_markdown(changelog)
print(markdown)
This example generates release notes for commits between two tags without any external dependencies.

​
Core modules

git_client

Interface with Git repositories and commit history

changelog

Build and structure changelog data

formatters

Render changelogs in different formats

Python API

Complete API reference and examples

​
Installation

Install HelixCommit via pip: 
pip install helixcommit
Import the modules you need: 
# Core modules
from helixcommit.git_client import GitRepository, CommitRange
from helixcommit.changelog import ChangelogBuilder
from helixcommit.formatters import markdown, html, text

# Advanced features
from helixcommit.github_client import GitHubClient, GitHubSettings
from helixcommit.summarizer import PromptEngineeredSummarizer
from helixcommit.models import Changelog, CommitInfo

​
Basic workflow

Initialize Git repository

from pathlib import Path
from helixcommit.git_client import GitRepository

repo = GitRepository(Path("."))  # Current directory
# or
repo = GitRepository(Path("/path/to/repo"))

Define commit range

from helixcommit.git_client import CommitRange

# Between tags
commit_range = CommitRange(since="v1.0.0", until="v2.0.0")

# Unreleased changes
commit_range = CommitRange(since="v1.0.0", until="HEAD")

# With filtering
commit_range = CommitRange(
    since="v1.0.0",
    until="HEAD",
    include_merges=False,
    max_count=100
)

Fetch commits

commits = list(repo.iter_commits(commit_range))
print(f"Found {len(commits)} commits")

Build changelog

from datetime import datetime
from helixcommit.changelog import ChangelogBuilder

builder = ChangelogBuilder(include_scopes=True)
changelog = builder.build(
    version="v2.0.0",
    release_date=datetime.now(),
    commits=commits,
    commit_prs={},
    pr_index={}
)

Render output

from helixcommit.formatters.markdown import render_markdown

# Generate markdown
output = render_markdown(changelog)
print(output)

# Save to file
Path("RELEASE_NOTES.md").write_text(output)

​
Advanced features

​
GitHub integration

Enrich changelogs with pull request data: 
from helixcommit.github_client import GitHubClient, GitHubSettings

# Initialize GitHub client
settings = GitHubSettings(
    owner="username",
    repo="repository",
    token="ghp_..."  # Optional, improves rate limits
)
client = GitHubClient(settings)

# Fetch PR data
pr_index = {}
commit_prs = {}

for commit in commits:
    if commit.pr_number:
        pr = client.get_pull_request(commit.pr_number)
        if pr:
            pr_index[commit.pr_number] = pr

# Use enriched data in changelog
changelog = builder.build(
    version="v2.0.0",
    release_date=datetime.now(),
    commits=commits,
    commit_prs=commit_prs,
    pr_index=pr_index
)

​
AI summarization

Add AI-powered summaries: 
from helixcommit.summarizer import PromptEngineeredSummarizer

# Initialize AI summarizer
summarizer = PromptEngineeredSummarizer(
    api_key="sk-...",
    model="gpt-4o-mini",
    cache_path=Path(".cache/summaries.json"),
    domain_scope="software release notes",
    expert_roles=["Product Manager", "Tech Lead"],
    rag_backend="simple"
)

# Use with changelog builder
builder = ChangelogBuilder(
    summarizer=summarizer,
    include_scopes=True
)

# AI summaries are automatically generated
changelog = builder.build(
    version="v2.0.0",
    release_date=datetime.now(),
    commits=commits,
    commit_prs={},
    pr_index={}
)

​
Custom formatting

Create custom output formatters: 
from helixcommit.models import Changelog

def custom_formatter(changelog: Changelog) -> str:
    """Generate custom release notes format."""
    lines = [
        f"# Release {changelog.version}",
        f"Released: {changelog.release_date.strftime('%Y-%m-%d')}",
        ""
    ]
    
    for section in changelog.sections:
        lines.append(f"## {section.title}")
        for item in section.items:
            lines.append(f"- {item.description} ({item.commit_sha[:7]})")
        lines.append("")
    
    return "\n".join(lines)

# Use custom formatter
output = custom_formatter(changelog)

​
Type hints and IDE support

HelixCommit is fully typed with type hints for excellent IDE support: 
from helixcommit.git_client import GitRepository, CommitRange
from helixcommit.models import CommitInfo, Changelog
from typing import List

def generate_notes(repo_path: str, since: str, until: str) -> str:
    """Generate release notes with full type safety."""
    repo: GitRepository = GitRepository(Path(repo_path))
    commit_range: CommitRange = CommitRange(since=since, until=until)
    commits: List[CommitInfo] = list(repo.iter_commits(commit_range))
    
    # IDE provides autocomplete and type checking
    builder = ChangelogBuilder()
    changelog: Changelog = builder.build(
        version=until,
        release_date=datetime.now(),
        commits=commits
    )
    
    return render_markdown(changelog)

​
Error handling

Handle errors gracefully: 
from helixcommit.git_client import GitRepository
from helixcommit.github_client import GitHubApiError, GitHubRateLimitError

try:
    # Initialize repository
    repo = GitRepository(Path("/path/to/repo"))
    commits = list(repo.iter_commits(commit_range))
    
    # GitHub operations
    client = GitHubClient(settings)
    pr = client.get_pull_request(123)
    
except FileNotFoundError:
    print("Error: Git repository not found")
except GitHubRateLimitError as e:
    print(f"Rate limit exceeded. Resets at: {e.reset_time}")
except GitHubApiError as e:
    print(f"GitHub API error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

​
Next steps

Python API reference

Complete API documentation

Git client

Working with Git repositories

Changelog builder

Building and structuring changelogs

Formatters

Rendering output in different formats