tinytools

A small utility library designed to provide common functionality for use in various projects. It includes tools for handling archives, images, logging, and video processing.

Features

• Archive Extraction: Safe extraction of ZIP and TAR archives with protection against path traversal attacks.
• Image Processing: Tools for converting NumPy arrays to PIL Images, creating image grids, and handling batches of images.
• Logging: Rich logging configuration with colored output and custom formatting.
• Video Processing: Utilities for loading videos as image lists or NumPy arrays, saving video files from image lists, and retrieving video metadata.

Installation

You can install tinytools directly from GitHub:

pip install git+https://github.com/alex-bene/tinytools.git

Or if you are using uv:

uv add git+https://github.com/alex-bene/tinytools.git

Usage Examples

Archive Extraction

import zipfile
from tinytools.archives import safe_zip_extract_all

with zipfile.ZipFile("example.zip", "r") as zip_ref:
    safe_zip_extract_all(zip_ref, "./extracted_files")

Image Processing

import numpy as np
from PIL import Image
from tinytools.image import img_from_array, imgs_from_array_batch

# Convert a NumPy array to PIL Image
img = img_from_array(np.random.rand(100, 100, 3))

# Convert a batch of images to PIL Images
batch = np.random.rand(5, 100, 100, 3)
imgs = imgs_from_array_batch(batch)

# Create an image grid
grid = image_grid(imgs, rows=2, cols=3)

Logging

from tinytools.logger import get_logger

logger = get_logger("my_app")
logger.info("This is an info message")

Video Processing

from tinytools.video import load_video, save_video

# Load video as list of PIL images
frames = load_video("input.mp4")

# Save list of PIL images as video
save_video(frames, "output.mp4", fps=30.0)

Development

To contribute to this project, please ensure you have uv installed.

1. Clone the repository:

   git clone https://github.com/alex-bene/tinyvis.git
   cd tinyvis

2. Install dependencies and pre-commit hooks:

   uv sync
   uv run pre-commit install

3. Run checks manually (optional):

   uv run ruff check
   uv run ruff format

This project uses Ruff for linting and formatting. We use pre-commit hooks to ensure code quality.

• Local: Hooks run before every commit (requires pre-commit install).
• GitHub Actions: Runs on every push to auto-fix issues on all branches.
• pre-commit.ci: Runs on every push to check code quality (fixes are handled by the GitHub Action).

License

This project is licensed under the MIT License.