or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-backend.mdbuilders.mdcli.mdindex.mdmetadata.mdplugins.mdversion.md
tile.json

tessl/pypi-hatchling

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/hatchling@1.27.x

To install, run

npx @tessl/cli install tessl/pypi-hatchling@1.27.0

index.mddocs/

Hatchling

A modern, extensible Python build backend that implements PEP 517 and PEP 660 standards. Hatchling serves as the core packaging infrastructure for Python projects, providing comprehensive build system functionality with support for plugins, custom build hooks, and flexible configuration.

Package Information

  • Package Name: hatchling
  • Language: Python
  • Installation: pip install hatchling
  • Build Backend: Use as build-backend = "hatchling.build" in pyproject.toml

Core Imports

# PEP 517/660 build backend API
from hatchling.build import build_sdist, build_wheel, build_editable
from hatchling.build import get_requires_for_build_sdist, get_requires_for_build_wheel, get_requires_for_build_editable

# Builder classes for programmatic use
from hatchling.builders.sdist import SdistBuilder  
from hatchling.builders.wheel import WheelBuilder

# Plugin system
from hatchling.plugin.manager import PluginManager

# Metadata handling
from hatchling.metadata.core import ProjectMetadata

# CLI interface
from hatchling.cli import hatchling

# Plugin registration
from hatchling.plugin import hookimpl

Basic Usage

As Build Backend

Configure in pyproject.toml:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Programmatic Usage

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

# Build a wheel
wheel_builder = WheelBuilder(os.getcwd())
wheel_path = next(wheel_builder.build(directory="dist", versions=["standard"]))
print(f"Built wheel: {wheel_path}")

# Build a source distribution
sdist_builder = SdistBuilder(os.getcwd())
sdist_path = next(sdist_builder.build(directory="dist", versions=["standard"]))
print(f"Built sdist: {sdist_path}")

CLI Usage

# Build distributions
hatchling build

# Show metadata
hatchling metadata

# Version management
hatchling version

# Dependency analysis
hatchling dep

Architecture

Hatchling is built around a plugin architecture with several key components:

  • Build Backend API: PEP 517/660 compliant functions for build tools like pip
  • Builder System: Extensible builders for different distribution types (wheel, sdist, binary)
  • Plugin Manager: Centralized plugin discovery and management system
  • Metadata System: Project metadata parsing, validation, and core metadata generation
  • Version Management: Pluggable version sources and schemes
  • Build Hooks: Pre/post-build customization points
  • CLI Interface: Command-line tools for development and debugging

Capabilities

PEP 517/660 Build Backend

Core build backend functions implementing Python packaging standards for integration with build frontends like pip and build.

def build_sdist(sdist_directory: str, config_settings: dict | None = None) -> str: ...
def build_wheel(wheel_directory: str, config_settings: dict | None = None, metadata_directory: str | None = None) -> str: ...
def build_editable(wheel_directory: str, config_settings: dict | None = None, metadata_directory: str | None = None) -> str: ...
def get_requires_for_build_sdist(config_settings: dict | None = None) -> list[str]: ...
def get_requires_for_build_wheel(config_settings: dict | None = None) -> list[str]: ...
def get_requires_for_build_editable(config_settings: dict | None = None) -> list[str]: ...
def prepare_metadata_for_build_wheel(metadata_directory: str, config_settings: dict | None = None) -> str: ...
def prepare_metadata_for_build_editable(metadata_directory: str, config_settings: dict | None = None) -> str: ...

PEP 517/660 Build Backend

Builder System

Comprehensive builder classes for creating different types of Python distributions with extensible configuration and plugin support.

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): ...
    def build(self, *, directory: str = "dist", versions: list[str] | None = None) -> Iterator[str]: ...

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): ...
    def build(self, *, directory: str = "dist", versions: list[str] | None = None) -> Iterator[str]: ...

Builder System

Plugin System

Extensible plugin architecture supporting custom builders, build hooks, version sources, version schemes, and metadata hooks.

class PluginManager:
    def __init__(self, project_metadata: ProjectMetadata, plugin_manager: PluginManager | None = None): ...
    @property
    def builders(self) -> dict[str, type[BuilderInterface]]: ...
    @property
    def build_hooks(self) -> dict[str, type[BuildHookInterface]]: ...
    @property
    def version_sources(self) -> dict[str, type[VersionSourceInterface]]: ...
    @property
    def version_schemes(self) -> dict[str, type[VersionSchemeInterface]]: ...
    @property
    def metadata_hooks(self) -> dict[str, type[MetadataHookInterface]]: ...

Plugin System

Metadata System

Project metadata parsing, validation, and core metadata generation following Python packaging standards.

class ProjectMetadata:
    def __init__(self, root: str, plugin_manager: PluginManager | None = None, config: dict | None = None): ...
    @property
    def name(self) -> str: ...
    @property
    def version(self) -> str: ...
    @property
    def description(self) -> str: ...
    @property
    def dependencies(self) -> list[str]: ...
    @property
    def optional_dependencies(self) -> dict[str, list[str]]: ...

Metadata System

CLI Interface

Command-line interface providing build, metadata inspection, version management, and dependency analysis functionality.

def hatchling() -> int: ...

CLI Interface

Version Management

Pluggable version sources and schemes for flexible version handling across different project structures and workflows.

class VersionSourceInterface:
    def get_version_data(self) -> dict: ...
    def set_version(self, version: str, version_data: dict) -> None: ...

class VersionSchemeInterface:
    def update(self, version: str, **kwargs) -> str: ...
    def parse(self, version: str) -> dict: ...
    def normalize(self, version: str) -> str: ...

Version Management

Types

# Core build backend types
from typing import Any, Generator, Callable, TypeVar, Generic
from pathlib import Path

ConfigSettings = dict[str, Any] | None

# Generic type variables for plugin system
BuilderConfigBound = TypeVar('BuilderConfigBound')
PluginManagerBound = TypeVar('PluginManagerBound')

# Builder interfaces
class BuilderInterface:
    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]: ...
    def get_version_api(self) -> dict[str, Callable]: ...

class BuildHookInterface:
    def clean(self, versions: list[str]) -> None: ...
    def initialize(self, version: str, build_data: dict[str, Any]) -> None: ...
    def finalize(self, version: str, build_data: dict[str, Any], artifact_path: str) -> None: ...

# Plugin interfaces
class VersionSourceInterface:
    def get_version_data(self) -> dict: ...
    def set_version(self, version: str, version_data: dict) -> None: ...

class VersionSchemeInterface:
    def update(self, version: str, **kwargs) -> str: ...
    def parse(self, version: str) -> dict: ...
    def normalize(self, version: str) -> str: ...

class MetadataHookInterface:
    def update(self, metadata: dict[str, Any]) -> None: ...

# File and archive types
class IncludedFile:
    def __init__(self, path: str, source_path: str, distribution_path: str): ...
    path: str
    source_path: str  
    distribution_path: str