Metadata-Version: 2.1
Name: unibox
Version: 0.10.0
Summary: unibox provides unified interface for common file operations
Author-Email: trojblue <trojblue@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Project-URL: Homepage, https://trojblue.github.io/unibox
Project-URL: Documentation, https://trojblue.github.io/unibox
Project-URL: Changelog, https://trojblue.github.io/unibox/changelog
Project-URL: Repository, https://github.com/trojblue/unibox
Project-URL: Issues, https://github.com/trojblue/unibox/issues
Project-URL: Discussions, https://github.com/trojblue/unibox/discussions
Project-URL: Gitter, https://gitter.im/unibox/community
Project-URL: Funding, https://github.com/sponsors/trojblue
Requires-Python: >=3.10
Requires-Dist: boto3>=1.35.91
Requires-Dist: colorama>=0.4.6
Requires-Dist: colorlog>=6.9.0
Requires-Dist: datasets>=3.2.0
Requires-Dist: orjson>=3.10.13
Requires-Dist: pandas[parquet]>=2.2.3
Requires-Dist: pillow>=11.1.0
Requires-Dist: tomli>=2.2.1
Requires-Dist: tomli-w>=1.2.0
Requires-Dist: tqdm>=4.67.1
Description-Content-Type: text/markdown

# unibox

[![ci](https://github.com/trojblue/unibox/workflows/ci/badge.svg)](https://github.com/trojblue/unibox/actions?query=workflow%3Aci)
[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://trojblue.github.io/unibox/)
[![pypi version](https://img.shields.io/pypi/v/unibox.svg)](https://pypi.org/project/unibox/)
[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#unibox:gitter.im)

**A unified interface for seamless file operations across local, S3, and Hugging Face ecosystems.**

`unibox` simplifies loading, saving, and exploring data—whether it's a local CSV, an S3-hosted image, or an entire Hugging Face dataset. With a single API, you can handle diverse file types and storage backends effortlessly.

## Installation

```bash
pip install unibox
```

Or with `uv`:

```bash
uv tool install unibox
```



## Quick Start

Load anything, anywhere:

```python
import unibox as ub

# Local parquet file
df = ub.loads("data/sample.parquet")

# S3-hosted text file
lines = ub.loads("s3://my-bucket/notes.txt")

# Hugging Face dataset
dataset = ub.loads("hf://user/repo")
```

Save with ease:

```python
ub.saves(df, "s3://my-bucket/processed.parquet")
ub.saves(dataset, "hf://my-org/new-dataset")
```

List files or peek at data:

```python
# List all JPGs in an S3 folder
images = ub.ls("s3://bucket/images", exts=[".jpg"])

# Preview a dataset
ub.peeks(dataset)
```



## Why unibox?

- **Versatile**: Handles CSVs, images, datasets, and more—locally or remotely.
- **Simple**: One function call to load or save, no matter the source.
- **Transformative**: From quick data peeks to concurrent downloads, it scales with your needs.



Explore the full power in our [documentation](https://trojblue.github.io/unibox/).



## Contributing

Love unibox? Join us! Check out [CONTRIBUTING.md]() to get started.

Extra dev notes: see [README_dev.md](./README_dev.md).
