or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build.mdcheck.mdconfiguration.mdcreate.mdfragments.mdindex.mdproject.mdvcs.md
tile.json

tessl/pypi-towncrier

Building newsfiles for your project.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/towncrier@25.8.x

To install, run

npx @tessl/cli install tessl/pypi-towncrier@25.8.0

index.mddocs/

Towncrier

Towncrier is a utility to produce useful, summarized news files (changelogs) for your project. Rather than reading Git history or having one single file which developers all write to and produce merge conflicts, towncrier reads "news fragments" which contain information useful to end users.

Package Information

  • Package Name: towncrier
  • Language: Python
  • Installation: pip install towncrier

Core Imports

import towncrier

For programmatic usage:

from towncrier.build import __main as build_main
from towncrier.create import __main as create_main  
from towncrier.check import __main as check_main
from towncrier._settings import load_config_from_options, Config
from towncrier._builder import find_fragments, render_fragments, parse_newfragment_basename
from towncrier._project import get_version, get_project_name
from towncrier._writer import append_to_newsfile
from towncrier._vcs import remove_files, stage_newsfile, get_remote_branches

Basic Usage

Command Line Usage

Build a changelog from news fragments:

towncrier build

Create a new news fragment:

towncrier create 123.feature

Check for news fragments on a branch:

towncrier check --compare-with origin/main

Programmatic Usage

from towncrier.build import __main as build_main
from towncrier._settings import load_config_from_options

# Load configuration
base_directory, config = load_config_from_options(
    directory=None,  # Use current directory
    config_path=None  # Auto-detect config file
)

# Build changelog programmatically
build_main(
    draft=False,              # Write to files
    directory=None,           # Use current directory  
    config_file=None,         # Use auto-detected config
    project_name=None,        # Use config or auto-detect
    project_version=None,     # Use config or auto-detect
    project_date=None,        # Use current date
    answer_yes=True,          # Auto-confirm actions
    answer_keep=False         # Remove fragments after build
)

Architecture

Towncrier uses a modular architecture with these key components:

  • Fragment Discovery: Finds and parses news fragment files based on naming conventions
  • Template Rendering: Uses Jinja2 templates to format the final changelog output
  • VCS Integration: Supports Git, Mercurial, or no VCS for file management
  • Configuration System: TOML-based configuration with sensible defaults
  • Multi-format Support: Can generate RST, Markdown, or custom formatted output

The workflow involves creating individual fragment files for each change, then running the build command to combine them into a cohesive changelog entry.

Capabilities

Build Command

Build a combined news file from news fragments, with options for drafts, custom versions, and fragment management.

def __main(
    draft: bool,
    directory: str | None,
    config_file: str | None, 
    project_name: str | None,
    project_version: str | None,
    project_date: str | None,
    answer_yes: bool,
    answer_keep: bool
) -> None

Build Command

Create Command

Create new news fragments with customizable content, sections, and automatic editor integration.

def __main(
    ctx: click.Context,
    directory: str | None,
    config_path: str | None,
    filename: str,
    edit: bool | None,
    content: str,
    section: str | None
) -> None

Create Command

Check Command

Check for new fragments on a branch by comparing with a base branch and validating fragment requirements.

def __main(
    comparewith: str | None,
    directory: str | None,
    config_path: str | None,
    staged: bool
) -> None

Check Command

Fragment Processing

Core functionality for finding, parsing, and rendering news fragments with support for various formats and organization.

def find_fragments(
    base_directory: str,
    config: Config,
    strict: bool = False
) -> tuple[dict[str, dict[tuple[str, str, int], str]], list[tuple[str, str]]]

def render_fragments(
    template: str,
    issue_format: str | None,
    fragments: Mapping[str, Mapping[str, Mapping[str, Sequence[str]]]],
    definitions: Mapping[str, Mapping[str, Any]],
    underlines: Sequence[str],
    wrap: bool,
    versiondata: Mapping[str, str],
    top_underline: str = "=",
    all_bullets: bool = False,
    render_title: bool = True,
    md_header_level: int = 1
) -> str

Fragment Processing

Configuration Management

Load and manage towncrier configuration from TOML files with validation and defaults.

def load_config_from_options(
    directory: str | None,
    config_path: str | None
) -> tuple[str, Config]

class Config:
    sections: Mapping[str, str]
    types: Mapping[str, Mapping[str, Any]]
    template: str | tuple[str, str]
    start_string: str
    package: str
    package_dir: str
    single_file: bool
    filename: str
    directory: str | None
    version: str | None
    name: str
    title_format: str | Literal[False] 
    issue_format: str | None
    underlines: Sequence[str]
    wrap: bool
    all_bullets: bool
    orphan_prefix: str
    create_eof_newline: bool
    create_add_extension: bool
    ignore: list[str] | None
    issue_pattern: str

Configuration

Project Utilities

Extract project metadata like version and name from packages for automatic changelog generation.

def get_version(package_dir: str, package: str) -> str
def get_project_name(package_dir: str, package: str) -> str

Project Utilities

VCS Integration

Version control system integration for fragment management, branch operations, and news file staging.

def remove_files(base_directory: str, fragment_filenames: list[str]) -> None
def stage_newsfile(directory: str, filename: str) -> None  
def get_remote_branches(base_directory: str) -> list[str]
def get_default_compare_branch(
    base_directory: str, 
    branches: Container[str]
) -> str | None

VCS Integration