tessl/pypi-setuptools

Easily download, build, install, upgrade, and uninstall Python packages

—

Pending

Overview

Eval results

Files

Build Backend API

Name: tessl/pypi-setuptools
Author: tessl

PEP 517/518 compliant build backend functions for modern Python packaging workflows, enabling setuptools to work with build tools like pip, build, and other PEP 517 frontends. This API provides a standardized interface for building wheels and source distributions.

Capabilities

Core Build Functions

The main functions that implement the PEP 517 build backend interface for creating distributable packages.

def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
    """
    Build a wheel distribution from the current directory.

    This function builds a wheel (.whl) file that can be installed by pip
    or other installation tools. The wheel contains the built package.

    Parameters:
    - wheel_directory (str): Directory where the wheel file will be written
    - config_settings (dict, optional): Build configuration settings from frontend
    - metadata_directory (str, optional): Directory containing prepared metadata

    Returns:
    str: Filename of the built wheel file

    Raises:
    BackendUnavailable: If backend cannot build wheels
    CalledProcessError: If build process fails
    """

def build_sdist(sdist_directory, config_settings=None):
    """
    Build a source distribution from the current directory.

    This function creates a source distribution (.tar.gz) file containing
    the source code and build instructions.

    Parameters:
    - sdist_directory (str): Directory where the sdist file will be written
    - config_settings (dict, optional): Build configuration settings from frontend

    Returns:
    str: Filename of the built source distribution

    Raises:
    BackendUnavailable: If backend cannot build sdists
    CalledProcessError: If build process fails
    """

def build_editable(wheel_directory, config_settings=None, metadata_directory=None):
    """
    Build an editable wheel distribution.

    Creates a wheel that installs the package in "editable" or "development"
    mode, where changes to the source code are immediately reflected without
    reinstallation.

    Parameters:
    - wheel_directory (str): Directory where the wheel file will be written
    - config_settings (dict, optional): Build configuration settings from frontend
    - metadata_directory (str, optional): Directory containing prepared metadata

    Returns:
    str: Filename of the built editable wheel file

    Raises:
    BackendUnavailable: If backend cannot build editable wheels
    CalledProcessError: If build process fails
    """

Build Requirement Functions

Functions that return the dependencies needed for building packages, allowing frontends to install necessary tools before attempting builds.

def get_requires_for_build_wheel(config_settings=None):
    """
    Get requirements for building a wheel.

    Returns a list of packages that must be installed before
    build_wheel() can be called successfully.

    Parameters:
    - config_settings (dict, optional): Build configuration settings

    Returns:
    list: List of requirement strings (e.g., ['wheel>=0.30.0', 'cython'])

    Example return value:
    ['wheel>=0.30.0']
    """

def get_requires_for_build_sdist(config_settings=None):
    """
    Get requirements for building a source distribution.

    Returns a list of packages that must be installed before
    build_sdist() can be called successfully.

    Parameters:
    - config_settings (dict, optional): Build configuration settings

    Returns:
    list: List of requirement strings

    Example return value:
    []  # Usually empty for setuptools
    """

def get_requires_for_build_editable(config_settings=None):
    """
    Get requirements for building an editable wheel.

    Returns a list of packages that must be installed before
    build_editable() can be called successfully.

    Parameters:
    - config_settings (dict, optional): Build configuration settings

    Returns:
    list: List of requirement strings

    Example return value:
    ['wheel>=0.30.0']
    """

Metadata Preparation Functions

Functions for preparing package metadata separately from the build process, which can improve build performance by avoiding redundant metadata generation.

def prepare_metadata_for_build_wheel(metadata_directory, config_settings=None):
    """
    Prepare metadata for building a wheel.

    This function generates package metadata (like METADATA, WHEEL files)
    without building the complete wheel. This can speed up dependency
    resolution by frontends.

    Parameters:
    - metadata_directory (str): Directory where metadata files will be written
    - config_settings (dict, optional): Build configuration settings

    Returns:
    str: Name of the metadata directory created

    The created directory will contain:
    - METADATA file (package metadata)
    - WHEEL file (wheel metadata)
    - entry_points.txt (if entry points are defined)
    - Other metadata files as needed
    """

def prepare_metadata_for_build_editable(metadata_directory, config_settings=None):
    """
    Prepare metadata for building an editable wheel.

    Similar to prepare_metadata_for_build_wheel but for editable installations.

    Parameters:
    - metadata_directory (str): Directory where metadata files will be written
    - config_settings (dict, optional): Build configuration settings

    Returns:
    str: Name of the metadata directory created
    """

Build Backend Error Classes

Exception classes specific to the build backend functionality.

class SetupRequirementsError(Exception):
    """
    Exception raised when setup requirements cannot be satisfied.

    This error is raised when the build backend cannot install or find
    the dependencies needed for building the package.

    Attributes:
    - specifiers: List of requirement specifiers that failed
    """

    def __init__(self, specifiers):
        """
        Initialize with failed requirement specifiers.

        Parameters:
        - specifiers (list): Requirements that could not be satisfied
        """

Usage Examples

Using with pyproject.toml

The build backend is typically configured in pyproject.toml:

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

Custom Build Configuration

[build-system]
requires = ["setuptools>=61.0", "wheel", "cython"]
build-backend = "setuptools.build_meta"

[tool.setuptools]
# Setuptools-specific configuration
zip-safe = false

[tool.setuptools.packages.find]
where = ["src"]
include = ["mypackage*"]
exclude = ["tests*"]

Building with pip

# Build wheel using the build backend
pip wheel .

# Install in editable mode (uses build_editable)
pip install -e .

# Build source distribution
pip sdist .

Building with build tool

# Install the build frontend
pip install build

# Build both wheel and sdist
python -m build

# Build only wheel
python -m build --wheel

# Build only sdist
python -m build --sdist

Configuration Settings

Build frontends can pass configuration settings to the backend:

# Example of what a frontend might do internally
config_settings = {
    'global-option': ['--verbose'],
    'build-option': ['--build-base', '/tmp/build'],
}

wheel_filename = build_wheel(
    wheel_directory='dist',
    config_settings=config_settings
)

Custom Build Backend

You can create a custom build backend that wraps setuptools:

# custom_backend.py
from setuptools import build_meta as _orig

# Re-export most functions unchanged
build_wheel = _orig.build_wheel
build_sdist = _orig.build_sdist
get_requires_for_build_wheel = _orig.get_requires_for_build_wheel
get_requires_for_build_sdist = _orig.get_requires_for_build_sdist

def build_editable(wheel_directory, config_settings=None, metadata_directory=None):
    """Custom editable build logic."""
    print("Custom editable build logic")
    return _orig.build_editable(wheel_directory, config_settings, metadata_directory)

# Use in pyproject.toml:
# [build-system]
# requires = ["setuptools>=61.0", "wheel"]
# build-backend = "custom_backend"

Error Handling

from setuptools.build_meta import build_wheel, SetupRequirementsError

try:
    wheel_file = build_wheel('dist')
    print(f"Built wheel: {wheel_file}")
except SetupRequirementsError as e:
    print(f"Missing requirements: {e.specifiers}")
    # Install missing requirements and retry
except Exception as e:
    print(f"Build failed: {e}")

Metadata Preparation

from setuptools.build_meta import prepare_metadata_for_build_wheel
import os

# Prepare metadata without building the full wheel
metadata_dir = prepare_metadata_for_build_wheel('build/metadata')

# Read the prepared metadata
metadata_path = os.path.join('build/metadata', metadata_dir, 'METADATA')
with open(metadata_path) as f:
    metadata_content = f.read()
    print("Package metadata:", metadata_content)

Install with Tessl CLI