API¶

The autohooks API for writing plugins.

Main¶

Main Plugin API

class autohooks.api.Config¶

Config helper class for easier access to a tree of settings.

__init__(config_dict: Dict[str, Any] | None = None) → None¶

Create a new Config from a dictionary.

Parameters:: config_dict – Dictionary to be used for the Config.

get(*keys: str) → Config¶

Get a sub-config. If a sub-config with the passed keys does not exists an empty Config is returned.

Parameters:: *keys – Variable length of keys to resolve.

Example:

config = Config({"foo": {"bar": {"baz": 1}}})
baz = config.get("foo", "bar")
empty_config = config.get("lorem", "ipsum")

get_value(key: str, default: Any | None = None) → Any¶

Get a config value.

Parameters:

key – Key to lookup in the config.
default – Value to return if key is not in the config. By default None is returned.

Example:

config = Config({"foo": {"bar": {"baz": 1}}})
value = config.get("foo", "bar").get_value("baz")

is_empty() → bool¶: Returns True if the config has no data.

class autohooks.api.ReportProgress¶

A class to report progress of a plugin

__init__(progress: Progress, task_id: int) → None¶

init(total: int) → None¶

Init the progress with the total number to process

Parameters:: total – Most of the time this should be the number of files to process.

update(advance: int = 1) → None¶

Update the number of already processed steps/items/files.

This increases the progress indicator.

Parameters:: advance – Number of steps/items/files the progress advanced. By default 1.

autohooks.api.bold_info(message: str) → None¶

Highlight message as an strong information in the terminal

Parameters:: message – Message to print

autohooks.api.error(message: str) → None¶

Highlight message as an error in the terminal

Parameters:: message – Message to print

autohooks.api.fail(message: str) → None¶

Highlight message as a failure in the terminal

Parameters:: message – Message to print

autohooks.api.info(message: str) → None¶

Highlight message as an information in the terminal

Parameters:: message – Message to print

autohooks.api.ok(message: str) → None¶

Highlight message as a success/ok in the terminal

Parameters:: message – Message to print

autohooks.api.out(message: str)¶

Print message to the terminal without highlighting

Parameters:: message – Message to print

autohooks.api.warning(message: str) → None¶

Highlight message as a warning in the terminal

Parameters:: message – Message to print

Git¶

Plugin API for handling git related tasks

exception autohooks.api.git.GitError¶: Error raised if a git command fails.

class autohooks.api.git.Status¶

Status of a file in git

ADDED = 'A'¶

COPIED = 'C'¶

DELETED = 'D'¶

IGNORED = '!'¶

MODIFIED = 'M'¶

RENAMED = 'R'¶

UNMODIFIED = ' '¶

UNTRACKED = '?'¶

UPDATED = 'U'¶

class autohooks.api.git.StatusEntry¶

Status of a file in the git index and working tree.

Implements the os.PathLike protocol.

index¶: Status in the index

working_tree¶: Status in the working tree

path¶: Path to the file

root_path¶: An optional path to a root directory

old_path¶: Set for renamed files

__init__(status_string: str, root_path: Path | None = None) → None¶

absolute_path() → Path¶: Returns the absolute path of the file of this StatusEntry

autohooks.api.git.exec_git(*args: str, ignore_errors: bool = False) → str¶

Execute git command.

Raises:

GitError – A GitError is raised if the git commit fails and ignore_errors is False.

Parameters:

*args – Variable length argument list passed to git.
ignore_errors – Ignore errors if git command fails. Default: False.

Example:

exec_git("commit", "-m", "A new commit")

autohooks.api.git.get_staged_status(files: Iterable[PathLike] | None = None) → List[StatusEntry]¶

Get a list of StatusEntry instances containing only staged files.

Parameters:: files – (optional) specify an iterable of files and exclude all other paths for the status.
Returns:: A list of StatusEntry instances with files that are staged.

autohooks.api.git.get_status(files: Iterable[PathLike] | None = None) → List[StatusEntry]¶

Get information about the current git status.

Parameters:: files – (optional) specify an iterable of os.PathLike and exclude all other paths for the status.
Returns:: A list of StatusEntry instances that contain the status of the specific files.

autohooks.api.git.is_partially_staged_status(status: StatusEntry) → bool¶

Returns true, if the status of the given StatusEntry is partially staged.

Parameters:: status – A StatusEntry object that contains the filename, path and the git status.
Returns:: True if file is partially staged, False else.

autohooks.api.git.is_staged_status(status: StatusEntry) → bool¶

Returns true, if the status of the given StatusEntry is staged.

Parameters:: status – A StatusEntry object that contains the filename, path and the git status.
Returns:: True if file is staged, False else.

autohooks.api.git.stage_files(files: Iterable[PathLike]) → None¶

Add the passed os.PathLike to git staging index

Parameters:: files – An iterable of os.PathLike to add to the index

class autohooks.api.git.stash_unstaged_changes¶

A context manager that stashes changes on tracked files that are not added to the index. The stashed changes are restored when the context manager exits.

Example:

with stash_unstaged_changes():
    do_something()

__init__(files: Iterable[PathLike] | None = None) → None¶

Parameters:: files – Optional iterable of path like objects to consider for being staged. By default all files in the git status are considered.

Path¶

Plugin API for path checking

autohooks.api.path.is_python_path(path: Path | None) → bool¶

Function to check if path is a Python file.

Parameters:: path – A path to a file.
Returns:: True if path is a Python file.

autohooks.api.path.match(path: PathLike, pattern_list: Iterable[str]) → bool¶

Check if a path like object matches to one of the patterns.

Internally fnmatch is used. See https://docs.python.org/3/library/fnmatch.html for details.

Parameters:

path – os.PathLike to check if it matches to one of the patterns.
pattern_list – Iterable (e.g tuple or list) of patterns to match against the path..

Returns:

True if path matches a pattern of the list.