0
# Autohooks
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: autohooks
7
- **Language**: Python
8
- **Installation**: `pip install autohooks`
9
- **Supported Python**: 3.9+
10

11
## Core Imports
12

13
```python
14
import autohooks
15
```
16

17
For plugin development (main API):
18

19
```python
20
from autohooks.api import Config, ReportProgress
21
from autohooks.api import error, fail, info, bold_info, ok, out, warning
22
```
23

24
For git operations:
25

26
```python
27
from autohooks.api.git import get_staged_status, get_status, stage_files
28
from autohooks.api.git import StatusEntry, Status, stash_unstaged_changes
29
```
30

31
For path utilities:
32

33
```python
34
from autohooks.api.path import is_python_path, match
35
```
36

37
## Basic Usage
38

39
### Installation and Activation
40

41
```python
42
# Install hooks for the current project
43
import subprocess
44
subprocess.run(["autohooks", "activate"], check=True)
45

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

50
### Plugin Development
51

52
```python
53
from autohooks.api import Config, ReportProgress
54
from autohooks.api.git import get_staged_status, stage_files
55

56
def precommit(config: Config, report_progress: ReportProgress, **kwargs):
57
    """
58
    Main plugin entry point called during pre-commit hook execution.
59
    
60
    Args:
61
        config: Configuration object for accessing settings
62
        report_progress: Progress reporting interface
63
        **kwargs: Additional arguments for future compatibility
64
        
65
    Returns:
66
        int: 0 for success, non-zero for failure
67
    """
68
    # Get staged Python files
69
    status_entries = get_staged_status()
70
    python_files = [entry for entry in status_entries 
71
                   if entry.path.suffix == '.py']
72
    
73
    if not python_files:
74
        return 0
75
        
76
    # Initialize progress reporting
77
    report_progress.init(len(python_files))
78
    
79
    # Process each file
80
    for file_entry in python_files:
81
        # Perform processing (formatting, linting, etc.)
82
        process_file(file_entry.absolute_path())
83
        report_progress.update()
84
    
85
    return 0
86
```
87

88
## Architecture
89

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

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

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

100
## Capabilities
101

102
### Command Line Interface
103

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

106
```python { .api }
107
def main(): ...
108
def install_hooks(term: Terminal, args: Namespace): ...
109
def check_hooks(term: Terminal, args: Namespace): ...
110
def add_plugins(term: Terminal, args: Namespace): ...
111
def remove_plugins(term: Terminal, args: Namespace): ...
112
def list_plugins(term: Terminal, args: Namespace): ...
113
```
114

115
[Command Line Interface](./cli.md)
116

117
### Plugin API
118

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

121
```python { .api }
122
class Config:
123
    def get(self, *keys: str) -> 'Config': ...
124
    def get_value(self, key: str, default: Any = None) -> Any: ...
125

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

130
def error(message: str) -> None: ...
131
def info(message: str) -> None: ...
132
def ok(message: str) -> None: ...
133
```
134

135
[Plugin API](./plugin-api.md)
136

137
### Git Operations
138

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

141
```python { .api }
142
def get_status(files: Optional[Iterable[PathLike]] = None) -> List[StatusEntry]: ...
143
def get_staged_status(files: Optional[Iterable[PathLike]] = None) -> List[StatusEntry]: ...
144
def stage_files(files: Iterable[PathLike]) -> None: ...
145
def is_staged_status(status: StatusEntry) -> bool: ...
146
def is_partially_staged_status(status: StatusEntry) -> bool: ...
147

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

151
class stash_unstaged_changes: ...
152
```
153

154
[Git Operations](./git-operations.md)
155

156
### Configuration Management
157

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

160
```python { .api }
161
class AutohooksConfig:
162
    def from_dict(config_dict: Dict[str, Any]) -> 'AutohooksConfig': ...
163
    def from_toml(toml_file: Path) -> 'AutohooksConfig': ...
164
    def has_autohooks_config(self) -> bool: ...
165
    def get_pre_commit_script_names(self) -> List[str]: ...
166
    def get_mode(self) -> Mode: ...
167

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

171
[Configuration Management](./configuration.md)
172

173
### Hook Management
174

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

177
```python { .api }
178
class PreCommitHook:
179
    def exists(self) -> bool: ...
180
    def is_autohooks_pre_commit_hook(self) -> bool: ...
181
    def is_current_autohooks_pre_commit_hook(self) -> bool: ...
182
    def read_mode(self) -> Mode: ...
183
    def write(self, *, mode: Mode) -> None: ...
184

185
def get_pre_commit_hook_path(): ...
186
```
187

188
[Hook Management](./hook-management.md)
189

190
### Path Utilities
191

192
Path matching and validation utilities for file processing in plugins.
193

194
```python { .api }
195
def is_python_path(path: Optional[Path]) -> bool: ...
196
def match(path: PathLike, pattern_list: Iterable[str]) -> bool: ...
197
```
198

199
[Path Utilities](./path-utilities.md)
200

201
## Types
202

203
```python { .api }
204
class Mode(Enum):
205
    PIPENV = 1
206
    PYTHONPATH = 2
207
    POETRY = 3
208
    PIPENV_MULTILINE = 4
209
    POETRY_MULTILINE = 5
210
    UNDEFINED = -1
211
    UNKNOWN = -2
212

213
class Status(Enum):
214
    UNMODIFIED = " "
215
    MODIFIED = "M"
216
    ADDED = "A"
217
    DELETED = "D"
218
    RENAMED = "R"
219
    COPIED = "C"
220
    UPDATED = "U"
221
    UNTRACKED = "?"
222
    IGNORED = "!"
223

224
class AutohooksSettings:
225
    mode: Mode
226
    pre_commit: Iterable[str]
227
    def write(self, filename: Path) -> None: ...
228
```