Kōyō

A utility library of reusable Python functions used throughout various projects in the Van de Plas lab.

Features

Module	Description
`koyo.click`	CLI helpers: path parsing, plugin loading, parameter tables, timed iterators
`koyo.system`	Platform detection, environment variable helpers, version checks, disk-space checks
`koyo.utilities`	Generic utils: nearest-index search (Numba-accelerated), array rescaling, chunking, size formatting
`koyo.timer`	Human-readable timing and `measure_time` context manager
`koyo.multicore`	`joblib`-backed multi-core helpers with RAM-aware CPU count
`koyo.logging`	`loguru`-based logging configuration
`koyo.color`	RGB/hex conversions and matplotlib colour utilities
`koyo.path`	File-system helpers: zero-copy `sendfile`, glob utilities, URI handling
`koyo.zarr`	Zarr-backed compressed array storage (Blosc/zip)
`koyo.sparse`	`scipy.sparse` convenience wrappers
`koyo.compression`	Generic data-compression utilities
`koyo.fig_mixin`	`FigureMixin` for composable figure export
`koyo.pdf_mixin`	PDF export backend
`koyo.pptx_mixin`	PowerPoint export backend (requires `pptx` extra)
`koyo.spectrum`	Spectroscopy (mass-spectrometry) utilities
`koyo.mosaic`	Rectangle-packing algorithm for image/figure mosaics
`koyo.decorators`	`retry` decorator with exponential back-off
`koyo.json`	JSON serialisation helpers
`koyo.toml`	TOML file handling

Installation

pip install koyo

Optional dependencies

# PowerPoint export
pip install koyo[pptx]

# Image-processing utilities (scikit-learn)
pip install koyo[image]

# Clipboard support
pip install koyo[clipboard]

# Windows shortcut support
pip install koyo[win]

# All extras
pip install koyo[pptx,image,clipboard,win]

Quick start

from koyo.utilities import find_nearest_index, rescale, format_size
from koyo.system import is_installed, get_version
from koyo.timer import measure_time

# Find the closest index in a sorted array
import numpy as np
arr = np.linspace(0, 100, 1000)
idx = find_nearest_index(arr, 42.7)

# Rescale an array to [0, 1]
scaled = rescale(arr, 0, 1)

# Human-readable byte size
print(format_size(1_500_000))  # "1.4M"

# Check whether a package is installed
if is_installed("zarr"):
    print(f"zarr {get_version('zarr')} is available")

# Time a block of code
with measure_time() as t:
    result = some_expensive_function()
print(f"Finished in {t():.3f}s")

Contributing

Contributions are always welcome. Please feel free to submit PRs with new features, bug fixes, or documentation improvements.

git clone https://github.com/vandeplaslab/koyo.git
cd koyo
pip install -e ".[dev]"

Run the test suite:

pytest

Run linting:

ruff check src/

Metadata

Release files for koyo 0.3.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for koyo 0.3.6
File	Size	Uploaded
koyo-0.3.6.tar.gz	123.6 kB	May 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for koyo 0.3.6
File	Interpreter	ABI	Platform	Reset
koyo-0.3.6-py3-none-any.whl 107.7 kB May 26, 2026	Python 3	none	any	Details

Total release size: 231.3 kB

Release files / koyo-0.3.6.tar.gz

Download URL	koyo-0.3.6.tar.gz
Size	123.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`5e60a819708bca9ca721c0e98279eeadbdf580756502b56b3a7e38fae35517ee`
BLAKE2b-256 checksum How to use checksums	`8a394bde81bbce5e798c5a24b9de28e4f0486d2b5a6a156a3fb4e35546eca86e`
Upload date	May 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Release files / koyo-0.3.6-py3-none-any.whl

Download URL	koyo-0.3.6-py3-none-any.whl
Size	107.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e3e4b51927d2e2eaa5e3fb5026aa2143a844c860fbd0b8390c4b338b5737779b`
BLAKE2b-256 checksum How to use checksums	`4b7a862be57cf1a3269cb205ce56506fcbc2c50c10854fd23e74196d9df765bb`
Upload date	May 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`