tessl/pypi-autohooks

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Hook Management

Name: tessl/pypi-autohooks
Author: tessl

Git hook installation, validation, and management with support for different execution modes and template rendering. This API provides comprehensive hook lifecycle management for autohooks integration.

Capabilities

Hook Installation and Management

Install, validate, and manage pre-commit hooks with support for different dependency modes and version tracking.

class PreCommitHook:
    """
    Pre-commit hook management class for installation, validation, and execution.
    """
    
    def __init__(self, pre_commit_hook_path: Optional[Path] = None) -> None:
        """
        Create PreCommitHook manager.
        
        Args:
            pre_commit_hook_path: Optional custom path to pre-commit hook file.
                                If None, uses default git hooks directory.
        """
    
    def exists(self) -> bool:
        """
        Check if pre-commit hook file exists.
        
        Returns:
            True if hook file exists, False otherwise
        """
    
    def is_autohooks_pre_commit_hook(self) -> bool:
        """
        Check if the existing hook is an autohooks-generated hook.
        
        Returns:
            True if hook is autohooks-generated, False otherwise
        """
    
    def is_current_autohooks_pre_commit_hook(self) -> bool:
        """
        Check if the hook is the current version of autohooks hook.
        
        Returns:
            True if hook is current version, False if outdated
        """
    
    def read_mode(self) -> Mode:
        """
        Read the dependency management mode from the hook file.
        
        Returns:
            Mode enum indicating how dependencies are managed
        """
    
    def read_version(self) -> int:
        """
        Read the template version from the hook file.
        
        Returns:
            Template version number, -1 if not found
        """
    
    def write(self, *, mode: Mode) -> None:
        """
        Write/install the pre-commit hook with specified mode.
        
        Args:
            mode: Dependency management mode for hook execution
        """

def get_pre_commit_hook_path():
    """
    Get the standard path to the pre-commit hook file.
    
    Returns:
        Path to the pre-commit hook in the git hooks directory
    """

Usage Examples:

from autohooks.hooks import PreCommitHook, get_pre_commit_hook_path
from autohooks.settings import Mode

# Create hook manager
hook = PreCommitHook()

# Check hook status
if hook.exists():
    if hook.is_autohooks_pre_commit_hook():
        if hook.is_current_autohooks_pre_commit_hook():
            print("Hook is installed and current")
        else:
            print("Hook is installed but outdated")
    else:
        print("Different hook is installed")
else:
    print("No pre-commit hook installed")

# Install/update hook
hook.write(mode=Mode.POETRY)

# Check hook configuration
current_mode = hook.read_mode()
version = hook.read_version()
print(f"Hook mode: {current_mode}, version: {version}")

# Get hook path
hook_path = get_pre_commit_hook_path()
print(f"Hook installed at: {hook_path}")

Template Management

Hook template rendering with support for different execution modes and shebang generation.

class PreCommitTemplate:
    """
    Template manager for generating pre-commit hook files.
    """
    
    def __init__(self, template_path: Optional[Path] = None) -> None:
        """
        Create template manager.
        
        Args:
            template_path: Optional custom template path. If None, uses default template.
        """
    
    def render(self, *, mode: Mode) -> str:
        """
        Render the pre-commit hook template with specified mode.
        
        Args:
            mode: Dependency management mode for hook execution
            
        Returns:
            Rendered hook script content
        """

def get_pre_commit_hook_template_path() -> Path:
    """
    Get path to the pre-commit hook template file.
    
    Returns:
        Path to template file
    """

Usage Examples:

from autohooks.template import PreCommitTemplate, get_pre_commit_hook_template_path
from autohooks.settings import Mode

# Create template manager
template = PreCommitTemplate()

# Render hook for different modes
poetry_hook = template.render(mode=Mode.POETRY)
pipenv_hook = template.render(mode=Mode.PIPENV) 
pythonpath_hook = template.render(mode=Mode.PYTHONPATH)

# Use custom template
custom_template_path = get_pre_commit_hook_template_path()
custom_template = PreCommitTemplate(custom_template_path)
hook_content = custom_template.render(mode=Mode.POETRY)

# Write rendered hook to file
from autohooks.hooks import get_pre_commit_hook_path
hook_path = get_pre_commit_hook_path()
hook_path.write_text(hook_content)
hook_path.chmod(0o775)

Template Constants

Shebang and template constants for different execution modes.

PYTHON3_SHEBANG = "/usr/bin/env python3"
PIPENV_SHEBANG = "/usr/bin/env -S pipenv run python3"  
POETRY_SHEBANG = "/usr/bin/env -S poetry run python"

# For OS's that don't support '/usr/bin/env -S'
PIPENV_MULTILINE_SHEBANG = (
    "/bin/sh\n"
    "\"true\" ''':'\n"
    'pipenv run python3 "$0" "$@"\n'
    'exit "$?"\n'
    "'''"
)

POETRY_MULTILINE_SHEBANG = (
    "/bin/sh\n"
    "\"true\" ''':'\n"  
    'poetry run python "$0" "$@"\n'
    'exit "$?"\n'
    "'''"
)

TEMPLATE_VERSION = 1

Usage Examples:

from autohooks.template import (
    PYTHON3_SHEBANG, POETRY_SHEBANG, PIPENV_SHEBANG,
    POETRY_MULTILINE_SHEBANG, PIPENV_MULTILINE_SHEBANG,
    TEMPLATE_VERSION
)
from autohooks.settings import Mode

def get_shebang_for_mode(mode: Mode) -> str:
    """Get appropriate shebang for execution mode."""
    if mode == Mode.POETRY:
        return POETRY_SHEBANG
    elif mode == Mode.POETRY_MULTILINE:
        return POETRY_MULTILINE_SHEBANG
    elif mode == Mode.PIPENV:
        return PIPENV_SHEBANG
    elif mode == Mode.PIPENV_MULTILINE:
        return PIPENV_MULTILINE_SHEBANG
    else:
        return PYTHON3_SHEBANG

# Check template version compatibility
def is_compatible_version(hook_version: int) -> bool:
    return hook_version == TEMPLATE_VERSION

Hook Validation

Comprehensive hook validation including version checking, mode validation, and compatibility assessment.

def check_hook_is_current(term: Terminal, pre_commit_hook: PreCommitHook) -> None:
    """
    Check if the installed hook is the current version.
    
    Args:
        term: Terminal interface for output
        pre_commit_hook: Hook instance to check
    """

def check_hook_mode(term: Terminal, config_mode: Mode, hook_mode: Mode) -> None:
    """
    Check if hook mode matches configuration mode.
    
    Args:
        term: Terminal interface for output
        config_mode: Mode from configuration
        hook_mode: Mode from installed hook
    """

Usage Examples:

from autohooks.precommit.run import check_hook_is_current, check_hook_mode
from autohooks.hooks import PreCommitHook
from autohooks.config import load_config_from_pyproject_toml
from autohooks.terminal import Terminal

# Validate hook installation
term = Terminal()
hook = PreCommitHook()
config = load_config_from_pyproject_toml()

# Check if hook is current
check_hook_is_current(term, hook)

# Check if modes match
if config.has_autohooks_config():
    config_mode = config.get_mode()
    hook_mode = hook.read_mode()
    check_hook_mode(term, config_mode, hook_mode)

Hook Execution Flow

Installation: PreCommitHook.write() creates executable hook script
Git Trigger: Git executes hook on commit attempt
Mode Detection: Hook reads shebang to determine execution mode
Dependency Resolution: Mode determines how to load autohooks and plugins
Plugin Execution: Autohooks loads and executes configured plugins
Result Processing: Hook returns status to git (0 = success, non-zero = failure)

Dependency Modes

PYTHONPATH Mode

Uses system Python and PYTHONPATH
Fastest execution, requires autohooks in system/virtual environment
Shebang: #!/usr/bin/env python3

POETRY Mode

Uses poetry run python for execution
Handles dependencies via Poetry
Shebang: #!/usr/bin/env -S poetry run python

PIPENV Mode

Uses pipenv run python3 for execution
Handles dependencies via Pipenv
Shebang: #!/usr/bin/env -S pipenv run python3

Multiline Modes

For systems not supporting env -S flag
Uses shell script wrapper for dependency management
Maintains compatibility across different Unix systems

Types

from pathlib import Path
from typing import Optional
from autohooks.settings import Mode
from autohooks.terminal import Terminal

Install with Tessl CLI

npx tessl i tessl/pypi-autohooks

docs

tessl/pypi-autohooks

hook-management.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Hook Management

Capabilities

Hook Installation and Management

Template Management

Template Constants

Hook Validation

Hook Execution Flow

Dependency Modes

PYTHONPATH Mode

POETRY Mode

PIPENV Mode

Multiline Modes

Types

hook-management.mddocs/