or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdconfiguration.mdgit-operations.mdhook-management.mdindex.mdpath-utilities.mdplugin-api.md
tile.json

tessl/pypi-autohooks

Library for managing git hooks using pyproject.toml configuration with an extensible plugin system

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/autohooks@25.4.x

To install, run

npx @tessl/cli install tessl/pypi-autohooks@25.4.0

index.mddocs/

Autohooks

A pure Python library for managing and writing git hooks using pyproject.toml for configuration. Autohooks installs minimal executable git hooks with support for different dependency management modes (pythonpath, poetry, pipenv), providing an extensible plugin system for code formatting, linting, and testing tools.

Package Information

  • Package Name: autohooks
  • Language: Python
  • Installation: pip install autohooks
  • Supported Python: 3.9+

Core Imports

import autohooks

For plugin development (main API):

from autohooks.api import Config, ReportProgress
from autohooks.api import error, fail, info, bold_info, ok, out, warning

For git operations:

from autohooks.api.git import get_staged_status, get_status, stage_files
from autohooks.api.git import StatusEntry, Status, stash_unstaged_changes

For path utilities:

from autohooks.api.path import is_python_path, match

Basic Usage

Installation and Activation

# Install hooks for the current project
import subprocess
subprocess.run(["autohooks", "activate"], check=True)

# Add plugins to configuration
subprocess.run(["autohooks", "plugins", "add", "autohooks.plugins.black"], check=True)

Plugin Development

from autohooks.api import Config, ReportProgress
from autohooks.api.git import get_staged_status, stage_files

def precommit(config: Config, report_progress: ReportProgress, **kwargs):
    """
    Main plugin entry point called during pre-commit hook execution.
    
    Args:
        config: Configuration object for accessing settings
        report_progress: Progress reporting interface
        **kwargs: Additional arguments for future compatibility
        
    Returns:
        int: 0 for success, non-zero for failure
    """
    # Get staged Python files
    status_entries = get_staged_status()
    python_files = [entry for entry in status_entries 
                   if entry.path.suffix == '.py']
    
    if not python_files:
        return 0
        
    # Initialize progress reporting
    report_progress.init(len(python_files))
    
    # Process each file
    for file_entry in python_files:
        # Perform processing (formatting, linting, etc.)
        process_file(file_entry.absolute_path())
        report_progress.update()
    
    return 0

Architecture

Autohooks follows a plugin-based architecture with clear separation of concerns:

  • CLI Layer: Command-line interface for user interactions (activate, check, plugins)
  • Configuration Layer: TOML-based configuration management with pyproject.toml integration
  • Hook Management: Git hook installation, validation, and execution orchestration
  • Plugin System: Extensible plugin architecture with progress reporting and error handling
  • API Layer: Clean public API for plugin development with git, path, and terminal utilities

The library prioritizes Python-native tooling while maintaining flexibility in dependency management through multiple execution modes.

Capabilities

Command Line Interface

Complete CLI for managing git hooks and plugins, including hook activation, status checking, and plugin management with support for different dependency modes.

def main(): ...
def install_hooks(term: Terminal, args: Namespace): ...
def check_hooks(term: Terminal, args: Namespace): ...
def add_plugins(term: Terminal, args: Namespace): ...
def remove_plugins(term: Terminal, args: Namespace): ...
def list_plugins(term: Terminal, args: Namespace): ...

Command Line Interface

Plugin API

Core API for developing autohooks plugins with configuration access, progress reporting, and terminal output utilities.

class Config:
    def get(self, *keys: str) -> 'Config': ...
    def get_value(self, key: str, default: Any = None) -> Any: ...

class ReportProgress:
    def init(self, total: int) -> None: ...
    def update(self, advance: int = 1) -> None: ...

def error(message: str) -> None: ...
def info(message: str) -> None: ...
def ok(message: str) -> None: ...

Plugin API

Git Operations

Comprehensive git integration for working with staged files, status checking, and repository operations within hooks.

def get_status(files: Optional[Iterable[PathLike]] = None) -> List[StatusEntry]: ...
def get_staged_status(files: Optional[Iterable[PathLike]] = None) -> List[StatusEntry]: ...
def stage_files(files: Iterable[PathLike]) -> None: ...
def is_staged_status(status: StatusEntry) -> bool: ...
def is_partially_staged_status(status: StatusEntry) -> bool: ...

class StatusEntry:
    def absolute_path(self) -> Path: ...

class stash_unstaged_changes: ...

Git Operations

Configuration Management

Configuration system for reading and writing autohooks settings in pyproject.toml with support for different dependency modes.

class AutohooksConfig:
    def from_dict(config_dict: Dict[str, Any]) -> 'AutohooksConfig': ...
    def from_toml(toml_file: Path) -> 'AutohooksConfig': ...
    def has_autohooks_config(self) -> bool: ...
    def get_pre_commit_script_names(self) -> List[str]: ...
    def get_mode(self) -> Mode: ...

def load_config_from_pyproject_toml(pyproject_toml: Optional[Path] = None) -> AutohooksConfig: ...

Configuration Management

Hook Management

Git hook installation, validation, and management with support for different execution modes and template rendering.

class PreCommitHook:
    def exists(self) -> bool: ...
    def is_autohooks_pre_commit_hook(self) -> bool: ...
    def is_current_autohooks_pre_commit_hook(self) -> bool: ...
    def read_mode(self) -> Mode: ...
    def write(self, *, mode: Mode) -> None: ...

def get_pre_commit_hook_path(): ...

Hook Management

Path Utilities

Path matching and validation utilities for file processing in plugins.

def is_python_path(path: Optional[Path]) -> bool: ...
def match(path: PathLike, pattern_list: Iterable[str]) -> bool: ...

Path Utilities

Types

class Mode(Enum):
    PIPENV = 1
    PYTHONPATH = 2
    POETRY = 3
    PIPENV_MULTILINE = 4
    POETRY_MULTILINE = 5
    UNDEFINED = -1
    UNKNOWN = -2

class Status(Enum):
    UNMODIFIED = " "
    MODIFIED = "M"
    ADDED = "A"
    DELETED = "D"
    RENAMED = "R"
    COPIED = "C"
    UPDATED = "U"
    UNTRACKED = "?"
    IGNORED = "!"

class AutohooksSettings:
    mode: Mode
    pre_commit: Iterable[str]
    def write(self, filename: Path) -> None: ...