pytrove 1.0.0__tar.gz

pytrove-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdullah (github.com/eeeob)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytrove-1.0.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: pytrove
+Version: 1.0.0
+Summary: Python Tools library for some services
+Project-URL: Homepage, https://github.com/eeeob/pytrove
+Author-email: Abdullah <aldheeb01@gmail.com>
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions>=4.0; python_version < '3.13'
+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>=48.0.1; extra == 'crypto'
+Provides-Extra: dev
+Requires-Dist: hatch<=1.16.5; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine<=6.2.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: aioimaplib>=2.0.1; extra == 'full'
+Requires-Dist: beautifulsoup4>=4.14.3; extra == 'full'
+Requires-Dist: cryptography>=48.0.1; extra == 'full'
+Requires-Dist: kurigram>=2.1.35; extra == 'full'
+Requires-Dist: phonenumbers>=9.0.21; extra == 'full'
+Requires-Dist: pycountry>=26.2.16; extra == 'full'
+Requires-Dist: pymongo>=4.6.3; extra == 'full'
+Requires-Dist: typeguard>=4.3; extra == 'full'
+Requires-Dist: wrapt>=1.16; extra == 'full'
+Provides-Extra: imap
+Requires-Dist: aioimaplib>=2.0.1; extra == 'imap'
+Provides-Extra: mongo
+Requires-Dist: pymongo>=4.6.3; 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.1.35; extra == 'tg'
+Provides-Extra: typecheck
+Requires-Dist: typeguard>=4.3; 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)
+
+**pytrove** 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 pytrove
+```
+
+### 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` | Telegram automation |
+| `imap` | `aioimaplib` | IMAP email fetching |
+| `bs4` | `beautifulsoup4` | HTML email parsing |
+| `typecheck` | `typeguard` | Runtime type validation (`validate_type`) |
+| `proxy` | `wrapt` | Restricted object proxies (`RestrictedProxy`, `WeakRestrictedProxy`, `AioThreadWorker.get_loop`) |
+| `full` | everything above | All features |
+
+```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
+```
+
+---
+
+## 🚀 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
+
+```bash
+git clone https://github.com/eeeob/pytrove.git
+cd pytrove
+pip install -e ".[full,dev]"
+```
+
+### Running tests
+
+```bash
+pytest
+```
+
+Tests run in CI across every Python version listed in the classifiers above (3.10 through 3.14), both with the minimal (no-extras) install and with `[full,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/pytrove

pytrove-1.0.0/README.md

@@ -0,0 +1,147 @@
+# 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)
+
+**pytrove** 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 pytrove
+```
+
+### 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` | Telegram automation |
+| `imap` | `aioimaplib` | IMAP email fetching |
+| `bs4` | `beautifulsoup4` | HTML email parsing |
+| `typecheck` | `typeguard` | Runtime type validation (`validate_type`) |
+| `proxy` | `wrapt` | Restricted object proxies (`RestrictedProxy`, `WeakRestrictedProxy`, `AioThreadWorker.get_loop`) |
+| `full` | everything above | All features |
+
+```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
+```
+
+---
+
+## 🚀 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
+
+```bash
+git clone https://github.com/eeeob/pytrove.git
+cd pytrove
+pip install -e ".[full,dev]"
+```
+
+### Running tests
+
+```bash
+pytest
+```
+
+Tests run in CI across every Python version listed in the classifiers above (3.10 through 3.14), both with the minimal (no-extras) install and with `[full,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/pytrove

pytrove-1.0.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[project]
+name = "pytrove"
+dynamic = ["version"]
+description = "Python Tools library for some services"
+requires-python = ">=3.10"
+authors = [{ name = "Abdullah", email = "aldheeb01@gmail.com" }]
+readme = "README.md"
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "typing_extensions>=4.0; python_version<'3.13'",
+]
+
+
+[project.urls]
+"Homepage" = "https://github.com/eeeob/pytrove"
+
+[project.optional-dependencies]
+dev = [
+    "hatch<=1.16.5",
+    "twine<=6.2.0",
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+]
+
+
+mongo = ["pymongo>=4.6.3"]
+country = ["pycountry>=26.2.16", "phonenumbers>=9.0.21"]
+crypto = ["cryptography>=48.0.1"]
+bs4 = ["beautifulsoup4>=4.14.3"]
+imap = ["aioimaplib>=2.0.1"]
+phone = ["phonenumbers>=9.0.21"]
+tg = ["kurigram>=2.1.35"]
+typecheck = ["typeguard>=4.3"]
+proxy = ["wrapt>=1.16"]
+
+full = [
+    "pytrove[imap,phone,country,bs4,mongo,tg,crypto,typecheck,proxy]"
+]
+
+[tool.hatch.build.targets.sdist]
+exclude = [".github/",]
+
+[tool.hatch.version]
+path = "pytrove/__meta__.py"
+
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+ignore-vcs = true
+packages = ["pytrove"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

pytrove-1.0.0/pytrove/__init__.py

@@ -0,0 +1,39 @@
+from .__meta__ import __version__
+
+from .validate_tools import *
+from .date_tools import *
+from .num_tools import *
+from .files_tools import *
+from .iter_tools import *
+from .text_tools import *
+from .async_tools import *
+from .misc_tools import *
+from .tg_tools import *
+from .phone_tools import *
+from .country_tools import *
+from .crypto_tools import *
+from .data_tools import *
+from .callable_tools import *
+from .logging_tools import *
+from .email_tools import *
+from .classes import *
+
+__all__ = (
+    *validate_tools.__all__, 
+    *date_tools.__all__, 
+    *num_tools.__all__, 
+    *files_tools.__all__, 
+    *iter_tools.__all__, 
+    *text_tools.__all__, 
+    *async_tools.__all__, 
+    *misc_tools.__all__, 
+    *tg_tools.__all__, 
+    *phone_tools.__all__, 
+    *country_tools.__all__, 
+    *crypto_tools.__all__, 
+    *data_tools.__all__, 
+    *callable_tools.__all__, 
+    *classes.__all__, 
+    *logging_tools.__all__, 
+    *email_tools.__all__, 
+)

pytrove-1.0.0/pytrove/__meta__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

pytrove-1.0.0/pytrove/_async_tools.py

@@ -0,0 +1,202 @@
+import asyncio
+import sys
+
+from typing import Any, Awaitable, List, Optional, Union, TYPE_CHECKING, overload
+from .typings import _T, _True, _False
+
+
+_PY314 = sys.version_info >= (3, 14)
+
+def _get_fut_loop(fut):
+    try:
+        get_loop = fut.get_loop
+    except AttributeError:
+        pass
+    else:
+        return get_loop()
+    return fut._loop
+
+def _get_running_loop() -> Optional[asyncio.AbstractEventLoop]:
+    try:
+        return asyncio.get_running_loop()
+    except RuntimeError:
+        return 
+
+
+class _GatheringFuture(asyncio.Future):
+    def __init__(self, children, *, loop):
+        super().__init__(loop=loop)
+
+        self._children = children
+
+    if not TYPE_CHECKING:
+        @property
+        def cancel_message(self) -> Optional[Any]:
+            return getattr(self, "_cancel_message", None)
+        
+        @cancel_message.setter
+        def cancel_message(self, value: Optional[Any]):
+            setattr(self, "_cancel_message", value)
+
+
+        def cancel(self, msg: Optional[Any] = None) -> bool:
+            # Cancelling the outer future does not cancel *this* future
+            # immediately -- it forwards the request to every child and lets
+            # them unwind first, exactly like asyncio.gather(). _done_callback
+            # only turns `outer` itself into a CancelledError once every child
+            # has actually finished (npending == 0); until then `outer` stays
+            # pending even though a cancellation is already in flight.
+            if self.done():
+                return False
+
+            ret = False
+
+            for child in self._children:
+                if child.cancel(msg=msg):
+                    ret = True
+
+            if ret:
+                self.cancel_message = "" if msg is None else msg
+
+            return ret
+
+
+@overload
+def _gather_cancel_on_error(*awaitables: Awaitable[_T], return_exceptions: _False = False) -> asyncio.Future[List[_T]]:...
+@overload
+def _gather_cancel_on_error(*awaitables: Awaitable[_T], return_exceptions: _True) -> asyncio.Future[List[Union[_T, Exception]]]:...
+def _gather_cancel_on_error(*awaitables, return_exceptions = False):
+    """Reimplementation of asyncio.gather() that cancels every sibling as soon
+    as one fails (asyncio.gather() itself leaves the rest running).
+
+    `_done_callback` fires once per child future and does one of three things:
+      - if `outer` is already resolved (a prior sibling failed first, or the
+        caller cancelled `outer` itself -- see _GatheringFuture.cancel above),
+        the result/exception is only drained via fut.exception() so asyncio's
+        "exception was never retrieved" warning doesn't fire on a future
+        nobody will ever await again;
+      - if this child failed and `return_exceptions` is False, `outer` is
+        failed with that exception and every other still-running child is
+        cancelled -- this is the actual "cancel on error" behavior;
+      - once every child has reported in (`npending == 0`), results are
+        collected in the original awaitables order and `outer` is resolved --
+        as a success, or as CancelledError if `outer` was cancelled while
+        children were still finishing (see _GatheringFuture.cancel, which
+        lets already-running children finish instead of force-stopping them).
+
+    `awaitable_2_fut` deduplicates: passing the same awaitable twice must not
+    schedule it twice or count it twice toward `npending`, since asyncio.gather
+    has the same behavior for repeated arguments.
+
+    On 3.14+, `future_add_to_awaited_by`/`future_discard_from_awaited_by` keep
+    each child's "awaited by" introspection link pointed at the *caller's*
+    task instead of this function's internal bookkeeping -- otherwise tools
+    like asyncio's task graph (or Task.print_stack()) would show the children
+    as awaited by a frame that already returned.
+    """
+
+    if not awaitables:
+        outer = asyncio.get_event_loop().create_future()
+        outer.set_result([])
+        return outer
+
+    if _PY314:
+        loop = _get_running_loop()
+        current_task = None if loop is None else asyncio.current_task(loop)
+    else:
+        loop = None
+        current_task = None
+    
+
+    def _done_callback(fut, current_task = current_task):
+        nonlocal npending
+        npending -= 1
+
+        if _PY314 and current_task is not None:
+            asyncio.future_discard_from_awaited_by(fut, current_task)
+
+        if outer is None or outer.done():
+            if not fut.cancelled():
+                fut.exception()  # استهلاك الاستثناء لمنع تحذير asyncio
+            return
+
+        if not return_exceptions:
+            try:
+                exc = fut.exception()
+            except asyncio.CancelledError as e:
+                exc = e
+
+            if exc is not None:
+                outer.set_exception(exc)
+
+                for child in children:
+                    if child is not fut and not child.done():
+                        child.cancel()
+
+                return
+
+        if npending == 0:
+            results = []
+
+            for child in children:
+                try:
+                    result = child.exception()
+                except asyncio.CancelledError as e:
+                    result = e
+
+                if result is None:
+                    result = child.result()
+
+                results.append(result)
+
+            if (cancel_message := outer.cancel_message) is not None:
+                outer.set_exception(asyncio.CancelledError(cancel_message))
+            else:
+                outer.set_result(results)
+    
+    
+    
+    npending = 0
+    outer = None
+    
+    done_futs = []
+    children = []
+
+    awaitable_2_fut = {}
+    
+
+    for awaitable in awaitables:
+        fut = awaitable_2_fut.get(awaitable)
+
+        if fut is None:
+            fut = asyncio.ensure_future(awaitable, loop=loop)
+
+            if loop is None:
+                loop = _get_fut_loop(fut)
+
+            if fut is not awaitable:
+                fut._log_destroy_pending = False
+
+            npending += 1
+            awaitable_2_fut[awaitable] = fut
+
+            if fut.done():
+                done_futs.append(fut)
+            else:
+                if _PY314 and current_task is not None:
+                    asyncio.future_add_to_awaited_by(fut, current_task)
+
+                fut.add_done_callback(_done_callback)
+
+        children.append(fut)
+
+    outer = _GatheringFuture(children, loop=loop)
+
+    for fut in done_futs:
+        _done_callback(fut)
+
+    return outer
+
+
+
+