tessl/pypi-poetry

Python dependency management and packaging made easy.

—

Pending

Overview

Eval results

Files

Build System

Name: tessl/pypi-poetry
Author: tessl

PEP 517/518 compliant build backend for creating wheel and source distributions. Integrates with Python packaging standards for distribution creation and publishing workflows.

Capabilities

Build Backend API

Poetry's PEP 517/518 compliant build backend for creating Python distributions.

def build_wheel(wheel_directory: str, config_settings: dict = None, 
               metadata_directory: str = None) -> str:
    """
    Build wheel distribution.
    
    Args:
        wheel_directory: Directory to place the wheel
        config_settings: Build configuration settings
        metadata_directory: Directory containing prepared metadata
        
    Returns:
        Filename of the built wheel
        
    Raises:
        BuildError: If wheel building fails
    """

def build_sdist(sdist_directory: str, config_settings: dict = None) -> str:
    """
    Build source distribution.
    
    Args:
        sdist_directory: Directory to place the source distribution
        config_settings: Build configuration settings
        
    Returns:
        Filename of the built source distribution
        
    Raises:
        BuildError: If source distribution building fails
    """

def get_requires_for_build_wheel(config_settings: dict = None) -> list:
    """
    Get build requirements for wheel building.
    
    Args:
        config_settings: Build configuration settings
        
    Returns:
        List of build requirement specifications
    """

def get_requires_for_build_sdist(config_settings: dict = None) -> list:
    """
    Get build requirements for source distribution building.
    
    Args:
        config_settings: Build configuration settings
        
    Returns:
        List of build requirement specifications
    """

def prepare_metadata_for_build_wheel(metadata_directory: str, 
                                   config_settings: dict = None) -> str:
    """
    Prepare wheel metadata without building the wheel.
    
    Args:
        metadata_directory: Directory to place metadata
        config_settings: Build configuration settings
        
    Returns:
        Name of the prepared metadata directory
    """

Usage Example

from poetry.masonry import api

# Build wheel distribution
wheel_filename = api.build_wheel("dist/")
print(f"Built wheel: {wheel_filename}")

# Build source distribution
sdist_filename = api.build_sdist("dist/")
print(f"Built source distribution: {sdist_filename}")

# Get build requirements
wheel_reqs = api.get_requires_for_build_wheel()
sdist_reqs = api.get_requires_for_build_sdist()

print(f"Wheel build requirements: {wheel_reqs}")
print(f"Source build requirements: {sdist_reqs}")

# Prepare metadata only
metadata_dir = api.prepare_metadata_for_build_wheel("build/")
print(f"Prepared metadata in: {metadata_dir}")

Build Configuration

Configuration options for customizing the build process.

class BuildConfig:
    """
    Build configuration and options.
    
    Manages build settings, file inclusion/exclusion,
    and build-time customizations.
    """
    
    def __init__(self, config_settings: dict = None):
        """
        Initialize build configuration.
        
        Args:
            config_settings: Build configuration settings
        """
    
    @property
    def include_patterns(self) -> list:
        """File patterns to include in distribution."""
    
    @property
    def exclude_patterns(self) -> list:
        """File patterns to exclude from distribution."""
    
    @property
    def build_directory(self) -> Path:
        """Build output directory."""
    
    def should_include(self, file_path: Path) -> bool:
        """
        Check if file should be included in distribution.
        
        Args:
            file_path: Path to check
            
        Returns:
            True if file should be included
        """
    
    def get_build_requirements(self) -> list:
        """
        Get build requirements for current configuration.
        
        Returns:
            List of build requirement specifications
        """

Package Building

High-level package building utilities and orchestration.

class PackageBuilder:
    """
    High-level package building orchestration.
    
    Handles building packages with dependency resolution,
    file collection, and distribution creation.
    """
    
    def __init__(self, poetry: Poetry, env: Env, io = None):
        """
        Initialize package builder.
        
        Args:
            poetry: Poetry instance
            env: Build environment
            io: IO interface
        """
    
    def build(self, format_: str = "wheel", target_dir: Path = None) -> Path:
        """
        Build package in specified format.
        
        Args:
            format_: Distribution format ("wheel" or "sdist")
            target_dir: Target directory for built package
            
        Returns:
            Path to built package
        """
    
    def build_all(self, target_dir: Path = None) -> list[Path]:
        """
        Build all distribution formats.
        
        Args:
            target_dir: Target directory for built packages
            
        Returns:
            List of paths to built packages
        """
    
    def get_metadata(self) -> dict:
        """
        Get package metadata for distribution.
        
        Returns:
            Package metadata dictionary
        """
    
    def collect_files(self) -> list[Path]:
        """
        Collect files to include in distribution.
        
        Returns:
            List of file paths to include
        """

Usage Example

from poetry.masonry.builders.package_builder import PackageBuilder
from poetry.factory import Factory
from poetry.utils.env import EnvManager

# Create Poetry instance and environment
poetry = Factory().create_poetry()
env_manager = EnvManager(poetry.file.parent)
env = env_manager.create_venv()

# Create package builder
builder = PackageBuilder(poetry, env)

# Build wheel
wheel_path = builder.build("wheel", target_dir=Path("dist"))
print(f"Built wheel: {wheel_path}")

# Build source distribution
sdist_path = builder.build("sdist", target_dir=Path("dist"))
print(f"Built source distribution: {sdist_path}")

# Build all formats
all_builds = builder.build_all(target_dir=Path("dist"))
for build_path in all_builds:
    print(f"Built: {build_path}")

Wheel Building

Specific utilities for wheel distribution creation.

class WheelBuilder:
    """
    Wheel distribution builder.
    
    Handles creation of wheel (.whl) distributions with
    proper metadata, file organization, and compression.
    """
    
    def __init__(self, poetry: Poetry):
        """
        Initialize wheel builder.
        
        Args:
            poetry: Poetry instance
        """
    
    def build(self, target_dir: Path) -> Path:
        """
        Build wheel distribution.
        
        Args:
            target_dir: Target directory
            
        Returns:
            Path to built wheel file
        """
    
    def get_wheel_filename(self) -> str:
        """
        Get wheel filename based on package metadata.
        
        Returns:
            Wheel filename
        """
    
    def write_metadata(self, wheel_dir: Path) -> None:
        """
        Write wheel metadata files.
        
        Args:
            wheel_dir: Wheel build directory
        """

Source Distribution Building

Utilities for source distribution creation.

class SdistBuilder:
    """
    Source distribution builder.
    
    Handles creation of source distributions (.tar.gz) with
    proper file inclusion and packaging.
    """
    
    def __init__(self, poetry: Poetry):
        """
        Initialize source distribution builder.
        
        Args:
            poetry: Poetry instance
        """
    
    def build(self, target_dir: Path) -> Path:
        """
        Build source distribution.
        
        Args:
            target_dir: Target directory
            
        Returns:
            Path to built source distribution
        """
    
    def get_sdist_filename(self) -> str:
        """
        Get source distribution filename.
        
        Returns:
            Source distribution filename
        """
    
    def collect_source_files(self) -> list[Path]:
        """
        Collect source files for distribution.
        
        Returns:
            List of source file paths
        """

Build Environment

Specialized build environment management for package building.

def create_build_environment(poetry: Poetry, env: Env, io = None) -> Env:
    """
    Create isolated build environment.
    
    Args:
        poetry: Poetry instance
        env: Base environment
        io: IO interface
        
    Returns:
        Build environment with dependencies installed
    """

def install_build_dependencies(env: Env, requirements: list) -> None:
    """
    Install build dependencies in environment.
    
    Args:
        env: Build environment
        requirements: List of build requirements
        
    Raises:
        BuildError: If dependency installation fails
    """

def validate_build_environment(env: Env, requirements: list) -> bool:
    """
    Validate build environment has required dependencies.
    
    Args:
        env: Environment to validate
        requirements: Required build dependencies
        
    Returns:
        True if environment is valid for building
    """

Advanced Build Patterns

Custom Build Scripts

from poetry.masonry.api import build_wheel, build_sdist

def custom_build_process():
    """Custom build process with pre/post build steps."""
    
    # Pre-build steps
    print("Running pre-build steps...")
    run_code_generation()
    compile_assets()
    
    # Build distributions
    wheel_file = build_wheel("dist/")
    sdist_file = build_sdist("dist/")
    
    # Post-build steps
    print("Running post-build steps...")
    sign_distributions([wheel_file, sdist_file])
    upload_to_registry([wheel_file, sdist_file])
    
    return wheel_file, sdist_file

def run_code_generation():
    """Generate code before building."""
    pass

def compile_assets():
    """Compile static assets."""
    pass

def sign_distributions(files):
    """Sign distribution files."""
    pass

def upload_to_registry(files):
    """Upload to package registry."""
    pass

Build Configuration in pyproject.toml

[tool.poetry.build]
# Include additional files
include = [
    "README.md",
    "LICENSE",
    "data/*.json"
]

# Exclude files from distribution
exclude = [
    "tests/",
    "docs/",
    "*.log"
]

# Build script configuration
script = "build_script.py"

Programmatic Building

from poetry.factory import Factory
from poetry.masonry.builders.package_builder import PackageBuilder
from poetry.utils.env import build_environment

def build_project_programmatically(project_path):
    """Build project programmatically."""
    # Create Poetry instance
    poetry = Factory().create_poetry(cwd=project_path)
    
    # Create build environment
    env_manager = EnvManager(poetry.file.parent)
    base_env = env_manager.create_venv()
    build_env = build_environment(poetry, base_env)
    
    # Create builder
    builder = PackageBuilder(poetry, build_env)
    
    # Build all formats
    distributions = builder.build_all(target_dir=project_path / "dist")
    
    return distributions

Error Handling

Build system exceptions and error conditions:

class BuildError(PoetryError):
    """Base build system error."""

class BuildBackendError(BuildError):
    """Build backend operation failures."""

class BuildRequirementError(BuildError):
    """Build requirement installation or resolution errors."""

class PackagingError(BuildError):
    """Package creation and formatting errors."""

class MetadataError(BuildError):
    """Package metadata generation errors."""

Common build errors: