skilleter-modules

A collection of Python modules used in my various other Python projects (readable, skilleter-thingy, skilleter-extras).

Module APIs

Import modules from the skilleter_modules package, for example:

from skilleter_modules import colour, files, git

Most functions raise the standard Python exception from the underlying operation. The command-wrapper modules (docker, git, and run) expose their own error types for failed external commands.

colour.py

Helpers for writing text containing lightweight colour markup as ANSI escape sequences.

Public functions:

• format(txt): returns txt with colour markup converted to ANSI. Supports [RED], [RED:text], 256-colour foreground codes such as [123], and 256-colour background codes such as [B123].
• write(txt=None, newline=True, stream=sys.stdout, indent=0, strip=False, cleareol=False, cr=False): writes formatted text to a stream. txt may be None, a string, or a list of strings.
• error(txt, newline=True, stream=sys.stderr, status=1, prefix=False): writes an error message and raises SystemExit(status).
• warning(txt, newline=True, stream=sys.stderr, prefix=False): writes a warning message.

dircolors.py

Formats filenames using GNU-compatible dircolors and LS_COLORS data. Large parts of this code are Copyright 2019 Allen Wild <allenwild93@gmail.com> and released under the Apache-2.0 licence.

docker.py

Small wrapper around the Docker CLI.

Public exception:

• DockerError: raised when an underlying Docker command fails.

Public functions:

• instances(all=False): returns a list of container IDs from docker ps -q. With all=True, stopped containers are included.
• stop(instance, force=False): stops a container by ID or name.
• rm(instance, force=False): removes a container by ID or name.
• images(): yields image IDs from docker images -q.
• rmi(image, force=False): removes an image by ID or name.

files.py

Miscellaneous file-related helpers for backup creation, file-type detection, and size formatting.

Public functions:

• is_binary_file(filename): returns True if file --mime reports the file as binary.
• file_type(filename, mime=False): returns the file --brief description, or MIME description when mime=True. Raises FileNotFoundError if the path is not an accessible file.
• format_size(size, always_suffix=False): converts a byte count to a human-readable binary-unit string.
• backup(filename, extension='bak', copyfile=True, timestamps=True): creates a backup by replacing or adding the file extension. Missing files are ignored. With copyfile=False, the original file is renamed instead of copied.

git.py

A git helper library built around the Git command-line tool, with some pygit2 support. Unless documented otherwise in code, functions return output from the corresponding git command as a list of strings and raise GitError on failure.

Public exception:

• GitError: command failure exception, subclassing run.RunError.

Command execution and repository setup:

• git(cmd, stdout=None, stderr=None, path=None): runs a git command.
• git_run_status(cmd, stdout=None, stderr=None, path=None, redirect=True): runs a git command and returns (output, status_code).
• clone(reponame, working_tree=None): clones a repository.
• init(reponame, bare=False, path=None): initializes a repository.

Refs, branches, tags, and commits:

• iscommit(commit, remote=False, remote_only=False, path=None): checks whether a commit, branch, or tag exists.
• branch(branchname='HEAD', path=None): returns the current or named branch.
• branches(all=False, path=None, remote=False): returns branch names.
• branch_name(branch, path=None): returns a full branch reference name.
• isbranch(branchname, local=True, remote=False, path=None): checks whether a name is a branch.
• matching_branch(branchname, case=False, path=None): finds matching branches.
• default_branches(path=None), is_default_branch(branchname=None, path=None), and default_branch(path=None, defaults=None): inspect default branch configuration.
• checkout(branch, create=False, commit=None, path=None): checks out a branch.
• delete_branch(branch, force=False, remote=False, path=None): deletes a local or remote branch.
• remote_tracking_branch(branch, path=None): returns a branch's upstream ref.
• current_commit(short=False, path=None) and commit_id(commit='HEAD', short=False, path=None): return commit IDs.
• tag(path=None), tags(path=None), tag_exists(tag, remote=None, path=None), tag_apply(tag, commit=None, push=False, path=None), and tag_delete(tag, push=False, path=None): inspect, create, and delete tags.
• parents(commit=None, ignore=None, path=None): finds possible parent branches for a commit.
• find_common_ancestor(branch1='HEAD', branch2='master', path=None): returns the common ancestor of two branches.
• get_commits(commit1, commit2, path=None) and commit_count(commit1, commit2, path=None): inspect commits between two revisions.
• author(commit, path=None): returns a commit author.
• commit_changes(commit='HEAD', path=None): returns files changed in a commit.
• matching_commit(name, path=None): finds branches, tags, or commits matching a name.
• log(branch1, branch2=None, path=None): returns git log output.
• object_type(name, path=None): returns the git object type.

Repository state and file operations:

• pull(repo=None, all=False, path=None), fetch(all=False, path=None), merge(branch, path=None), abort_merge(path=None), rebase(branch, path=None), abort_rebase(path=None), and update(clean=False, all=False, path=None): wrap common repository update operations.
• rebase_required(branch, parent, path=None): reports whether a branch needs rebasing against its parent.
• rebasing(path=None), bisecting(path=None), and merging(path=None): report in-progress repository operations.
• status_info(ignored=False, untracked=False, path=None, all_untracked=False): returns git status as a dictionary.
• status(ignored=False, untracked=False, path=None, all_untracked=False): returns git status records as a list.
• project(short=False, path=None): returns the current git project name, optionally shortened to the final path component.
• working_tree(path=None), git_dir(path=None), and tree_path(filename, path=None): return repository paths.
• files(dir=None, path=None): returns tracked files from git ls-files.
• add(files, path=None), rm(files, path=None), commit(files=None, message=None, all=False, amend=False, foreground=False, patch=False, dry_run=False, path=None), push(all=False, mirror=False, tags=False, atomic=False, dry_run=False, follow_tags=False, receive_pack=False, repo=None, force=False, delete=False, prune=False, verbose=False, set_upstream=False, push_options=None, signed=None, force_with_lease=False, no_verify=False, repository=None, refspec=None, path=None), reset(sha1, path=None), and clean(recurse=False, force=False, dry_run=False, quiet=False, exclude=None, ignore_rules=False, remove_only_ignored=False, path=None): wrap the equivalent git file/index/history commands.
• stash(path=None): returns the stash list.

Diffs, remotes, config, and search:

• difftool(commit_1=None, commit_2=None, files=None, tool=None, path=None): runs git difftool.
• commit_info(commit_1=None, commit_2=None, paths=None, diff_stats=False, path=None): returns commit or range details.
• diff(commit=None, renames=True, copies=True, relative=False, path=None): returns differences for a commit context.
• diff_status(commit1, commit2='HEAD', path=None): returns True when two commits have no differences.
• show(revision, filename, outfile=None, path=None): returns or writes a file from a revision.
• remotes(path=None) and remote_names(path=None): inspect configured remotes.
• remote_prune(remote, dry_run=False, path=None): returns prunable remote tracking branches.
• set_upstream(branch, upstream=None, path=None): sets a branch upstream.
• config_get(section, key, source=None, defaultvalue=None, path=None), config_set(section, key, value, source=None, path=None), and config_rm(section, key, source=LOCAL, path=None): read and update git configuration.
• ref(fields=('objectname',), sort=None, remotes=False, path=None): iterates refs with git for-each-ref.
• grep(pattern, git_dir=None, work_tree=None, options=None, wildcards=None, path=None): runs git grep.

path.py

Filesystem path helpers.

Public exception:

• PathError: module-specific path exception.

Public functions:

• is_subdirectory(root_path, sub_path): returns True when sub_path is a strict descendant of root_path.
• trimpath(full_path, trim_width): returns a shortened absolute path that preserves the final path segment, converts the home directory prefix to ~, and inserts ... when trimming is needed.

popup.py

Curses popup helper.

Public class:

• PopUp(screen, msg, colour, waitkey=False, sleep=1, centre=True, refresh=True): context manager that displays a centred curses panel while the with block is active. It can wait for a keypress or keep the popup visible for a minimum duration before closing.

run.py

Subprocess helpers that can capture stdout/stderr while optionally streaming output to the console.

Public exception:

• RunError: raised for non-zero subprocess exit status. The exception has msg and status attributes.

Public functions:

• command(cmd, show_stdout=False, show_stderr=False): runs a command string or argv list, captures both streams, optionally echoes them, and returns (returncode, stdout_lines, stderr_lines).
• capture_output(cmd, input_stream, output_streams): reads from a process stream and writes/appends the output to each configured sink.
• run(command, stdout=None, stderr=None, output=None): runs a command and returns captured stdout lines, or stderr lines if stdout is empty. Raises RunError on non-zero status.

tfm_pane.py

Console-pane-handling code for TFM. The module is currently reserved for TFM integration and does not expose a stable public function or class API.

tidy.py

Helpers for normalising logs and command output for display or comparison.

Public functions:

• debug_format(data): replaces ANSI escape sequences with readable {ESC...} tokens.
• convert_ansi(data, light=True): rewrites ANSI colour sequences for light or dark backgrounds.
• remove_times(data): replaces common date, time, and elapsed-duration text.
• remove_sha1(data): replaces SHA1 hashes.
• remove_sha256(data): replaces SHA256 hashes.
• remove_aws_ids(data): replaces common AWS resource and request IDs.
• remove_speeds(data): replaces data transfer rates.
• remove_ansi(text): removes ANSI escape sequences.