tessl/pypi-towncrier

Building newsfiles for your project.

Overview

Eval results

Files

Check Command

Name: tessl/pypi-towncrier
Author: tessl

The check command validates that appropriate news fragments exist for changes in a branch, helping enforce changelog requirements in development workflows.

Capabilities

Check Main Function

The primary entry point for checking fragment requirements.

def __main(
    comparewith: str | None,
    directory: str | None,
    config_path: str | None,
    staged: bool
) -> None:
    """
    Check for new fragments on a branch.
    
    Args:
        comparewith: Branch to compare against (None for auto-detection)
        directory: Directory to check in (None for current directory)
        config_path: Path to custom configuration file
        staged: Whether to include staged files in the comparison
        
    Exits:
        0: No fragments required or fragments found
        1: Fragments required but missing
    """

CLI Entry Point

The Click-decorated command-line interface for the check command.

def _main(
    compare_with: str | None,
    directory: str | None,
    config: str | None,
    staged: bool
) -> None:
    """
    Check for new fragments on a branch.
    
    Compares current branch against a base branch to determine if 
    news fragments are required for the changes made.
    """

Branch Comparison Logic

Default Branch Detection

The check command automatically detects the comparison branch using this priority:

Explicit --compare-with parameter
origin/main if it exists
origin/master if it exists
upstream/main if it exists
upstream/master if it exists
First available remote branch

File Change Analysis

The command analyzes changed files to determine if fragments are needed:

Compares current branch against the base branch
Optionally includes staged changes
Excludes fragment files themselves from requiring fragments
Uses VCS commands (git diff, hg diff) for file listing

Usage Examples

Basic Branch Check

from towncrier.check import __main as check_main

# Check against default branch
check_main(
    comparewith=None,  # Auto-detect base branch
    directory=None,    # Current directory
    config_path=None,  # Auto-detect config
    staged=False       # Don't include staged files
)

Custom Branch Comparison

# Check against specific branch with staged files
check_main(
    comparewith="develop",
    directory="/path/to/project",
    config_path="custom-towncrier.toml",
    staged=True  # Include staged changes
)

Command Line Usage

# Basic check against default branch
towncrier check

# Check against specific branch
towncrier check --compare-with develop

# Include staged files in check
towncrier check --staged

# Check in specific directory
towncrier check --dir /path/to/project --config custom.toml

# Check feature branch against main
towncrier check --compare-with origin/main

VCS Integration

Git Support

For Git repositories, the check command:

# Git-specific functions from towncrier._git
def get_remote_branches(base_directory: str) -> list[str]:
    """Get list of remote branches."""

def list_changed_files_compared_to_branch(
    base_directory: str,
    branch: str, 
    staged: bool
) -> list[str]:
    """List files changed compared to branch."""

def get_default_compare_branch(branches: Container[str]) -> str | None:
    """Get default branch for comparison."""

Mercurial Support

For Mercurial repositories:

# Mercurial-specific functions from towncrier._hg  
def get_remote_branches(base_directory: str) -> list[str]:
    """Get list of remote branches."""

def list_changed_files_compared_to_branch(
    base_directory: str,
    branch: str,
    staged: bool  
) -> list[str]:
    """List files changed compared to branch."""

def get_default_compare_branch(branches: Container[str]) -> str | None:
    """Get default branch for comparison."""

No VCS Support

For projects without version control:

# No-VCS fallback functions from towncrier._novcs
def get_remote_branches(base_directory: str) -> list[str]:
    """Return empty list (no branches)."""

def list_changed_files_compared_to_branch(
    base_directory: str,
    branch: str,
    staged: bool
) -> list[str]:
    """Return empty list (no changes detectable)."""

Fragment Detection

Fragment File Recognition

The check command identifies fragment files using:

Configured fragment directory locations
Fragment type extensions from configuration
Section-based fragment organization
Ignore patterns from configuration

Validation Logic

# Pseudo-code for fragment validation
if no_files_changed:
    exit(0)  # No fragments required
    
changed_files = get_changed_files(branch, staged)
fragment_files = find_fragments(directory, config)

if has_required_changes(changed_files) and not fragment_files:
    exit(1)  # Fragments required but missing
else:
    exit(0)  # Requirements satisfied

Configuration Options

The check command uses these configuration values:

directory: Fragment directory location
package_dir: Package directory for fragment resolution
package: Package name for fragment location
types: Fragment type definitions for recognition
sections: Section configuration for multi-section projects
ignore: Patterns for files that don't require fragments

Error Handling

The check command handles these scenarios:

CalledProcessError: VCS command failures (git/hg errors)
ConfigError: Invalid or missing configuration
Branch detection failure: No suitable comparison branch found
Permission errors: Cannot access repository or files
Network errors: Cannot fetch remote branch information

CI Integration

Common usage patterns in continuous integration:

# In GitHub Actions, GitLab CI, etc.
towncrier check --compare-with ${{ github.event.pull_request.base.ref }}

# In pre-commit hooks
towncrier check --staged

# For feature branch workflows
towncrier check --compare-with origin/develop

Install with Tessl CLI