or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

application.mdcli-commands.mdconfiguration.mdenvironment-management.mdindex.mdplugin-system.mdproject-management.mdpython-management.md
tile.json

tessl/pypi-hatch

Modern, extensible Python project management tool with comprehensive environment and build system support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/hatch@1.14.x

To install, run

npx @tessl/cli install tessl/pypi-hatch@1.14.0

index.mddocs/

Hatch

Modern, extensible Python project management tool that provides a comprehensive solution for Python package development, environment management, dependency handling, testing, and publishing. Hatch standardizes the development workflow with a plugin-based architecture and fast, reliable operations.

Package Information

  • Package Name: hatch
  • Language: Python
  • Installation: pip install hatch

Core Imports

from hatch.cli import main
from hatch.cli.application import Application
from hatch.project.core import Project
from hatch.config.user import ConfigFile

For plugin development:

from hatch.env.plugin.interface import EnvironmentInterface
from hatch.publish.plugin.interface import PublisherInterface
from hatch.template.plugin.interface import TemplateInterface

Basic Usage

from hatch.project.core import Project
from hatch.cli.application import Application

# Initialize a project
project = Project("/path/to/project")

# Access project metadata
print(project.metadata.name)
print(project.metadata.version)

# Create application instance
app = Application(exit_func=lambda code: None)
app.project = project

# Get an environment
env = app.get_environment("default")
if not env.exists():
    env.create()

# Execute commands in the environment
context = app.get_execution_context()
app.run_shell_commands(context)

Architecture

Hatch follows a layered architecture with clear separation of concerns:

  • CLI Layer: Click-based command-line interface with 16+ commands
  • Application Layer: Central coordinator managing project state and operations
  • Project Layer: Project representation with metadata and configuration management
  • Plugin System: Extensible architecture supporting environment, publisher, template, and collector plugins
  • Environment Management: Virtual environment creation, dependency management, and command execution
  • Configuration System: Hierarchical configuration with environment variable support

The plugin system enables extensibility through well-defined interfaces, allowing custom environments (Docker, Conda), publishers (private indices), and project templates.

Capabilities

CLI Commands

Command-line interface providing comprehensive project management operations including environment management, dependency handling, building, testing, publishing, and Python installation management.

def main():
    """Main CLI entry point."""

# Core CLI commands available:
# hatch build - Build distributions
# hatch clean - Remove build artifacts  
# hatch config - Configuration management
# hatch dep - Dependency operations
# hatch env - Environment management
# hatch fmt - Code formatting
# hatch new - Project creation
# hatch project - Project operations
# hatch publish - Package publishing
# hatch python - Python management
# hatch run - Command execution
# hatch shell - Shell integration
# hatch status - Project status
# hatch test - Test execution
# hatch version - Version management

CLI Commands

Project Management

Core project representation and manipulation capabilities including project discovery, metadata access, configuration management, and project initialization.

class Project:
    def __init__(self, path: Path, *, name: str | None = None, config=None): ...
    
    @classmethod
    def from_config(cls, config, project: str) -> Project | None: ...
    
    @property
    def root(self) -> Path | None: ...
    @property
    def metadata(self): ...
    @property
    def config(self): ...
    
    def find_project_root(self) -> Path | None: ...
    def ensure_cwd(self): ...
    
    @staticmethod
    def canonicalize_name(name: str, *, strict=True) -> str: ...
    @staticmethod
    def initialize(project_file_path, template_config): ...

Project Management

Application Controller

Central application controller that manages project state, configuration, environments, and command execution. Provides the main coordination layer for all hatch operations.

class Application:
    @property
    def config(self): ...
    @property
    def plugins(self): ...
    @property
    def project(self): ...
    
    def get_environment(self, env_name: str | None = None): ...
    def prepare_environment(self, environment): ...
    def run_shell_commands(self, context): ...
    def get_python_manager(self, directory: str | None = None): ...
    def abort(self, text='', code=1, **kwargs): ...

Application Controller

Environment Management

Environment plugin system for creating, managing, and executing commands in isolated Python environments. Supports virtual environments, Docker containers, and custom environment types through plugins.

class EnvironmentInterface:
    PLUGIN_NAME: str = ''
    
    @property
    def name(self) -> str: ...
    @property
    def config(self) -> dict: ...
    @property
    def dependencies(self) -> list: ...
    
    def exists(self) -> bool: ...
    def create(self) -> None: ...
    def remove(self) -> None: ...
    def install_project(self) -> None: ...
    def install_project_dev_mode(self) -> None: ...
    def sync_dependencies(self) -> None: ...

Environment Management

Plugin System

Extensible plugin architecture supporting environment types, publishers, project templates, and environment collectors. Provides hook specifications and plugin manager for registration and discovery.

# Hook specifications
def hatch_register_environment(): ...
def hatch_register_publisher(): ...
def hatch_register_template(): ...
def hatch_register_environment_collector(): ...

class PluginManager:
    def initialize(self): ...
    def hatch_register_environment(self): ...
    def hatch_register_publisher(self): ...
    def hatch_register_template(self): ...

Plugin System

Configuration Management

Hierarchical configuration system with lazy loading, environment variable support, and file-based persistence. Manages application settings, project configuration, and plugin configuration.

class ConfigFile:
    def __init__(self, path: Path | None = None): ...
    
    @property
    def path(self): ...
    
    def save(self, content=None): ...
    def load(self): ...
    def read(self) -> str: ...
    def read_scrubbed(self) -> str: ...
    def restore(self): ...
    
    @classmethod
    def get_default_location(cls) -> Path: ...

class RootConfig:
    @property
    def mode(self): ...
    @property
    def project(self): ...
    @property
    def dirs(self): ...
    @property
    def publish(self): ...

Configuration Management

Python Installation Management

Automated Python distribution management including installation, version management, and distribution discovery. Supports multiple Python versions and provides integration with UV and other Python managers.

class PythonManager:
    def __init__(self, directory: Path): ...
    
    def get_installed(self) -> dict: ...
    def install(self, identifier: str): ...

class InstalledDistribution:
    @property
    def path(self) -> Path: ...
    @property
    def name(self) -> str: ...
    @property
    def python_path(self) -> Path: ...
    @property
    def version(self) -> str: ...
    
    def needs_update(self) -> bool: ...

Python Management

Types

# Core types used across the API
from pathlib import Path
from typing import Any, Dict, List, Optional, Union, Generator, Callable

# Hatch-specific types
class HatchError(Exception):
    """Base exception for hatch-specific errors."""

class PythonDistributionUnknownError(HatchError):
    """Raised when a Python distribution is unknown."""

class PythonDistributionResolutionError(HatchError):
    """Raised when Python distribution resolution fails."""

# Environment variables classes
class AppEnvVars:
    ENV: str = 'HATCH_ENV'
    ENV_ACTIVE: str = 'HATCH_ENV_ACTIVE'
    QUIET: str = 'HATCH_QUIET'
    VERBOSE: str = 'HATCH_VERBOSE'
    INTERACTIVE: str = 'HATCH_INTERACTIVE'
    PYTHON: str = 'HATCH_PYTHON'
    NO_COLOR: str = 'NO_COLOR'
    FORCE_COLOR: str = 'FORCE_COLOR'

class ConfigEnvVars:
    PROJECT: str = 'HATCH_PROJECT'
    DATA: str = 'HATCH_DATA_DIR'
    CACHE: str = 'HATCH_CACHE_DIR'
    CONFIG: str = 'HATCH_CONFIG'

class PublishEnvVars:
    USER: str = 'HATCH_INDEX_USER'
    AUTH: str = 'HATCH_INDEX_AUTH'
    REPO: str = 'HATCH_INDEX_REPO'