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 that

are not staged, and
affect files that are partially staged.

Changes that are made before the context manager exits, are 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.