tessl/pypi-hatchling

Modern, extensible Python build backend implementing PEP 517/660 standards with plugin architecture.

—

Pending

Overview

Eval results

Files

Builder System

Name: tessl/pypi-hatchling
Author: tessl

Comprehensive builder classes for creating different types of Python distributions with extensible configuration and plugin support. The builder system provides programmatic access to hatchling's build functionality.

Capabilities

Source Distribution Builder

Creates source distributions containing all source files needed to build the project.

class SdistBuilder(BuilderInterface):
    def __init__(
        self,
        root: str,
        plugin_manager: PluginManager | None = None,
        config: dict | None = None,
        metadata: ProjectMetadata | None = None,
        app: Application | None = None
    ):
        """
        Initialize source distribution builder.
        
        Args:
            root: Project root directory path
            plugin_manager: Optional plugin manager instance
            config: Optional builder configuration
            metadata: Optional project metadata instance
            app: Optional application context
        """
    
    def build(
        self, 
        *, 
        directory: str | None = None, 
        versions: list[str] | None = None,
        hooks_only: bool | None = None,
        clean: bool | None = None,
        clean_hooks_after: bool | None = None,
        clean_only: bool | None = False
    ) -> Generator[str, None, None]:
        """
        Build source distributions.
        
        Args:
            directory: Output directory for built distributions (default: "dist")
            versions: List of version types to build (default: ["standard"])
            hooks_only: Whether to run only build hooks
            clean: Whether to clean build directory before building
            clean_hooks_after: Whether to clean hooks after building
            clean_only: Whether to only clean without building
            
        Yields:
            str: Paths to built distribution files
        """
    
    def get_version_api(self) -> dict[str, Callable]:
        """Get version API mapping of version names to callable builders."""

Wheel Builder

Creates wheel distributions (.whl files) containing compiled bytecode and data files.

class WheelBuilder(BuilderInterface):
    def __init__(
        self,
        root: str,
        plugin_manager: PluginManager | None = None,
        config: dict | None = None,
        metadata: ProjectMetadata | None = None,
        app: Application | None = None
    ):
        """
        Initialize wheel builder.
        
        Args:
            root: Project root directory path
            plugin_manager: Optional plugin manager instance
            config: Optional builder configuration
            metadata: Optional project metadata instance
            app: Optional application context
        """
    
    def build(self, *, directory: str = "dist", versions: list[str] | None = None) -> Iterator[str]:
        """
        Build wheel distributions.
        
        Args:
            directory: Output directory for built distributions
            versions: List of version types to build (["standard", "editable"])
            
        Yields:
            str: Paths to built distribution files
        """
    
    def get_version_api(self) -> dict[str, Callable]:
        """Get version API mapping of version names to callable builders."""
    
    def get_version_tags(self) -> list[str]:
        """Get wheel version tags for this builder."""

Binary Builder

Base class for binary distribution builders with cross-platform support.

class BinaryBuilder(BuilderInterface):
    def __init__(
        self,
        root: str,
        plugin_manager: PluginManager | None = None,
        config: dict | None = None,
        metadata: ProjectMetadata | None = None,
        app: Application | None = None
    ):
        """
        Initialize binary builder.
        
        Args:
            root: Project root directory path
            plugin_manager: Optional plugin manager instance
            config: Optional builder configuration
            metadata: Optional project metadata instance
            app: Optional application context
        """
    
    def build(self, *, directory: str = "dist", versions: list[str] | None = None) -> Iterator[str]:
        """
        Build binary distributions.
        
        Args:
            directory: Output directory for built distributions
            versions: List of version types to build
            
        Yields:
            str: Paths to built distribution files
        """

Application Builder

Specialized builder for creating standalone application distributions.

class AppBuilder(BinaryBuilder):
    """Application builder extending binary builder functionality."""

Custom Builder

Generic custom builder for plugin-defined builders.

class CustomBuilder(Generic[PluginManagerBound]):
    def __init__(self, builder: type[BuilderInterface], plugin_manager: PluginManagerBound):
        """
        Initialize custom builder with plugin-defined builder class.
        
        Args:
            builder: Builder class from plugin
            plugin_manager: Plugin manager instance
        """

Builder Configuration

Builder Config Base Class

class BuilderConfig:
    def __init__(
        self,
        root: str,
        plugin_name: str,
        config: dict,
        metadata: ProjectMetadata,
        plugin_manager: PluginManager,
        target_config: dict | None = None,
        app: Application | None = None
    ):
        """
        Base configuration class for all builders.
        
        Args:
            root: Project root directory
            plugin_name: Name of the builder plugin
            config: Builder configuration dictionary
            metadata: Project metadata instance
            plugin_manager: Plugin manager instance
            target_config: Optional target-specific configuration
            app: Optional application context
        """
    
    @property
    def root(self) -> str:
        """Project root directory."""
    
    @property
    def plugin_name(self) -> str:
        """Builder plugin name."""
    
    @property
    def config(self) -> dict:
        """Builder configuration."""
    
    @property
    def metadata(self) -> ProjectMetadata:
        """Project metadata."""
    
    @property
    def dependencies(self) -> list[str]:
        """Builder dependencies."""

Specialized Configuration Classes

class SdistBuilderConfig(BuilderConfig):
    """Configuration for source distribution builder."""

class WheelBuilderConfig(BuilderConfig):
    """Configuration for wheel builder."""

class BinaryBuilderConfig(BuilderConfig):
    """Configuration for binary builders."""

File Handling

Included Files

class IncludedFile:
    def __init__(self, path: str, source_path: str, distribution_path: str):
        """
        Represents a file included in distributions.
        
        Args:
            path: Relative path within distribution
            source_path: Absolute path to source file
            distribution_path: Path within distribution archive
        """
    
    path: str
    source_path: str
    distribution_path: str

Archive Management

class SdistArchive:
    def __init__(self, name: str, *, reproducible: bool):
        """
        Source distribution archive creation.
        
        Args:
            name: Archive name
            reproducible: Whether to create reproducible archives
        """
    
    def create_file(self, contents: str | bytes, *relative_paths: str) -> None:
        """Create a file in the archive."""
    
    def add_file(self, path: str, *, uname: str = "root", gname: str = "root") -> None:
        """Add an existing file to the archive."""

class WheelArchive:
    def __init__(self, path: str, *, reproducible: bool):
        """
        Wheel archive creation.
        
        Args:
            path: Path to wheel file
            reproducible: Whether to create reproducible archives
        """
    
    def write_file(self, path: str, contents: str | bytes) -> None:
        """Write a file to the wheel."""
    
    def add_file(self, path: str, archive_path: str) -> None:
        """Add an existing file to the wheel."""

Usage Examples

Basic Builder Usage

import os
from hatchling.builders.wheel import WheelBuilder
from hatchling.builders.sdist import SdistBuilder

# Create builders
project_root = os.getcwd()
wheel_builder = WheelBuilder(project_root)
sdist_builder = SdistBuilder(project_root)

# Build distributions
wheel_paths = list(wheel_builder.build(directory="dist"))
sdist_paths = list(sdist_builder.build(directory="dist"))

print(f"Built wheels: {wheel_paths}")
print(f"Built sdists: {sdist_paths}")

With Custom Configuration

from hatchling.builders.wheel import WheelBuilder
from hatchling.metadata.core import ProjectMetadata
from hatchling.plugin.manager import PluginManager

# Load project metadata
metadata = ProjectMetadata(os.getcwd())

# Create plugin manager
plugin_manager = PluginManager(metadata)

# Custom configuration
config = {
    "include": ["src/**/*.py"],
    "exclude": ["**/*test*.py"],
    "dev-mode-dirs": ["src"]
}

# Create builder with custom config
builder = WheelBuilder(
    root=os.getcwd(),
    plugin_manager=plugin_manager,
    config=config,
    metadata=metadata
)

# Build with specific versions
wheel_paths = list(builder.build(
    directory="dist",
    versions=["standard", "editable"]
))

Accessing Builder Information

# Get version API information
version_api = builder.get_version_api()
print(f"Supported versions: {version_api}")

# For wheel builders, get version tags
if hasattr(builder, 'get_version_tags'):
    tags = builder.get_version_tags()
    print(f"Wheel tags: {tags}")

# Access builder configuration
config = builder.config
print(f"Dependencies: {config.dependencies}")
print(f"Root directory: {config.root}")

Builder Interface

All builders implement the BuilderInterface protocol:

class BuilderInterface(ABC, Generic[BuilderConfigBound, PluginManagerBound]):
    def build(self, *, directory: str = "dist", versions: list[str] | None = None) -> Iterator[str]:
        """Build distributions and yield paths to built files."""
    
    def get_version_api(self) -> dict[str, Callable]:
        """Get version API mapping of version names to callable builders."""
    
    def iter_build_targets(self, versions: list[str]) -> Iterator[tuple[str, str]]:
        """Iterate over build targets for given versions."""

Platform-Specific Features

macOS Platform Tags

def process_macos_plat_tag(plat: str, /, *, compat: bool) -> str:
    """
    Process macOS platform tags for wheel compatibility.
    
    Args:
        plat: Platform tag string
        compat: Whether to use compatibility mode
        
    Returns:
        str: Processed platform tag
    """

This builder system provides the foundation for hatchling's flexible and extensible build functionality, supporting various distribution types and custom build workflows through its plugin architecture.

Install with Tessl CLI