pretty-release-notes 1.4.0__py3-none-any.whl

pretty_release_notes/__init__.py

@@ -0,0 +1,38 @@
+"""Pretty Release Notes - Transform GitHub release notes with AI."""
+
+# Public API exports for library usage
+from .api import ReleaseNotesBuilder, ReleaseNotesClient
+from .core.config import (
+	DatabaseConfig,
+	FilterConfig,
+	GitHubConfig,
+	LLMConfig,
+	OpenAIConfig,
+	ReleaseNotesConfig,
+)
+from .core.interfaces import (
+	CompositeProgressReporter,
+	NullProgressReporter,
+	ProgressEvent,
+	ProgressReporter,
+)
+
+__version__ = "1.4.0"
+
+__all__ = [
+	# Client classes
+	"ReleaseNotesBuilder",
+	"ReleaseNotesClient",
+	# Configuration
+	"ReleaseNotesConfig",
+	"GitHubConfig",
+	"LLMConfig",
+	"OpenAIConfig",
+	"DatabaseConfig",
+	"FilterConfig",
+	# Progress reporting
+	"ProgressReporter",
+	"ProgressEvent",
+	"NullProgressReporter",
+	"CompositeProgressReporter",
+]

pretty_release_notes/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running pretty_release_notes as a module."""
+
+from .main import app
+
+if __name__ == "__main__":
+	app()

pretty_release_notes/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters for integrating core abstractions with external systems."""

pretty_release_notes/adapters/cli_progress.py

@@ -0,0 +1,25 @@
+"""CLI adapter for progress reporting."""
+
+from ..core.interfaces import ProgressEvent, ProgressReporter
+from ..ui import CLI
+
+
+class CLIProgressReporter(ProgressReporter):
+	"""Adapt ProgressReporter interface to existing CLI class."""
+
+	def __init__(self, cli: CLI):
+		self.cli = cli
+
+	def report(self, event: ProgressEvent) -> None:
+		"""Route progress events to appropriate CLI methods."""
+		if event.type == "markdown":
+			self.cli.show_markdown_text(event.message)
+		elif event.type == "success":
+			self.cli.show_success(event.message)
+		elif event.type == "error":
+			self.cli.show_error(event.message)
+		elif event.type == "info":
+			self.cli.show_markdown_text(event.message)
+		elif event.type == "release_notes":
+			heading = event.metadata.get("heading", "Release Notes") if event.metadata else "Release Notes"
+			self.cli.show_release_notes(heading, event.message)

pretty_release_notes/api.py

@@ -0,0 +1,239 @@
+"""High-level API for library usage of pretty_release_notes."""
+
+from pathlib import Path
+
+from .core.config import (
+	DatabaseConfig,
+	FilterConfig,
+	GitHubConfig,
+	GroupingConfig,
+	LLMConfig,
+	ReleaseNotesConfig,
+)
+from .core.interfaces import NullProgressReporter, ProgressReporter
+from .generator import ReleaseNotesGenerator
+from .openai_client import DEFAULT_MODEL, ReasoningEffort
+
+
+class ReleaseNotesClient:
+	"""High-level client for generating release notes."""
+
+	def __init__(
+		self,
+		config: ReleaseNotesConfig,
+		progress_reporter: ProgressReporter | None = None,
+	):
+		self.config = config
+		self.progress_reporter = progress_reporter or NullProgressReporter()
+
+	def generate_release_notes(
+		self,
+		owner: str,
+		repo: str,
+		tag: str,
+		previous_tag_name: str | None = None,
+	) -> str:
+		"""Generate release notes for a repository and tag.
+
+		Args:
+			owner: Repository owner
+			repo: Repository name
+			tag: Git tag for the release
+			previous_tag_name: Optional previous tag to use as starting point
+
+		Returns:
+			Formatted release notes as markdown
+		"""
+		generator = ReleaseNotesGenerator(self.config, self.progress_reporter)
+		generator.initialize_repository(owner, repo)
+		return generator.generate(tag, previous_tag_name)
+
+	def update_github_release(
+		self,
+		owner: str,
+		repo: str,
+		tag: str,
+		notes: str,
+	) -> None:
+		"""Update release notes on GitHub.
+
+		Args:
+			owner: Repository owner
+			repo: Repository name
+			tag: Git tag for the release
+			notes: New release notes content
+		"""
+		generator = ReleaseNotesGenerator(self.config, self.progress_reporter)
+		generator.initialize_repository(owner, repo)
+		generator.update_on_github(notes, tag)
+
+
+class ReleaseNotesBuilder:
+	"""Builder pattern for constructing ReleaseNotesClient."""
+
+	def __init__(self):
+		self._github_token = None
+		self._llm_key = None
+		self._llm_model = DEFAULT_MODEL
+		self._max_patch_size = 10000
+		self._reasoning_effort = None
+		self._db_type = "sqlite"
+		self._db_name = "stored_lines"
+		self._db_read_enabled = True
+		self._db_write_enabled = True
+		self._exclude_types = set()
+		self._exclude_labels = set()
+		self._exclude_authors = set()
+		self._group_by_type = True
+		self._type_headings = {}
+		self._other_heading = "Other Changes"
+		self._prompt_path = Path("prompt.txt")
+		self._force_use_commits = False
+		self._progress_reporter = None
+
+	def with_github_token(self, token: str) -> "ReleaseNotesBuilder":
+		"""Set GitHub authentication token."""
+		self._github_token = token
+		return self
+
+	def with_llm(
+		self,
+		api_key: str,
+		model: str = DEFAULT_MODEL,
+		max_patch_size: int = 10000,
+		reasoning_effort: ReasoningEffort | None = None,
+	) -> "ReleaseNotesBuilder":
+		"""Set LLM configuration."""
+		self._llm_key = api_key
+		self._llm_model = model
+		self._max_patch_size = max_patch_size
+		self._reasoning_effort = reasoning_effort
+		return self
+
+	def with_openai(
+		self,
+		api_key: str,
+		model: str = DEFAULT_MODEL,
+		max_patch_size: int = 10000,
+		reasoning_effort: ReasoningEffort | None = None,
+	) -> "ReleaseNotesBuilder":
+		"""Backward-compatible alias for with_llm()."""
+		return self.with_llm(
+			api_key=api_key,
+			model=model,
+			max_patch_size=max_patch_size,
+			reasoning_effort=reasoning_effort,
+		)
+
+	def with_database(
+		self,
+		db_type: str = "sqlite",
+		db_name: str = "stored_lines",
+		no_read: bool = False,
+		no_write: bool = False,
+	) -> "ReleaseNotesBuilder":
+		"""Configure database for caching generated summaries."""
+		self._db_type = db_type
+		self._db_name = db_name
+		self._db_read_enabled = not no_read
+		self._db_write_enabled = not no_write
+		return self
+
+	def with_filters(
+		self,
+		exclude_types: set[str] | None = None,
+		exclude_labels: set[str] | None = None,
+		exclude_authors: set[str] | None = None,
+	) -> "ReleaseNotesBuilder":
+		"""Set filters for excluding specific types, labels, or authors."""
+		if exclude_types:
+			self._exclude_types = exclude_types
+		if exclude_labels:
+			self._exclude_labels = exclude_labels
+		if exclude_authors:
+			self._exclude_authors = exclude_authors
+		return self
+
+	def with_grouping(
+		self,
+		group_by_type: bool = True,
+		type_headings: dict[str, str] | None = None,
+		other_heading: str = "Other Changes",
+	) -> "ReleaseNotesBuilder":
+		"""Configure output grouping by conventional commit type.
+
+		Args:
+			group_by_type: Enable grouping by type
+			type_headings: Custom mapping of types to section headings
+			other_heading: Heading for uncategorized changes
+		"""
+		self._group_by_type = group_by_type
+		if type_headings:
+			self._type_headings = type_headings
+		self._other_heading = other_heading
+		return self
+
+	def with_prompt_file(self, path: Path) -> "ReleaseNotesBuilder":
+		"""Set custom prompt file path."""
+		self._prompt_path = path
+		return self
+
+	def with_force_commits(self, force: bool = True) -> "ReleaseNotesBuilder":
+		"""Force using commits even when PRs are available."""
+		self._force_use_commits = force
+		return self
+
+	def with_progress_reporter(self, reporter: ProgressReporter) -> "ReleaseNotesBuilder":
+		"""Set custom progress reporter."""
+		self._progress_reporter = reporter
+		return self
+
+	def _build_grouping_config(self) -> GroupingConfig:
+		"""Build grouping config, preserving defaults when no custom headings are set."""
+		if self._type_headings:
+			return GroupingConfig(
+				group_by_type=self._group_by_type,
+				type_headings=self._type_headings,
+				other_heading=self._other_heading,
+			)
+		return GroupingConfig(
+			group_by_type=self._group_by_type,
+			other_heading=self._other_heading,
+		)
+
+	def build(self) -> ReleaseNotesClient:
+		"""Build the client with configured options.
+
+		Raises:
+			ValueError: If required configuration is missing
+		"""
+		if not self._github_token:
+			raise ValueError("GitHub token is required")
+		if not self._llm_key:
+			raise ValueError("LLM API key is required")
+
+		config = ReleaseNotesConfig(
+			github=GitHubConfig(token=self._github_token),
+			llm=LLMConfig(
+				api_key=self._llm_key,
+				model=self._llm_model,
+				max_patch_size=self._max_patch_size,
+				reasoning_effort=self._reasoning_effort,
+			),
+			database=DatabaseConfig(
+				type=self._db_type,
+				name=self._db_name,
+				read_enabled=self._db_read_enabled,
+				write_enabled=self._db_write_enabled,
+			),
+			filters=FilterConfig(
+				exclude_change_types=self._exclude_types,
+				exclude_change_labels=self._exclude_labels,
+				exclude_authors=self._exclude_authors,
+			),
+			grouping=self._build_grouping_config(),
+			prompt_path=self._prompt_path,
+			force_use_commits=self._force_use_commits,
+		)
+
+		return ReleaseNotesClient(config, self._progress_reporter)

pretty_release_notes/core/__init__.py

@@ -0,0 +1 @@
+"""Core abstractions for pretty_release_notes."""

pretty_release_notes/core/config.py

@@ -0,0 +1,166 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ..openai_client import DEFAULT_MODEL, ReasoningEffort, normalize_reasoning_effort
+
+
+@dataclass
+class GitHubConfig:
+	token: str
+	owner: str | None = None
+
+	def __post_init__(self):
+		if not self.token:
+			raise ValueError("GitHub token is required")
+
+
+@dataclass
+class LLMConfig:
+	api_key: str
+	model: str = DEFAULT_MODEL
+	max_patch_size: int = 10000
+	reasoning_effort: ReasoningEffort | None = None
+
+	def __post_init__(self):
+		if not self.api_key:
+			raise ValueError("LLM API key is required")
+		self.reasoning_effort = normalize_reasoning_effort(self.reasoning_effort)
+
+
+OpenAIConfig = LLMConfig
+
+
+@dataclass
+class DatabaseConfig:
+	"""Database configuration for caching release note summaries.
+
+	Attributes:
+		type: Database backend type ("csv" or "sqlite")
+		name: Database filename (without extension). If relative, stores in ~/.pretty-release-notes/
+			If absolute path, stores at that exact location.
+		read_enabled: Whether to read cached summaries (CLI override; not in config files)
+		write_enabled: Whether to persist new summaries (CLI override; not in config files)
+	"""
+
+	type: str = "sqlite"
+	name: str = "stored_lines"
+	read_enabled: bool = True
+	write_enabled: bool = True
+
+	def __init__(
+		self,
+		type: str = "sqlite",
+		name: str = "stored_lines",
+		read_enabled: bool = True,
+		write_enabled: bool = True,
+		enabled: bool | None = None,
+	):
+		self.type = type
+		self.name = name
+		if enabled is not None:
+			self.read_enabled = enabled
+			self.write_enabled = enabled
+		else:
+			self.read_enabled = read_enabled
+			self.write_enabled = write_enabled
+		if self.type not in ("csv", "sqlite"):
+			raise ValueError(f"Invalid database type: {self.type}")
+
+	@property
+	def enabled(self) -> bool:
+		return self.read_enabled and self.write_enabled
+
+	@enabled.setter
+	def enabled(self, value: bool) -> None:
+		self.read_enabled = value
+		self.write_enabled = value
+
+
+@dataclass
+class FilterConfig:
+	exclude_change_types: set[str] = field(default_factory=set)
+	exclude_change_labels: set[str] = field(default_factory=set)
+	exclude_authors: set[str] = field(default_factory=set)
+
+
+@dataclass
+class GroupingConfig:
+	"""Configuration for grouping release notes output."""
+
+	group_by_type: bool = True
+	type_headings: dict[str, str] = field(
+		default_factory=lambda: {
+			"feat": "Features",
+			"fix": "Bug Fixes",
+			"perf": "Performance Improvements",
+			"docs": "Documentation",
+			"refactor": "Code Refactoring",
+			"test": "Tests",
+			"build": "Build System",
+			"ci": "CI/CD",
+			"chore": "Chores",
+			"style": "Style",
+			"revert": "Reverts",
+		}
+	)
+	other_heading: str = "Other Changes"
+	breaking_changes_heading: str = "Breaking Changes"
+
+	def get_heading(self, type_name: str | None) -> str:
+		"""Get the section heading for a given type."""
+		if not type_name:
+			return self.other_heading
+		return self.type_headings.get(type_name, self.other_heading)
+
+
+def _get_default_prompt_path() -> Path:
+	"""Get the default prompt.txt path from the package directory."""
+	# Get the directory where this config.py file is located
+	package_dir = Path(__file__).parent.parent
+	return package_dir / "prompt.txt"
+
+
+@dataclass(init=False)
+class ReleaseNotesConfig:
+	github: GitHubConfig
+	llm: LLMConfig
+	database: DatabaseConfig = field(default_factory=DatabaseConfig)
+	filters: FilterConfig = field(default_factory=FilterConfig)
+	grouping: GroupingConfig = field(default_factory=GroupingConfig)
+	prompt_path: Path = field(default_factory=_get_default_prompt_path)
+	force_use_commits: bool = False
+
+	def __init__(
+		self,
+		github: GitHubConfig,
+		llm: LLMConfig | None = None,
+		openai: LLMConfig | None = None,
+		database: DatabaseConfig | None = None,
+		filters: FilterConfig | None = None,
+		grouping: GroupingConfig | None = None,
+		prompt_path: Path | None = None,
+		force_use_commits: bool = False,
+	):
+		if llm is not None and openai is not None and llm != openai:
+			raise ValueError("Pass either llm or openai configuration, not both")
+
+		resolved_llm = llm or openai
+		if resolved_llm is None:
+			raise ValueError("LLM configuration is required")
+
+		self.github = github
+		self.llm = resolved_llm
+		self.database = database if database is not None else DatabaseConfig()
+		self.filters = filters if filters is not None else FilterConfig()
+		self.grouping = grouping if grouping is not None else GroupingConfig()
+		self.prompt_path = prompt_path if prompt_path is not None else _get_default_prompt_path()
+		self.force_use_commits = force_use_commits
+
+	@property
+	def openai(self) -> LLMConfig:
+		"""Backward-compatible alias for llm configuration."""
+		return self.llm
+
+	@openai.setter
+	def openai(self, value: LLMConfig) -> None:
+		self.llm = value

pretty_release_notes/core/config_loader.py

@@ -0,0 +1,221 @@
+import tomllib
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+from dotenv import dotenv_values
+
+from ..openai_client import DEFAULT_MODEL
+from .config import (
+	DatabaseConfig,
+	FilterConfig,
+	GitHubConfig,
+	GroupingConfig,
+	LLMConfig,
+	ReleaseNotesConfig,
+	_get_default_prompt_path,
+)
+
+
+class ConfigLoader(ABC):
+	@abstractmethod
+	def load(self) -> ReleaseNotesConfig:
+		"""Load configuration from source."""
+		pass
+
+
+class DictConfigLoader(ConfigLoader):
+	"""Load from dictionary (for programmatic usage)."""
+
+	def __init__(self, config_dict: dict[str, Any]):
+		self.config_dict = config_dict
+
+	def load(self) -> ReleaseNotesConfig:
+		llm_api_key = self.config_dict.get("llm_api_key", self.config_dict.get("openai_api_key"))
+		if llm_api_key is None:
+			raise KeyError("llm_api_key")
+
+		return ReleaseNotesConfig(
+			github=GitHubConfig(
+				token=self.config_dict["github_token"],
+				owner=self.config_dict.get("github_owner"),
+			),
+			llm=LLMConfig(
+				api_key=llm_api_key,
+				model=self.config_dict.get("llm_model", self.config_dict.get("openai_model", DEFAULT_MODEL)),
+				max_patch_size=self.config_dict.get("max_patch_size", 10000),
+				reasoning_effort=self.config_dict.get(
+					"llm_reasoning_effort",
+					self.config_dict.get(
+						"openai_reasoning_effort",
+						self.config_dict.get("reasoning_effort"),
+					),
+				),
+			),
+			database=DatabaseConfig(
+				type=self.config_dict.get("db_type", "sqlite"),
+				name=self.config_dict.get("db_name", "stored_lines"),
+				enabled=self.config_dict.get("use_db", True),
+			),
+			filters=FilterConfig(
+				exclude_change_types=set(self.config_dict.get("exclude_types", [])),
+				exclude_change_labels=set(self.config_dict.get("exclude_labels", [])),
+				exclude_authors=set(self.config_dict.get("exclude_authors", [])),
+			),
+			grouping=GroupingConfig(
+				group_by_type=self.config_dict.get("group_by_type", True),
+				**(
+					{}
+					if "type_headings" not in self.config_dict
+					else {"type_headings": self.config_dict["type_headings"]}
+				),
+				**(
+					{}
+					if "other_heading" not in self.config_dict
+					else {"other_heading": self.config_dict["other_heading"]}
+				),
+			),
+			prompt_path=Path(self.config_dict["prompt_path"])
+			if "prompt_path" in self.config_dict
+			else _get_default_prompt_path(),
+			force_use_commits=self.config_dict.get("force_use_commits", False),
+		)
+
+
+class EnvConfigLoader(ConfigLoader):
+	"""Load from .env file (backward compatibility)."""
+
+	def __init__(self, env_path: str = ".env"):
+		self.env_path = env_path
+
+	def load(self) -> ReleaseNotesConfig:
+		config = dotenv_values(self.env_path)
+
+		# Required fields
+		github_token = config["GH_TOKEN"]
+		llm_key = config.get("LLM_API_KEY") or config.get("OPENAI_API_KEY")
+
+		# Ensure github_token and llm_key are not None
+		if github_token is None:
+			raise ValueError("GH_TOKEN is required in .env file")
+		if llm_key is None:
+			raise ValueError("LLM_API_KEY is required in .env file")
+
+		return ReleaseNotesConfig(
+			github=GitHubConfig(token=github_token, owner=config.get("DEFAULT_OWNER")),
+			llm=LLMConfig(
+				api_key=llm_key,
+				model=config.get("LLM_MODEL") or config.get("OPENAI_MODEL") or DEFAULT_MODEL,
+				max_patch_size=int(config.get("MAX_PATCH_SIZE") or "10000"),
+				reasoning_effort=config.get("LLM_REASONING_EFFORT") or config.get("OPENAI_REASONING_EFFORT"),
+			),
+			database=DatabaseConfig(
+				type=config.get("DB_TYPE") or "sqlite",
+				name=config.get("DB_NAME") or "stored_lines",
+				enabled=True,
+			),
+			filters=FilterConfig(
+				exclude_change_types=self._parse_set(config.get("EXCLUDE_PR_TYPES") or ""),
+				exclude_change_labels=self._parse_set(config.get("EXCLUDE_PR_LABELS") or ""),
+				exclude_authors=self._parse_set(config.get("EXCLUDE_AUTHORS") or ""),
+			),
+			grouping=GroupingConfig(
+				group_by_type=(config.get("GROUP_BY_TYPE") or "true").lower() == "true",
+			),
+			prompt_path=(
+				Path(config["PROMPT_PATH"])
+				if "PROMPT_PATH" in config and config["PROMPT_PATH"] is not None
+				else _get_default_prompt_path()
+			),
+			force_use_commits=(config.get("FORCE_USE_COMMITS") or "false").lower() == "true",
+		)
+
+	def _parse_set(self, value: str) -> set[str]:
+		return set(value.split(",")) if value else set()
+
+
+class TomlConfigLoader(ConfigLoader):
+	"""Load from TOML file (default config format)."""
+
+	DEFAULT_CONFIG_PATH = Path.home() / ".pretty-release-notes" / "config.toml"
+
+	def __init__(self, config_path: Path | str | None = None):
+		"""Initialize TOML config loader.
+
+		Args:
+			config_path: Path to config file. If None, uses DEFAULT_CONFIG_PATH.
+		"""
+		if config_path is None:
+			self.config_path = self.DEFAULT_CONFIG_PATH
+		else:
+			self.config_path = Path(config_path)
+
+	def load(self) -> ReleaseNotesConfig:
+		"""Load configuration from TOML file.
+
+		Raises:
+			FileNotFoundError: If config file doesn't exist
+			ValueError: If required fields are missing or invalid
+		"""
+		if not self.config_path.exists():
+			raise FileNotFoundError(
+				f"Config file not found at {self.config_path}. "
+				f"Create it with the required fields or use --config-path to specify a different location."
+			)
+
+		with open(self.config_path, "rb") as f:
+			config = tomllib.load(f)
+
+		# Extract nested sections with defaults
+		github_config = config.get("github", {})
+		llm_config = {**config.get("openai", {}), **config.get("llm", {})}
+		database_config = config.get("database", {})
+		filters_config = config.get("filters", {})
+		grouping_config = config.get("grouping", {})
+
+		# Required fields
+		github_token = github_config.get("token")
+		llm_key = llm_config.get("api_key")
+
+		if not github_token:
+			raise ValueError("github.token is required in config file")
+		if not llm_key:
+			raise ValueError("llm.api_key is required in config file")
+
+		return ReleaseNotesConfig(
+			github=GitHubConfig(
+				token=github_token,
+				owner=github_config.get("owner"),
+			),
+			llm=LLMConfig(
+				api_key=llm_key,
+				model=llm_config.get("model", DEFAULT_MODEL),
+				max_patch_size=llm_config.get("max_patch_size", 10000),
+				reasoning_effort=llm_config.get("reasoning_effort"),
+			),
+			database=DatabaseConfig(
+				type=database_config.get("type", "sqlite"),
+				name=database_config.get("name", "stored_lines"),
+				enabled=database_config.get("enabled", True),
+			),
+			filters=FilterConfig(
+				exclude_change_types=set(filters_config.get("exclude_change_types", [])),
+				exclude_change_labels=set(filters_config.get("exclude_change_labels", [])),
+				exclude_authors=set(filters_config.get("exclude_authors", [])),
+			),
+			grouping=GroupingConfig(
+				group_by_type=grouping_config.get("group_by_type", True),
+				**(
+					{}
+					if "type_headings" not in grouping_config
+					else {"type_headings": grouping_config["type_headings"]}
+				),
+				**(
+					{}
+					if "other_heading" not in grouping_config
+					else {"other_heading": grouping_config["other_heading"]}
+				),
+			),
+			prompt_path=Path(config["prompt_path"]) if "prompt_path" in config else _get_default_prompt_path(),
+			force_use_commits=config.get("force_use_commits", False),
+		)