Metadata-Version: 2.5
Name: pytrove
Version: 2.0.0
Summary: Utilities for async applications, data handling, files, archives and Telegram
Project-URL: Homepage, https://github.com/eeeob/pytrove
Project-URL: Source, https://github.com/eeeob/pytrove
Project-URL: Issues, https://github.com/eeeob/pytrove/issues
Project-URL: Releases, https://github.com/eeeob/pytrove/releases
Project-URL: Changelog, https://github.com/eeeob/pytrove/blob/main/CHANGELOG.md
Author-email: Abdullah <aldheeb01@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: archive,asyncio,json,telegram,utilities,validation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Archiving :: Compression
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: packaging>=22.0
Requires-Dist: typing-extensions>=4.4; python_version < '3.13'
Provides-Extra: archive
Requires-Dist: fastzip>=0.5; (sys_platform != 'win32') and extra == 'archive'
Requires-Dist: pathspec>=1.0; extra == 'archive'
Requires-Dist: zstandard>=0.22; (python_version < '3.14') and extra == 'archive'
Provides-Extra: bs4
Requires-Dist: beautifulsoup4>=4.14.3; extra == 'bs4'
Provides-Extra: country
Requires-Dist: phonenumbers>=9.0.21; extra == 'country'
Requires-Dist: pycountry>=26.2.16; extra == 'country'
Provides-Extra: crypto
Requires-Dist: cryptography>=50.0.0; extra == 'crypto'
Provides-Extra: full
Requires-Dist: aioimaplib>=2.0.1; extra == 'full'
Requires-Dist: babel>=2.14; extra == 'full'
Requires-Dist: beautifulsoup4>=4.14.3; extra == 'full'
Requires-Dist: cryptography>=50.0.0; extra == 'full'
Requires-Dist: fastzip>=0.5; (sys_platform != 'win32') and extra == 'full'
Requires-Dist: jsonref>=1.1; extra == 'full'
Requires-Dist: kurigram>=2.2.24; extra == 'full'
Requires-Dist: pathspec>=1.0; extra == 'full'
Requires-Dist: phonenumbers>=9.0.21; extra == 'full'
Requires-Dist: pycountry>=26.2.16; extra == 'full'
Requires-Dist: pymongo>=4.19.0; (python_version >= '3.11') and extra == 'full'
Requires-Dist: typeguard>=4.6; extra == 'full'
Requires-Dist: wrapt>=1.16; extra == 'full'
Requires-Dist: zstandard>=0.22; (python_version < '3.14') and extra == 'full'
Provides-Extra: imap
Requires-Dist: aioimaplib>=2.0.1; extra == 'imap'
Provides-Extra: json
Requires-Dist: jsonref>=1.1; extra == 'json'
Provides-Extra: locale
Requires-Dist: babel>=2.14; extra == 'locale'
Provides-Extra: mongo
Requires-Dist: pymongo>=4.19.0; (python_version >= '3.11') and extra == 'mongo'
Provides-Extra: phone
Requires-Dist: phonenumbers>=9.0.21; extra == 'phone'
Provides-Extra: proxy
Requires-Dist: wrapt>=1.16; extra == 'proxy'
Provides-Extra: tg
Requires-Dist: kurigram>=2.2.24; extra == 'tg'
Provides-Extra: typecheck
Requires-Dist: typeguard>=4.6; extra == 'typecheck'
Description-Content-Type: text/markdown

# pytrove 🛠️

[![PyPI version](https://img.shields.io/pypi/v/pytrove)](https://pypi.org/project/pytrove/)
[![Python versions](https://img.shields.io/pypi/pyversions/pytrove)](https://pypi.org/project/pytrove/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

An Arabic translation is kept in [`README.ar.md`](README.ar.md); this English text is the reference when the two differ.

**pytrove** is a modern Python utilities library providing async-ready helpers for backend systems, databases, cryptography, and Telegram automation.

> **Upgrading?** Every breaking change and how to migrate is in [CHANGELOG.md](CHANGELOG.md).

---

## ✨ Features

* ⚡ **Async-first design** built for modern `asyncio` applications
* 🗄️ **MongoDB utilities** for cleaner and safer database operations
* 🔐 **Cryptography helpers** (AES-GCM, secure key derivation)
* 🤖 **Telegram utilities** using Kurigram integration
* 📧 **IMAP email utilities** for fetching and parsing emails
* 🌍 **Country & phone utilities** for region and number handling
* 🧰 **General utilities** for parsing, validation, and data handling
* 🧩 **Fully typed codebase** with strict type hints support

---

## 📦 Installation

Starting from `v0.2.0`, the library uses **optional dependencies** — install only what you need.

### Minimal install (no optional dependencies)

```bash
pip install pytrove
```

### Install specific features

Each feature has its own extra; `full` installs all of them. The list of extras and the packages each one installs is defined in [`[project.optional-dependencies]` in `pyproject.toml`](pyproject.toml), which is the single source for it.

```bash
# Single feature
pip install "pytrove[crypto]"

# Multiple features
pip install "pytrove[crypto, mongo, phone]"

# Everything
pip install "pytrove[full]"
```

> **Note:** If you try to use a feature without its required packages installed, you'll get a clear `ImportError` with the exact install command needed.

### Install the latest version from GitHub

To install directly from the `main` branch (ahead of the latest PyPI release):

```bash
pip install git+https://github.com/eeeob/pytrove.git --force-reinstall
```
---
### 🔹 Without Deps
```bash
pip install git+https://github.com/eeeob/pytrove.git --force-reinstall --no-deps
```
---

## 🚀 Quick Start

### 🔐 Encryption example

```bash
pip install "pytrove[crypto]"
```

```python
from pytrove import encrypt, decrypt

key = "my-secure-key"

encrypted = encrypt("secret data", key)
print(encrypted)

decrypted = decrypt(encrypted, key)
print(decrypted)
```

### 🗄️ MongoDB example

```bash
pip install "pytrove[mongo]"
```

```python
from pytrove import MongoIndex

index = MongoIndex.from_dict({"key": {"field": 1}})
```

### 🤖 Telegram example

```bash
pip install "pytrove[tg]"
```

```python
from pytrove import format_tg_username, mention_tg_user

username = format_tg_username("@myuser")
mention = mention_tg_user(123456789, "John")
```

---

## 🧪 Development Setup

The only prerequisite is [`uv`](https://docs.astral.sh/uv/); it provisions the interpreter and the environment from `uv.lock`.

```bash
git clone https://github.com/eeeob/pytrove.git
cd pytrove
make sync        # the locked environment with every extra
make test        # the suite; also: make lint, make typecheck, make test-doctest
```

`CONTRIBUTING.md` describes the workflow and every recipe; CI runs the same recipes on Python 3.10 through 3.14, with and without the optional extras.

---

## 📄 License

This project is licensed under the **MIT License**.
See the [LICENSE](LICENSE) file for details.

---

## 📬 Contact

* Email: [aldheeb01@gmail.com](mailto:aldheeb01@gmail.com)
* GitHub: https://github.com/eeeob/pytrove
