utkit 0.4.0__tar.gz → 0.6.0__tar.gz

utkit-0.6.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.3
+Name: utkit
+Version: 0.6.0
+Summary: core libraries for development
+Author: TINS PJ
+Author-email: TINS PJ <tinspj1997@gmail.com>
+Requires-Dist: cryptography>=47.0.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pwdlib[argon2]>=0.3.0
+Requires-Dist: pyjwt>=2.12.1
+Requires-Dist: typer>=0.20.0
+Requires-Dist: zensical>=0.0.37
+Requires-Dist: slowapi>=0.1.9 ; extra == 'all'
+Requires-Dist: pydantic>=2.13.3 ; extra == 'all'
+Requires-Dist: psutil>=7.2.2 ; extra == 'all'
+Requires-Dist: jinja2>=3.1.6 ; extra == 'all'
+Requires-Dist: redis>=7.4.0 ; extra == 'all'
+Requires-Dist: slowapi>=0.1.9 ; extra == 'api'
+Requires-Dist: pydantic>=2.13.3 ; extra == 'api'
+Requires-Dist: psutil>=7.2.2 ; extra == 'standard'
+Requires-Dist: jinja2>=3.1.6 ; extra == 'standard'
+Requires-Dist: redis>=7.4.0 ; extra == 'store'
+Requires-Python: >=3.12
+Provides-Extra: all
+Provides-Extra: api
+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-0.6.0/README.md

@@ -0,0 +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-0.6.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "utkit"
+version = "0.6.0"
+description = "core libraries for development"
+readme = "README.md"
+authors = [
+    { name = "TINS PJ", email = "tinspj1997@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "cryptography>=47.0.0",
+    "loguru>=0.7.3",
+    "pwdlib[argon2]>=0.3.0",
+    "pyjwt>=2.12.1",
+    "typer>=0.20.0",
+    "zensical>=0.0.37",
+]
+
+[project.optional-dependencies]
+api=[
+ "slowapi>=0.1.9",
+ "pydantic>=2.13.3",
+]
+standard=[
+    "psutil>=7.2.2",
+     "jinja2>=3.1.6",
+]
+store=[
+     "redis>=7.4.0",
+]
+all=[
+    "slowapi>=0.1.9",
+    "pydantic>=2.13.3",
+    "psutil>=7.2.2",
+    "jinja2>=3.1.6",
+    "redis>=7.4.0",
+]
+
+[project.scripts]
+utkit = "utkit.cli:main"
+
+[build-system]
+requires = ["uv_build >= 0.11.8, <0.12.0"]
+build-backend = "uv_build"

utkit-0.6.0/src/utkit/__init__.py

@@ -0,0 +1,6 @@
+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/src/utkit/api/rate_limit/__init__.py

@@ -0,0 +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])

utkit-0.6.0/src/utkit/api/rate_limit/error.py

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

utkit-0.6.0/src/utkit/api/rate_limit/middleware.py

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

utkit-0.6.0/src/utkit/api/schema/query.py

@@ -0,0 +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")
+   

utkit-0.6.0/src/utkit/auth/__init__.py

@@ -0,0 +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):
+    return password_hash.hash(password)

{utkit-0.4.0 → utkit-0.6.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.4.0 → utkit-0.6.0}/src/utkit/communication/mail/smtp.py

@@ -1,63 +1,63 @@
-from __future__ import annotations
-
-import smtplib
-from dataclasses import dataclass, field
-from email.mime.multipart import MIMEMultipart
-from email.mime.text import MIMEText
-
-
-@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]
-    html: str
-    cc: list[str] = field(default_factory=list)
-    bcc: list[str] = field(default_factory=list)
-    reply_to: str | None = None
-
-
-def send_mail(config: SMTPConfig, message: MailMessage) -> None:
-    """Send an HTML email via SMTP.
-
-    Args:
-        config: SMTP server connection settings.
-        message: Email content and addressing details.
-    """
-    msg = MIMEMultipart("alternative")
-    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
-
-    msg.attach(MIMEText(message.html, "html"))
-
-    all_recipients = message.to + message.cc + message.bcc
-
-    if config.use_tls:
-        with smtplib.SMTP(config.host, config.port) as server:
-            server.ehlo()
-            server.starttls()
-            server.login(config.username, config.password)
-            server.sendmail(message.from_address, all_recipients, msg.as_string())
-    else:
-        with smtplib.SMTP_SSL(config.host, config.port) as server:
-            server.login(config.username, config.password)
-            server.sendmail(message.from_address, all_recipients, msg.as_string())
+from __future__ import annotations
+
+import smtplib
+from dataclasses import dataclass, field
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+
+
+@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]
+    html: str
+    cc: list[str] = field(default_factory=list)
+    bcc: list[str] = field(default_factory=list)
+    reply_to: str | None = None
+
+
+def send_mail(config: SMTPConfig, message: MailMessage) -> None:
+    """Send an HTML email via SMTP.
+
+    Args:
+        config: SMTP server connection settings.
+        message: Email content and addressing details.
+    """
+    msg = MIMEMultipart("alternative")
+    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
+
+    msg.attach(MIMEText(message.html, "html"))
+
+    all_recipients = message.to + message.cc + message.bcc
+
+    if config.use_tls:
+        with smtplib.SMTP(config.host, config.port) as server:
+            server.ehlo()
+            server.starttls()
+            server.login(config.username, config.password)
+            server.sendmail(message.from_address, all_recipients, msg.as_string())
+    else:
+        with smtplib.SMTP_SSL(config.host, config.port) as server:
+            server.login(config.username, config.password)
+            server.sendmail(message.from_address, all_recipients, msg.as_string())

utkit-0.6.0/src/utkit/core/logging.py

@@ -0,0 +1,88 @@
+import inspect
+import sys
+from pathlib import Path
+from typing import Callable, List
+from loguru import logger
+
+
+def _add_class_name(record):
+    """Patch logger records to include the caller's class name."""
+    if record["extra"].get("classname") is not None:
+        return
+    frame = inspect.currentframe()
+    try:
+        while frame:
+            frame = frame.f_back
+            if frame and frame.f_globals.get("__name__") not in (
+                "loguru._logger",
+                __name__,
+            ):
+                cls = frame.f_locals.get("self") or frame.f_locals.get("cls")
+                if cls is not None:
+                    record["extra"]["classname"] = (
+                        cls.__name__ if isinstance(cls, type) else type(cls).__name__
+                    )
+                else:
+                    record["extra"]["classname"] = "Global"
+                break
+        else:
+            record["extra"]["classname"] = "Global"
+    finally:
+        del frame
+
+
+def setup_logging(
+    log_base_path="logs",
+    patchers: List[Callable] = [],
+    rotation: str = "1 day",
+    compression: str = "zip",
+    level: str = "INFO",
+    app_retention: str = "7 days",
+    meter_retention: str = "30 days",
+    **kwargs,
+) -> None:
+    log_path = Path(log_base_path)
+    log_path.mkdir(exist_ok=True)
+
+    def default_patcher(record):
+        for patcher in patchers or []:
+            patcher(record)
+
+    patchers.append(_add_class_name)
+    logger.remove()
+    logger.configure(patcher=default_patcher)
+
+    # Common format string (DRY principle)
+    log_format = (
+        "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
+        "<level>{level: <8}</level> | "
+        "<cyan>{name}</cyan>:<cyan>{extra[classname]}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | "
+        "{message} | <blue>Context: {extra}</blue>"
+    )
+
+    log_kwargs = {
+        "rotation": rotation,
+        "compression": compression,
+        "format": log_format,
+        "level": level,
+        **kwargs,
+    }
+
+    # 2. Console (Everything INFO+)
+    logger.add(sys.stderr, format=log_format, level="INFO", colorize=True)
+
+    # 3. Application Logs (Daily Rotation)
+    logger.add(
+        log_path / "application_{time:YYYY-MM-DD}.log",
+        filter=lambda r: r["extra"].get("type") == "app",
+        retention=app_retention,
+        **log_kwargs,
+    )
+
+    # 4. Metering Logs
+    logger.add(
+        log_path / "metering_{time:YYYY-MM-DD}.log",
+        filter=lambda r: r["extra"].get("type") == "meter",
+        retention=meter_retention,
+        **log_kwargs,
+    )