tessl/pypi-towncrier

Building newsfiles for your project.

Overview

Eval results

Files

Create Command

Name: tessl/pypi-towncrier
Author: tessl

The create command generates new news fragment files with customizable content, automatic filename handling, and optional editor integration.

Capabilities

Create Main Function

The primary entry point for creating news fragments.

def __main(
    ctx: click.Context,
    directory: str | None,
    config_path: str | None,
    filename: str,
    edit: bool | None,
    content: str,
    section: str | None
) -> None:
    """
    Create a new news fragment file.
    
    Args:
        ctx: Click context for CLI operations
        directory: Directory to create fragment in (None for current directory)
        config_path: Path to custom configuration file
        filename: Base filename for the fragment (can be empty for interactive)
        edit: Whether to open editor for content (None for config default)
        content: Fragment content text
        section: Section subdirectory to create fragment in
    """

CLI Entry Point

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

def _main(
    ctx: click.Context,
    directory: str | None,
    config: str | None,
    filename: str,
    edit: bool | None,
    content: str,
    section: str | None
) -> None:
    """
    Create a new news fragment.
    
    If FILENAME is not provided, you'll be prompted to create it.
    
    Standard fragment types by extension:
    - .feature - a new feature
    - .bugfix - a bug fix  
    - .doc - a documentation improvement
    - .removal - a deprecation or removal of public API
    - .misc - an issue has been closed, but not of interest to users
    
    If the FILENAME base is just '+' (to create a fragment not tied to an
    issue), it will be appended with a random hex string.
    """

Content Input Function

Helper for getting fragment content from user input.

def _get_news_content_from_user(message: str, extension: str = "") -> str:
    """
    Get fragment content from user via editor or input prompt.
    
    Args:
        message: Prompt message for the user
        extension: File extension for temporary editor file
        
    Returns:
        str: The content provided by the user
    """

Fragment Types

Towncrier supports several standard fragment types identified by file extension:

Standard Types

# Default fragment types
FRAGMENT_TYPES = {
    "feature": "Features",
    "bugfix": "Bugfixes", 
    "doc": "Improved Documentation",
    "removal": "Deprecations and Removals",
    "misc": "Misc"
}

Fragment Naming Convention

Fragment files follow the pattern: {issue}.{type}[.{counter}]

issue: Issue number, identifier, or '+' for orphan fragments
type: One of the configured fragment types (feature, bugfix, etc.)
counter: Optional counter for multiple fragments of same type/issue

Usage Examples

Basic Fragment Creation

from towncrier.create import __main as create_main
import click

ctx = click.Context(click.Command('create'))

# Create a feature fragment
create_main(
    ctx=ctx,
    directory=None,
    config_path=None,
    filename="123.feature",
    edit=False,
    content="Added new user authentication system",
    section=None
)

Interactive Fragment Creation

# Create fragment with editor integration
create_main(
    ctx=ctx,
    directory="/path/to/project",
    config_path="custom-towncrier.toml",
    filename="456.bugfix",
    edit=True,  # Opens editor for content
    content="Add your info here",  # Default content
    section="auth"  # Create in auth section subdirectory
)

Orphan Fragment

# Create fragment not tied to specific issue
create_main(
    ctx=ctx,
    directory=None,
    config_path=None,
    filename="+.misc",  # '+' creates orphan with random suffix
    edit=False,
    content="Updated development dependencies",
    section=None
)

Command Line Usage

# Create basic feature fragment
towncrier create 123.feature

# Create with custom content
towncrier create 456.bugfix --content "Fixed memory leak in parser"

# Create and open editor
towncrier create 789.doc --edit

# Create in specific directory and section
towncrier create 101.feature --dir /path/to/project --section api

# Create orphan fragment
towncrier create +.misc --content "Updated CI configuration"

# Interactive creation (prompts for filename)
towncrier create