tessl/pypi-hatchling

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

—

Pending

Overview

Eval results

Files

CLI Interface

Name: tessl/pypi-hatchling
Author: tessl

Command-line interface providing build, metadata inspection, version management, and dependency analysis functionality. The CLI offers direct access to hatchling's capabilities for development and debugging.

Capabilities

Main CLI Entry Point

def hatchling() -> int:
    """
    Main CLI entry point.
    
    Returns:
        int: Exit code (0 for success)
    """

Build Command

Build distributions (wheels and source distributions) from the command line.

hatchling build [OPTIONS]

Options:
  -t, --target TEXT    Build target (wheel, sdist, binary, or custom)
  -c, --clean          Clean build directory before building
  --ext                Build extensions
  --no-sources         Skip source distribution building
  --no-wheel           Skip wheel building
  -h, --help          Show help message

Metadata Command

Inspect and display project metadata information.

hatchling metadata [OPTIONS]

Options:
  --field TEXT         Show specific metadata field
  --core               Show core metadata in email format
  --json               Output metadata as JSON
  -h, --help          Show help message

Version Command

Manage project version information.

hatchling version [OPTIONS] [VERSION]

Arguments:
  VERSION              New version to set (optional)

Options:
  --dry-run           Show what would be changed without making changes
  -h, --help          Show help message

Dependency Command

Analyze and display project dependencies.

hatchling dep [OPTIONS] COMMAND [ARGS]...

Commands:
  show                 Show dependency information
  hash                 Show dependency hashes
  freeze               Show installed dependencies in freeze format

Options:
  -h, --help          Show help message

Command Details

Build Command Usage

Build all distribution types:

hatchling build

Build only wheels:

hatchling build -t wheel

Build only source distributions:

hatchling build -t sdist

Build with clean directory:

hatchling build --clean

Build custom targets:

hatchling build -t my-custom-builder

Metadata Command Usage

Show all metadata:

hatchling metadata

Show specific field:

hatchling metadata --field name
hatchling metadata --field version
hatchling metadata --field dependencies

Show core metadata:

hatchling metadata --core

Output as JSON:

hatchling metadata --json

Version Command Usage

Show current version:

hatchling version

Set new version:

hatchling version 1.2.0

Preview version change:

hatchling version 1.2.0 --dry-run

Dependency Command Usage

Show project dependencies:

hatchling dep show

Show dependency hashes:

hatchling dep hash

Show freeze format:

hatchling dep freeze

CLI Implementation

Command Registration

def build_command(subparsers, defaults):
    """Register build command with argument parser."""

def metadata_command(subparsers, defaults):
    """Register metadata command with argument parser."""

def version_command(subparsers, defaults):
    """Register version command with argument parser."""

def dep_command(subparsers, defaults):
    """Register dependency command with argument parser."""

Argument Parser

The CLI uses Python's argparse module with the following structure:

parser = argparse.ArgumentParser(prog='hatchling', allow_abbrev=False)
subparsers = parser.add_subparsers()

# Default settings for all subcommands
defaults = {'metavar': ''}

Usage Examples

Development Workflow

# Check project metadata
hatchling metadata --field name
hatchling metadata --field version

# Build development distributions
hatchling build --clean

# Update version
hatchling version 1.1.0

# Build release distributions
hatchling build -t wheel -t sdist

CI/CD Integration

# Validate metadata
hatchling metadata --core > /dev/null

# Build distributions for upload
hatchling build --clean

# Check dependency information
hatchling dep show

Debugging

# Show all metadata in JSON format
hatchling metadata --json

# Show specific metadata fields
hatchling metadata --field dynamic
hatchling metadata --field build-system

# Preview version changes
hatchling version 2.0.0 --dry-run

Custom Builder Integration

# Build with custom builder plugin
hatchling build -t my-custom-builder

# Show available builders (through metadata)
hatchling metadata --field tool.hatch.build

Exit Codes

The CLI returns standard exit codes:

0: Success
1: General error (invalid arguments, build failures, etc.)
2: File not found or permission error

Configuration

CLI behavior can be configured through:

pyproject.toml: Project-specific settings
Environment variables: Build-time overrides
Command-line options: Per-invocation settings

Environment Variables

Common environment variables that affect CLI behavior:

HATCH_BUILD_CLEAN: Clean build directory (equivalent to --clean)
HATCH_BUILD_NO_SOURCES: Skip source distribution building
HATCH_BUILD_NO_WHEEL: Skip wheel building
HATCH_VERBOSE: Enable verbose output

Configuration Files

The CLI reads configuration from:

[tool.hatch.build]
targets = ["wheel", "sdist"]
clean = true

[tool.hatch.version]
source = "code"
path = "src/package/__about__.py"

[tool.hatch.metadata]
allow-direct-references = true

Programmatic Access

The CLI functions can also be called programmatically:

import sys
from hatchling.cli import hatchling

# Call CLI programmatically
sys.argv = ['hatchling', 'build', '--clean']
exit_code = hatchling()

However, for programmatic usage, it's recommended to use the builder classes directly rather than the CLI interface.

Error Handling

The CLI provides user-friendly error messages for common issues:

Missing pyproject.toml or invalid configuration
Build failures with detailed error context
Invalid metadata field references
Version parsing or setting errors
Dependency resolution issues

Errors are displayed to stderr with helpful suggestions when possible.

Integration with Build Tools

The CLI integrates with various development tools:

tox: Use hatchling CLI in tox environments
GitHub Actions: CI/CD with hatchling commands
pre-commit: Version management hooks
make: Build automation with make targets

Example Makefile integration:

build:
	hatchling build --clean

metadata:
	hatchling metadata --json > metadata.json

version:
	hatchling version $(VERSION)

The CLI interface provides a convenient way to access hatchling's functionality during development, CI/CD, and release workflows while maintaining consistency with the programmatic API.

Install with Tessl CLI