Metadata-Version: 2.4
Name: aldheeb-pytools
Version: 0.2.0
Summary: Python Tools library for some services
Project-URL: Homepage, https://github.com/eeeob/aldheeb-pytools
Author-email: Abdullah <aldheeb01@gmail.com>
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Provides-Extra: aiologic
Requires-Dist: aiologic>=0.16.0; extra == 'aiologic'
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>=46.0.4; extra == 'crypto'
Provides-Extra: dev
Requires-Dist: hatch<=1.16.5; extra == 'dev'
Requires-Dist: twine<=6.2.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: aioimaplib>=2.0.1; extra == 'full'
Requires-Dist: aiologic>=0.16.0; extra == 'full'
Requires-Dist: beautifulsoup4>=4.14.3; extra == 'full'
Requires-Dist: cryptography>=46.0.4; extra == 'full'
Requires-Dist: kurigram>=2.0.0; extra == 'full'
Requires-Dist: phonenumbers>=9.0.21; extra == 'full'
Requires-Dist: pycountry>=26.2.16; extra == 'full'
Requires-Dist: pymongo>=4.16.0; extra == 'full'
Provides-Extra: imap
Requires-Dist: aioimaplib>=2.0.1; extra == 'imap'
Provides-Extra: mongo
Requires-Dist: pymongo>=4.16.0; extra == 'mongo'
Provides-Extra: phone
Requires-Dist: phonenumbers>=9.0.21; extra == 'phone'
Provides-Extra: tg
Requires-Dist: kurigram>=2.0.0; extra == 'tg'
Description-Content-Type: text/markdown

# aldheeb-pytools 🛠️

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

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

---

## ✨ 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 aldheeb-pytools
```

### Install specific features

| Extra | Installs | Use for |
|-------|----------|---------|
| `crypto` | `cryptography` | Encryption & key derivation |
| `mongo` | `pymongo` | MongoDB utilities |
| `phone` | `phonenumbers` | Phone number parsing |
| `country` | `pycountry`, `phonenumbers` | Country info & region codes |
| `tg` | `kurigram`, `aiologic` | Telegram automation |
| `imap` | `aioimaplib` | IMAP email fetching |
| `bs4` | `beautifulsoup4` | HTML email parsing |
| `full` | everything above | All features |

```bash
# Single feature
pip install "aldheeb-pytools[crypto]"

# Multiple features
pip install "aldheeb-pytools[crypto, mongo, phone]"

# Everything
pip install "aldheeb-pytools[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.

---

## 🚀 Quick Start

### 🔐 Encryption example

```bash
pip install "aldheeb-pytools[crypto]"
```

```python
from pytools 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 "aldheeb-pytools[mongo]"
```

```python
from pytools import MongoIndex

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

### 🤖 Telegram example

```bash
pip install "aldheeb-pytools[tg]"
```

```python
from pytools import format_tg_username, mention_tg_user

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

---

## 🧪 Development Setup

```bash
git clone https://github.com/eeeob/aldheeb-pytools.git
cd aldheeb-pytools
pip install -e ".[dev]"
```

---

## 📄 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/aldheeb-pytools
