Metadata-Version: 2.4
Name: skilleter_modules
Version: 0.0.18
Summary: Modules used by my various Python projects (and hopefully useful to other people)
Author-email: John Skilleter <john@skilleter.org.uk>
Project-URL: Home, https://skilleter.org.uk
Project-URL: Repository, https://gitlab.com/skilleter/skilleter-modules
Project-URL: Issues, https://gitlab.com/skilleter/skilleter-extras/-/modules
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: pygit2
Dynamic: license-file

# 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:

```python
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.
