Path#

API#

class libjam.Path(*args, **kwargs)#

An extension of pathlib.Path with drawer’s functionality.

There are a few deviations from drawer’s functions:

First, following the pathlib.Path’s existing copy method, which works on both files and directories, this extension has only one copy_with_progress method that also works for both files and directories.

Second, the unlink_tree method, which links to shutil.rmtree, was added for convenience.

copy_with_progress(target, progress_callback: callable)#: Recursively copy this file or directory tree to the given destination while providing current progress.

get_tree_size() → int#: Returns the size of the given directory in bytes.

static to_readable_size(size: int, ndigits: int = 1) → tuple[float, str, str]#

Given a number of bytes, returns a human readable filesize, as a tuple.

Tuple format: (value, short unit name, long unit name) Example output: (6.9, ‘MB’, ‘MegaBytes’)

unlink_tree(ignore_errors=False, onerror=None, *, onexc=None, dir_fd=None)#

Recursively delete a directory tree.

If dir_fd is not None, it should be a file descriptor open to a directory; path will then be relative to that directory. dir_fd may not be implemented on your platform. If it is unavailable, using it will raise a NotImplementedError.

If ignore_errors is set, errors are ignored; otherwise, if onexc or onerror is set, it is called to handle the error with arguments (func, path, exc_info) where func is platform and implementation dependent; path is the argument to that function that caused it to fail; and the value of exc_info describes the exception. For onexc it is the exception instance, and for onerror it is a tuple as returned by sys.exc_info(). If ignore_errors is false and both onexc and onerror are None, the exception is reraised.

onerror is deprecated and only remains for backwards compatibility. If both onerror and onexc are set, onerror is ignored and onexc is used.

unlink_tree_with_progress(progress_callback: callable)#: Deletes the given directory while providing current progress.

start() → int#: Like xdg-open, but platform-aware.

pack_zip(dst)#: Packs the given directory to a zip file.

pack_zip_with_progress(dst, progress_callback: callable)#: Packs the given directory to a zip file while providing the current progress.

unpack_zip(dst)#: Unpacks the given zip archive to the specified directory.

unpack_zip_with_progress(dst, progress_callback: callable)#: Unpacks the given zip archive to the specified directory while providing current progress.

pack_7z(dst)#: Packs the given directory to a 7zip file.

unpack_7z(dst)#: Unpacks the given 7zip archive to the specified directory.

unpack_7z_with_progress(dst, progress_callback: callable)#: Unpacks the given tar archive to the specified directory while providing current progress.

unpack_rar(dst)#: Unpacks the given rar archive to the specified directory.

unpack_rar_with_progress(dst, progress_callback: callable)#: Unpacks the given tar archive to the specified directory while providing current progress.

can_unpack() → bool#: Checks if the given archive can be unpacked.

unpack(dst)#

Unpacks the given archive to the specified directory.

If the archive type is not supported NotImplementedError is raised.

unpack_with_progress(dst, progress_callback: callable)#

Unpacks the given archive to the specified directory while providing current progress.

If the archive type is not supported NotImplementedError is raised.

Example CLI for extracting archives#

extract.py file:

#! /usr/bin/env python3

# Imports
from libjam import Captain, writer, Path
import sys

# Main function
def extract(archive: str, out_directory: str):
  archive = Path(archive)
  out_directory = Path(out_directory)
  # Validating input
  if not archive.exists():
    captain.on_usage_error('file not found.')
  if not archive.is_file():
    captain.on_usage_error('given archive is not a file.')
  if not archive.can_unpack():
    captain.on_usage_error('unsupported archive type.')
  # Extracting
  with writer.ProgressBar(f"Extracting '{archive.name}'") as bar:
    archive.unpack_with_progress(out_directory, bar.update)

# Running
def main():
  captain = Captain(extract)
  args = captain.parse()
  return extract(*args)

if __name__ == '__main__':
  sys.exit(main())