<div align="center" markdown><a name="readme-top"></a>

<img src="https://raw.githubusercontent.com/microsoft/fluentui-emoji/main/assets/Grapes/3D/grapes_3d.png" style="height: 120px" />
<img src="https://gw.alipayobjects.com/zos/kitchen/qJ3l3EPsdW/split.svg" style="height: 120px" />
<img src="https://api.iconify.design/logos/python.svg" style="height: 120px; padding: 12px" />

# Grapes

Grapes is a comprehensive Python utility library offering robust tools for environment configuration, human-readable formatting, logging, progress tracking, serialization, and timing. Built with extensibility and performance in mind, it integrates seamlessly with popular libraries like Pydantic, Loguru, and Rich, providing developers with a powerful toolkit for building efficient and maintainable applications. <br />
[**Explore the docs »**](https://liblaf.github.io/grapes/)

[![PyPI - Downloads](https://img.shields.io/pypi/dm/liblaf-grapes?logo=PyPI&label=Downloads)](https://pypi.org/project/liblaf-grapes)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/liblaf-grapes?logo=Python&label=Python)](https://pypi.org/project/liblaf-grapes)
[![PyPI - Version](https://img.shields.io/pypi/v/liblaf-grapes?logo=PyPI&label=PyPI)](https://pypi.org/project/liblaf-grapes)
[![Codecov](https://img.shields.io/codecov/c/github/liblaf/grapes?logo=Codecov&label=Coverage)](https://codecov.io/gh/liblaf/grapes)
[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/liblaf/grapes/test.yaml?logo=GitHub%20Actions&label=Test)](https://github.com/liblaf/grapes/actions/workflows/test.yaml)
<br />
[![GitHub Contributors](https://img.shields.io/github/contributors/liblaf/grapes?logo=GitHub&label=Contributors)](https://github.com/liblaf/grapes/graphs/contributors)
[![GitHub Forks](https://img.shields.io/github/forks/liblaf/grapes)](https://github.com/liblaf/grapes/forks)
[![GitHub Repo Stars](https://img.shields.io/github/stars/liblaf/grapes)](https://github.com/liblaf/grapes/stargazers)
[![GitHub Issues](https://img.shields.io/github/issues/liblaf/grapes?logo=GitHub&label=Issues)](https://github.com/liblaf/grapes/issues)
[![GitHub License](https://img.shields.io/github/license/liblaf/grapes?label=License)](https://github.com/liblaf/grapes/blob/main/LICENSE)

[Changelog](https://github.com/liblaf/grapes/blob/main/CHANGELOG.md) · [Report Bug](https://github.com/liblaf/grapes/issues) · [Request Feature](https://github.com/liblaf/grapes/issues)

![](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png)

</div>

## ✨ Features

- 🍇 **Comprehensive Utility Library:** A rich collection of utility functions and classes to enhance your Python projects, covering a wide range of common tasks.
- ⚡ **High-Performance Timing:** Advanced timing utilities for precise performance measurement, including support for multiple time counters and human-readable duration formatting.
- 📊 **Progress Tracking:** Elegant progress bar and tracking functionality with customizable columns, making it easy to monitor the progress of long-running tasks.
- 🗂️ **Serialization and Deserialization:** Flexible and efficient data serialization and deserialization for JSON, TOML, YAML, and Pydantic models, ensuring seamless data handling.
- 📝 **Human-Readable Formats:** Functions to convert numerical values into human-readable formats, such as durations, counts, and throughput, enhancing the readability of your application's output.
- 🛠️ **Environment Configuration:** Simplified environment configuration management, allowing you to easily read and manage environment variables with a prefix.
- 🎨 **Rich Logging Integration:** Enhanced logging with Rich, Loguru, and IceCream, providing colorful, detailed, and user-friendly log outputs.
- 🧪 **Optional Imports:** Graceful handling of optional dependencies, ensuring that your application can run smoothly even if some dependencies are missing.
- 📄 **Text Processing:** Utilities for text processing, including comment stripping, to help clean up and process text data efficiently.
- 🤝 **Extensive Documentation:** Detailed and well-structured documentation, making it easy to understand and use the library's features.

<div align="right" markdown>

[![](https://img.shields.io/badge/-BACK_TO_TOP-black?style=flat-square)](#readme-top)

</div>

## 📦 Installation

To install `liblaf-grapes`, run the following command:

```bash
$ uv add liblaf-grapes
```

<div align="right" markdown>

[![](https://img.shields.io/badge/-BACK_TO_TOP-black?style=flat-square)](#readme-top)

</div>

## ⌨️ Local Development

You can use Github Codespaces for online development:

[![](https://github.com/codespaces/badge.svg)](https://codespaces.new/liblaf/grapes)

Or clone it for local development:

```bash
$ gh repo clone liblaf/grapes
$ cd grapes
$ just test
```

<div align="right" markdown>

[![](https://img.shields.io/badge/-BACK_TO_TOP-black?style=flat-square)](#readme-top)

</div>

## 🤝 Contributing

Contributions of all types are more than welcome, if you are interested in contributing code, feel free to check out our GitHub [Issues](https://github.com/liblaf/grapes/issues) to get stuck in to show us what you're made of.

[![](https://img.shields.io/badge/%F0%9F%A4%AF%20PR%20WELCOME-%E2%86%92-ffcb47?labelColor=black&style=for-the-badge)](https://github.com/liblaf/grapes/pulls)

[![](https://contrib.rocks/image?repo=liblaf%2Fgrapes)](https://github.com/liblaf/grapes/graphs/contributors)

<div align="right" markdown>

[![](https://img.shields.io/badge/-BACK_TO_TOP-black?style=flat-square)](#readme-top)

</div>

## 🔗 Links

### More Projects

- **[🍇 grapes](https://github.com/liblaf/grapes)** - Powerful Python utilities for logging, timing, and more, making development smoother!

### Credits

- **Python** - <https://www.python.org/>

<div align="right" markdown>

[![](https://img.shields.io/badge/-BACK_TO_TOP-black?style=flat-square)](#readme-top)

</div>

---

#### 📝 License

Copyright © 2025 [liblaf](https://github.com/liblaf). <br />
This project is [MIT](https://github.com/liblaf/grapes/blob/main/LICENSE) licensed.
