utkit 0.6.0__tar.gz → 0.8.0__tar.gz

{utkit-0.6.0 → utkit-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: utkit
-Version: 0.6.0
+Version: 0.8.0
 Summary: core libraries for development
 Author: TINS PJ
 Author-email: TINS PJ <tinspj1997@gmail.com>
@@ -27,80 +27,80 @@ Provides-Extra: standard
 Provides-Extra: store
 Description-Content-Type: text/markdown
 
-# utkit
-
-<div style="text-align: center; margin: 1.5rem 0;">
-  <img src="https://res.cloudinary.com/daft06bly/image/upload/v1777439163/logo_wussdc.png" alt="utkit" style="height: 100px; width: auto;" />
-</div>
-
-**utkit** is a collection of core libraries for Python development, providing ready-to-use utilities for common tasks such as authentication, email, encryption, caching, rate limiting, and more.
-
-
-- **Author:** TINS P JOSEPH
-- **Requires:** Python `>=3.12`
-- **License:** MIT
-- **PyPI:** [pypi.org/project/utkit](https://pypi.org/project/utkit/)
-
----
-
-## Installation
-
-```bash
-pip install utkit
-```
-
-Or with [uv](https://docs.astral.sh/uv/):
-
-```bash
-uv add utkit
-```
-
-### Optional extras
-
-| Extra | Included dependencies | Use for |
-|---|---|---|
-| `api` | `slowapi`, `pydantic` | Rate limiting and API schema for FastAPI |
-| `standard` | `psutil`, `jinja2` | Performance monitoring and HTML template rendering |
-| `store` | `redis` | Redis cache and key-value store |
-| `all` | all of the above | Install every optional dependency at once |
-
-```bash
-pip install "utkit[api]"
-pip install "utkit[standard]"
-pip install "utkit[store]"
-
-# All optional dependencies at once
-pip install "utkit[all]"
-```
-
----
-
-## Modules
-
-### Core
-
-| Module | Description |
-|---|---|
-| `auth` | Password hashing and verification |
-| `communication.mail` | Send HTML emails via SMTP |
-| `privacy.mask` | Mask sensitive data (email, phone, card, string) |
-| `privacy.security` | Fernet & RSA encryption, secret key generation, JWT |
-
-### Optional
-
-| Module | Extra | Description |
-|---|---|---|
-| `api.rate_limit` | `api` | Rate limiting for FastAPI via SlowAPI |
-| `api.schema` | `api` | Reusable Pydantic query models (pagination) |
-| `utils.performance` | `standard` | Execution time decorator and memory usage |
-| `template.render` | `standard` | HTML rendering from Jinja2 files and strings |
-| `store.redis` | `store` | Singleton Redis client with JSON serialisation |
-
----
-
-## CLI
-
-```bash
-utkit --version
-utkit docs
-```
+# utkit
+
+<div style="text-align: center; margin: 1.5rem 0;">
+  <img src="https://res.cloudinary.com/daft06bly/image/upload/v1777439163/logo_wussdc.png" alt="utkit" style="height: 100px; width: auto;" />
+</div>
+
+**utkit** is a collection of core libraries for Python development, providing ready-to-use utilities for common tasks such as authentication, email, encryption, caching, rate limiting, and more.
+
+
+- **Author:** TINS P JOSEPH
+- **Requires:** Python `>=3.12`
+- **License:** MIT
+- **PyPI:** [pypi.org/project/utkit](https://pypi.org/project/utkit/)
+
+---
+
+## Installation
+
+```bash
+pip install utkit
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add utkit
+```
+
+### Optional extras
+
+| Extra | Included dependencies | Use for |
+|---|---|---|
+| `api` | `slowapi`, `pydantic` | Rate limiting and API schema for FastAPI |
+| `standard` | `psutil`, `jinja2` | Performance monitoring and HTML template rendering |
+| `store` | `redis` | Redis cache and key-value store |
+| `all` | all of the above | Install every optional dependency at once |
+
+```bash
+pip install "utkit[api]"
+pip install "utkit[standard]"
+pip install "utkit[store]"
+
+# All optional dependencies at once
+pip install "utkit[all]"
+```
+
+---
+
+## Modules
+
+### Core
+
+| Module | Description |
+|---|---|
+| `auth` | Password hashing and verification |
+| `communication.mail` | Send HTML emails via SMTP |
+| `privacy.mask` | Mask sensitive data (email, phone, card, string) |
+| `privacy.security` | Fernet & RSA encryption, secret key generation, JWT |
+
+### Optional
+
+| Module | Extra | Description |
+|---|---|---|
+| `api.rate_limit` | `api` | Rate limiting for FastAPI via SlowAPI |
+| `api.schema` | `api` | Reusable Pydantic query models (pagination) |
+| `utils.performance` | `standard` | Execution time decorator and memory usage |
+| `template.render` | `standard` | HTML rendering from Jinja2 files and strings |
+| `store.redis` | `store` | Singleton Redis client with JSON serialisation |
+
+---
+
+## CLI
+
+```bash
+utkit --version
+utkit docs
+```

{utkit-0.6.0 → utkit-0.8.0}/README.md

@@ -1,77 +1,77 @@
-# utkit
-
-<div style="text-align: center; margin: 1.5rem 0;">
-  <img src="https://res.cloudinary.com/daft06bly/image/upload/v1777439163/logo_wussdc.png" alt="utkit" style="height: 100px; width: auto;" />
-</div>
-
-**utkit** is a collection of core libraries for Python development, providing ready-to-use utilities for common tasks such as authentication, email, encryption, caching, rate limiting, and more.
-
-
-- **Author:** TINS P JOSEPH
-- **Requires:** Python `>=3.12`
-- **License:** MIT
-- **PyPI:** [pypi.org/project/utkit](https://pypi.org/project/utkit/)
-
----
-
-## Installation
-
-```bash
-pip install utkit
-```
-
-Or with [uv](https://docs.astral.sh/uv/):
-
-```bash
-uv add utkit
-```
-
-### Optional extras
-
-| Extra | Included dependencies | Use for |
-|---|---|---|
-| `api` | `slowapi`, `pydantic` | Rate limiting and API schema for FastAPI |
-| `standard` | `psutil`, `jinja2` | Performance monitoring and HTML template rendering |
-| `store` | `redis` | Redis cache and key-value store |
-| `all` | all of the above | Install every optional dependency at once |
-
-```bash
-pip install "utkit[api]"
-pip install "utkit[standard]"
-pip install "utkit[store]"
-
-# All optional dependencies at once
-pip install "utkit[all]"
-```
-
----
-
-## Modules
-
-### Core
-
-| Module | Description |
-|---|---|
-| `auth` | Password hashing and verification |
-| `communication.mail` | Send HTML emails via SMTP |
-| `privacy.mask` | Mask sensitive data (email, phone, card, string) |
-| `privacy.security` | Fernet & RSA encryption, secret key generation, JWT |
-
-### Optional
-
-| Module | Extra | Description |
-|---|---|---|
-| `api.rate_limit` | `api` | Rate limiting for FastAPI via SlowAPI |
-| `api.schema` | `api` | Reusable Pydantic query models (pagination) |
-| `utils.performance` | `standard` | Execution time decorator and memory usage |
-| `template.render` | `standard` | HTML rendering from Jinja2 files and strings |
-| `store.redis` | `store` | Singleton Redis client with JSON serialisation |
-
----
-
-## CLI
-
-```bash
-utkit --version
-utkit docs
-```
+# utkit
+
+<div style="text-align: center; margin: 1.5rem 0;">
+  <img src="https://res.cloudinary.com/daft06bly/image/upload/v1777439163/logo_wussdc.png" alt="utkit" style="height: 100px; width: auto;" />
+</div>
+
+**utkit** is a collection of core libraries for Python development, providing ready-to-use utilities for common tasks such as authentication, email, encryption, caching, rate limiting, and more.
+
+
+- **Author:** TINS P JOSEPH
+- **Requires:** Python `>=3.12`
+- **License:** MIT
+- **PyPI:** [pypi.org/project/utkit](https://pypi.org/project/utkit/)
+
+---
+
+## Installation
+
+```bash
+pip install utkit
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add utkit
+```
+
+### Optional extras
+
+| Extra | Included dependencies | Use for |
+|---|---|---|
+| `api` | `slowapi`, `pydantic` | Rate limiting and API schema for FastAPI |
+| `standard` | `psutil`, `jinja2` | Performance monitoring and HTML template rendering |
+| `store` | `redis` | Redis cache and key-value store |
+| `all` | all of the above | Install every optional dependency at once |
+
+```bash
+pip install "utkit[api]"
+pip install "utkit[standard]"
+pip install "utkit[store]"
+
+# All optional dependencies at once
+pip install "utkit[all]"
+```
+
+---
+
+## Modules
+
+### Core
+
+| Module | Description |
+|---|---|
+| `auth` | Password hashing and verification |
+| `communication.mail` | Send HTML emails via SMTP |
+| `privacy.mask` | Mask sensitive data (email, phone, card, string) |
+| `privacy.security` | Fernet & RSA encryption, secret key generation, JWT |
+
+### Optional
+
+| Module | Extra | Description |
+|---|---|---|
+| `api.rate_limit` | `api` | Rate limiting for FastAPI via SlowAPI |
+| `api.schema` | `api` | Reusable Pydantic query models (pagination) |
+| `utils.performance` | `standard` | Execution time decorator and memory usage |
+| `template.render` | `standard` | HTML rendering from Jinja2 files and strings |
+| `store.redis` | `store` | Singleton Redis client with JSON serialisation |
+
+---
+
+## CLI
+
+```bash
+utkit --version
+utkit docs
+```

{utkit-0.6.0 → utkit-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "utkit"
-version = "0.6.0"
+version = "0.8.0"
 description = "core libraries for development"
 readme = "README.md"
 authors = [

{utkit-0.6.0 → utkit-0.8.0}/src/utkit/__init__.py

@@ -1,6 +1,6 @@
-def main() -> None:
-    print("Hello from utkit!")
-
-
-#TODO - Add more core utilities and libraries here as needed.   
+def main() -> None:
+    print("Hello from utkit!")
+
+
+#TODO - Add more core utilities and libraries here as needed.   
 #TODO : redis, logging,passlib, fastapi utils,sqlalchemy utils, etc.

{utkit-0.6.0 → utkit-0.8.0}/src/utkit/api/rate_limit/__init__.py

@@ -1,9 +1,9 @@
-from __future__ import annotations
-from slowapi import Limiter, _rate_limit_exceeded_handler as rate_limit_exceeded_handler
-from slowapi.util import get_remote_address
-
-__all__ = ["initialize_rate_limiter", "rate_limit_exceeded_handler"]
-
-
-def initialize_rate_limiter(rate_limit_default: str = "100/minute") -> Limiter:
-    return Limiter(key_func=get_remote_address, default_limits=[rate_limit_default])
+from __future__ import annotations
+from slowapi import Limiter, _rate_limit_exceeded_handler as rate_limit_exceeded_handler
+from slowapi.util import get_remote_address
+
+__all__ = ["initialize_rate_limiter", "rate_limit_exceeded_handler"]
+
+
+def initialize_rate_limiter(rate_limit_default: str = "100/minute") -> Limiter:
+    return Limiter(key_func=get_remote_address, default_limits=[rate_limit_default])

{utkit-0.6.0 → utkit-0.8.0}/src/utkit/api/rate_limit/error.py

@@ -1,4 +1,4 @@
-from __future__ import annotations
-from slowapi.errors import RateLimitExceeded as RateLimitExceededError
-
-__all__ = ["RateLimitExceededError"]
+from __future__ import annotations
+from slowapi.errors import RateLimitExceeded as RateLimitExceededError
+
+__all__ = ["RateLimitExceededError"]

{utkit-0.6.0 → utkit-0.8.0}/src/utkit/api/rate_limit/middleware.py

@@ -1,4 +1,4 @@
-from __future__ import annotations
-from slowapi.middleware import SlowAPIMiddleware as RateLimitMiddleware
-
-__all__ = ["RateLimitMiddleware"]
+from __future__ import annotations
+from slowapi.middleware import SlowAPIMiddleware as RateLimitMiddleware
+
+__all__ = ["RateLimitMiddleware"]

{utkit-0.6.0 → utkit-0.8.0}/src/utkit/api/schema/query.py

@@ -1,7 +1,7 @@
-from pydantic import BaseModel, Field
-
-
-class PaginationParams(BaseModel):
-    page: int = Field(1, gt=0 ,description="Page number, starting from 1")
-    page_size: int = Field(10, ge=0, description="Number of items per page")
+from pydantic import BaseModel, Field
+
+
+class PaginationParams(BaseModel):
+    page: int = Field(1, gt=0 ,description="Page number, starting from 1")
+    page_size: int = Field(10, ge=0, description="Number of items per page")
    

{utkit-0.6.0 → utkit-0.8.0}/src/utkit/auth/__init__.py

@@ -1,16 +1,16 @@
-from __future__ import annotations
-
-from pwdlib import PasswordHash
-
-password_hash = PasswordHash.recommended()
-
-__all__ = [
-    "verify_password","create_password_hash"
-]
-
-def verify_password(plain_password, hashed_password):
-    return password_hash.verify(plain_password, hashed_password)
-
-
-def create_password_hash(password):
+from __future__ import annotations
+
+from pwdlib import PasswordHash
+
+password_hash = PasswordHash.recommended()
+
+__all__ = [
+    "verify_password","create_password_hash"
+]
+
+def verify_password(plain_password, hashed_password):
+    return password_hash.verify(plain_password, hashed_password)
+
+
+def create_password_hash(password):
     return password_hash.hash(password)

{utkit-0.6.0 → utkit-0.8.0}/src/utkit/cli/__init__.py

@@ -1,52 +1,52 @@
-import subprocess
-from pathlib import Path
-
-import typer
-from importlib.metadata import version as get_version
-
-app = typer.Typer(no_args_is_help=True, help="utkit - core libraries for development.")
-
-
-def _version_callback(value: bool) -> None:
-    if value:
-        typer.echo(f"utkit v{get_version('utkit')}")
-        raise typer.Exit()
-
-
-@app.callback()
-def callback(
-    version: bool = typer.Option(
-        None,
-        "--version",
-        callback=_version_callback,
-        is_eager=True,
-        help="Show version and exit.",
-    ),
-) -> None:
-    pass
-
-
-@app.command()
-def version() -> None:
-    """Show the current version of utkit."""
-    typer.echo(f"utkit v{get_version('utkit')}")
-
-
-@app.command()
-def docs() -> None:
-    """Serve the utkit documentation locally on port 8005 and open in browser."""
-    docs_dir = Path(__file__).parent.parent / "documentation"
-    if not docs_dir.exists():
-        typer.echo(f"Documentation folder not found: {docs_dir}", err=True)
-        raise typer.Exit(code=1)
-
-    typer.echo("Starting docs server at http://localhost:8005 ...")
-    subprocess.run(
-        ["zensical", "serve", "--dev-addr", "localhost:8005", "--open"],
-        cwd=docs_dir,
-        check=True,
-    )
-
-
-def main() -> None:
-    app()
+import subprocess
+from pathlib import Path
+
+import typer
+from importlib.metadata import version as get_version
+
+app = typer.Typer(no_args_is_help=True, help="utkit - core libraries for development.")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"utkit v{get_version('utkit')}")
+        raise typer.Exit()
+
+
+@app.callback()
+def callback(
+    version: bool = typer.Option(
+        None,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    pass
+
+
+@app.command()
+def version() -> None:
+    """Show the current version of utkit."""
+    typer.echo(f"utkit v{get_version('utkit')}")
+
+
+@app.command()
+def docs() -> None:
+    """Serve the utkit documentation locally on port 8005 and open in browser."""
+    docs_dir = Path(__file__).parent.parent / "documentation"
+    if not docs_dir.exists():
+        typer.echo(f"Documentation folder not found: {docs_dir}", err=True)
+        raise typer.Exit(code=1)
+
+    typer.echo("Starting docs server at http://localhost:8005 ...")
+    subprocess.run(
+        ["zensical", "serve", "--dev-addr", "localhost:8005", "--open"],
+        cwd=docs_dir,
+        check=True,
+    )
+
+
+def main() -> None:
+    app()

utkit-0.8.0/src/utkit/communication/mail/smtp.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import smtplib
+import ssl
+from dataclasses import dataclass, field
+from email.message import EmailMessage
+
+
+@dataclass
+class SMTPConfig:
+    """SMTP connection configuration."""
+
+    host: str
+    port: int
+    username: str
+    password: str
+    use_tls: bool = True
+
+
+@dataclass
+class MailMessage:
+    """Email message parameters."""
+
+    subject: str
+    from_address: str
+    to: list[str]
+    cc: list[str] = field(default_factory=list)
+    bcc: list[str] = field(default_factory=list)
+    reply_to: str | None = None
+    text: str | None = None
+    html: str | None = None
+
+
+def send_mail(config: SMTPConfig, message: MailMessage) -> None:
+    """Send an email via SMTP.
+
+    Args:
+        config: SMTP server connection settings.
+        message: Email content and addressing details.
+
+    Raises:
+        ValueError: If both text and html are None, or if port is unsupported.
+    """
+    if not message.text and not message.html:
+        raise ValueError("Either 'text' or 'html' content must be provided")
+
+    msg = EmailMessage()
+    msg["Subject"] = message.subject
+    msg["From"] = message.from_address
+    msg["To"] = ", ".join(message.to)
+
+    if message.cc:
+        msg["Cc"] = ", ".join(message.cc)
+    if message.reply_to:
+        msg["Reply-To"] = message.reply_to
+
+    # Set content based on what's provided
+    if message.text and message.html:
+        # Both text and html: set text first, then add html as alternative
+        msg.set_content(message.text)
+        msg.add_alternative(message.html, subtype="html")
+    elif message.text:
+        # Only text
+        msg.set_content(message.text)
+    else:
+        # Only html
+        msg.set_content(message.html, subtype="html")
+
+    if config.port == 465:
+        # Use SMTP_SSL for port 465
+        context = ssl.create_default_context()
+        with smtplib.SMTP_SSL(config.host, config.port, context=context) as server:
+            server.login(config.username, config.password)
+            server.send_message(msg)
+    elif config.port == 587:
+        # Use SMTP with STARTTLS for port 587
+        with smtplib.SMTP(config.host, config.port) as server:
+            server.starttls()
+            server.login(config.username, config.password)
+            server.send_message(msg)
+    else:
+        raise ValueError(f"Unsupported SMTP port: {config.port}. Use 465 or 587.")