API introduction

Use HelixCommit programmatically in your Python applications

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

1. 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"))
   
2. 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
   )
   
3. Fetch commits

   commits = list(repo.iter_commits(commit_range))
   print(f"Found {len(commits)} commits")
   
4. 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={}
   )
   
5. 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