svc-infra 0.1.706__py3-none-any.whl → 1.1.0__py3-none-any.whl

svc_infra/storage/easy.py

@@ -6,7 +6,6 @@ Simplifies storage backend initialization with sensible defaults.
 
 import logging
 import os
-from typing import Optional
 
 from .backends import LocalBackend, MemoryBackend, S3Backend
 from .base import StorageBackend
@@ -16,7 +15,7 @@ logger = logging.getLogger(__name__)
 
 
 def easy_storage(
-    backend: Optional[str] = None,
+    backend: str | None = None,
     **kwargs,
 ) -> StorageBackend:
     """
@@ -135,9 +134,7 @@ def easy_storage(
         secret_key = kwargs.get("secret_key")
 
         if not access_key or not secret_key:
-            access_key_from_settings, secret_key_from_settings = (
-                settings.get_s3_credentials()
-            )
+            access_key_from_settings, secret_key_from_settings = settings.get_s3_credentials()
             access_key = access_key or access_key_from_settings
             secret_key = secret_key or secret_key_from_settings
 
@@ -165,14 +162,13 @@ def easy_storage(
     elif backend_type == "gcs":
         # Google Cloud Storage backend
         raise NotImplementedError(
-            "GCS backend not yet implemented. " "Use 'local' or 's3' backend for now."
+            "GCS backend not yet implemented. Use 'local' or 's3' backend for now."
         )
 
     elif backend_type == "cloudinary":
         # Cloudinary backend
         raise NotImplementedError(
-            "Cloudinary backend not yet implemented. "
-            "Use 'local' or 's3' backend for now."
+            "Cloudinary backend not yet implemented. Use 'local' or 's3' backend for now."
         )
 
     else:

svc_infra/storage/settings.py

@@ -5,7 +5,7 @@ Handles environment-based configuration and auto-detection of storage backends.
 """
 
 import os
-from typing import Literal, Optional
+from typing import Literal
 
 from pydantic import Field
 from pydantic_settings import BaseSettings
@@ -52,11 +52,9 @@ class StorageSettings(BaseSettings):
     """
 
     # Backend selection
-    storage_backend: Optional[Literal["local", "s3", "gcs", "cloudinary", "memory"]] = (
-        Field(
-            default=None,
-            description="Storage backend type (auto-detected if not set)",
-        )
+    storage_backend: Literal["local", "s3", "gcs", "cloudinary", "memory"] | None = Field(
+        default=None,
+        description="Storage backend type (auto-detected if not set)",
     )
 
     # Local backend settings
@@ -68,13 +66,13 @@ class StorageSettings(BaseSettings):
         default="http://localhost:8000/files",
         description="Base URL for serving files",
     )
-    storage_signing_secret: Optional[str] = Field(
+    storage_signing_secret: str | None = Field(
         default=None,
         description="Secret key for URL signing (auto-generated if not set)",
     )
 
     # S3 backend settings
-    storage_s3_bucket: Optional[str] = Field(
+    storage_s3_bucket: str | None = Field(
         default=None,
         description="S3 bucket name",
     )
@@ -82,43 +80,43 @@ class StorageSettings(BaseSettings):
         default="us-east-1",
         description="AWS region",
     )
-    storage_s3_endpoint: Optional[str] = Field(
+    storage_s3_endpoint: str | None = Field(
         default=None,
         description="Custom S3 endpoint (for DigitalOcean Spaces, Wasabi, etc.)",
     )
-    storage_s3_access_key: Optional[str] = Field(
+    storage_s3_access_key: str | None = Field(
         default=None,
         description="S3 access key (falls back to AWS_ACCESS_KEY_ID)",
     )
-    storage_s3_secret_key: Optional[str] = Field(
+    storage_s3_secret_key: str | None = Field(
         default=None,
         description="S3 secret key (falls back to AWS_SECRET_ACCESS_KEY)",
     )
 
     # GCS backend settings
-    storage_gcs_bucket: Optional[str] = Field(
+    storage_gcs_bucket: str | None = Field(
         default=None,
         description="Google Cloud Storage bucket name",
     )
-    storage_gcs_project: Optional[str] = Field(
+    storage_gcs_project: str | None = Field(
         default=None,
         description="GCP project ID",
     )
-    storage_gcs_credentials_path: Optional[str] = Field(
+    storage_gcs_credentials_path: str | None = Field(
         default=None,
         description="Path to GCP service account JSON",
     )
 
     # Cloudinary backend settings
-    storage_cloudinary_cloud_name: Optional[str] = Field(
+    storage_cloudinary_cloud_name: str | None = Field(
         default=None,
         description="Cloudinary cloud name",
     )
-    storage_cloudinary_api_key: Optional[str] = Field(
+    storage_cloudinary_api_key: str | None = Field(
         default=None,
         description="Cloudinary API key",
     )
-    storage_cloudinary_api_secret: Optional[str] = Field(
+    storage_cloudinary_api_secret: str | None = Field(
         default=None,
         description="Cloudinary API secret",
     )
@@ -176,7 +174,7 @@ class StorageSettings(BaseSettings):
         # Default to memory (for development/testing)
         return "memory"
 
-    def get_s3_credentials(self) -> tuple[Optional[str], Optional[str]]:
+    def get_s3_credentials(self) -> tuple[str | None, str | None]:
         """
         Get S3 credentials with fallback to AWS environment variables.
 

svc_infra/testing/__init__.py

@@ -28,9 +28,10 @@ from __future__ import annotations
 
 import time
 import uuid
+from collections.abc import Callable
 from dataclasses import dataclass, field
-from datetime import datetime, timedelta, timezone
-from typing import Any, Callable, Dict, List, Optional, TypeVar
+from datetime import UTC, datetime, timedelta
+from typing import Any, TypeVar
 
 # Type variable for generic model creation
 T = TypeVar("T")
@@ -46,7 +47,7 @@ class CacheEntry:
     """Internal representation of a cached value."""
 
     value: Any
-    expires_at: Optional[float] = None  # Unix timestamp
+    expires_at: float | None = None  # Unix timestamp
 
     def is_expired(self) -> bool:
         """Check if this entry has expired."""
@@ -86,14 +87,14 @@ class MockCache:
             prefix: Key prefix for namespacing (default: "test")
         """
         self.prefix = prefix
-        self._store: Dict[str, CacheEntry] = {}
-        self._tags: Dict[str, set[str]] = {}  # tag -> set of keys
+        self._store: dict[str, CacheEntry] = {}
+        self._tags: dict[str, set[str]] = {}  # tag -> set of keys
 
     def _prefixed_key(self, key: str) -> str:
         """Get the full key with prefix."""
         return f"{self.prefix}:{key}"
 
-    def get(self, key: str) -> Optional[Any]:
+    def get(self, key: str) -> Any | None:
         """
         Get a value from the cache.
 
@@ -116,8 +117,8 @@ class MockCache:
         self,
         key: str,
         value: Any,
-        ttl: Optional[int] = None,
-        tags: Optional[List[str]] = None,
+        ttl: int | None = None,
+        tags: list[str] | None = None,
     ) -> None:
         """
         Set a value in the cache.
@@ -208,7 +209,7 @@ class MockCache:
         self._store.clear()
         self._tags.clear()
 
-    def keys(self, pattern: str = "*") -> List[str]:
+    def keys(self, pattern: str = "*") -> list[str]:
         """
         Get all keys matching a pattern.
 
@@ -233,9 +234,7 @@ class MockCache:
         # Clean up expired entries
         now = time.time()
         self._store = {
-            k: v
-            for k, v in self._store.items()
-            if v.expires_at is None or v.expires_at > now
+            k: v for k, v in self._store.items() if v.expires_at is None or v.expires_at > now
         }
         return len(self._store)
 
@@ -251,14 +250,14 @@ class MockJob:
 
     id: str
     name: str
-    payload: Dict[str, Any]
-    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
-    available_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    payload: dict[str, Any]
+    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    available_at: datetime = field(default_factory=lambda: datetime.now(UTC))
     attempts: int = 0
     max_attempts: int = 5
     status: str = "pending"  # pending, processing, completed, failed
-    result: Optional[Any] = None
-    error: Optional[str] = None
+    result: Any | None = None
+    error: str | None = None
 
 
 class MockJobQueue:
@@ -294,10 +293,10 @@ class MockJobQueue:
         """
         self.sync_mode = sync_mode
         self._seq = 0
-        self._jobs: List[MockJob] = []
-        self._handlers: Dict[str, Callable[[Dict[str, Any]], Any]] = {}
-        self._completed: List[MockJob] = []
-        self._failed: List[MockJob] = []
+        self._jobs: list[MockJob] = []
+        self._handlers: dict[str, Callable[[dict[str, Any]], Any]] = {}
+        self._completed: list[MockJob] = []
+        self._failed: list[MockJob] = []
 
     def _next_id(self) -> str:
         """Generate next job ID."""
@@ -315,15 +314,13 @@ class MockJobQueue:
             Decorator function
         """
 
-        def decorator(func: Callable[[Dict[str, Any]], Any]) -> Callable:
+        def decorator(func: Callable[[dict[str, Any]], Any]) -> Callable:
             self._handlers[name] = func
             return func
 
         return decorator
 
-    def register_handler(
-        self, name: str, handler: Callable[[Dict[str, Any]], Any]
-    ) -> None:
+    def register_handler(self, name: str, handler: Callable[[dict[str, Any]], Any]) -> None:
         """
         Register a job handler function.
 
@@ -336,7 +333,7 @@ class MockJobQueue:
     def enqueue(
         self,
         name: str,
-        payload: Dict[str, Any],
+        payload: dict[str, Any],
         *,
         delay_seconds: int = 0,
         max_attempts: int = 5,
@@ -353,7 +350,7 @@ class MockJobQueue:
         Returns:
             The created MockJob
         """
-        available_at = datetime.now(timezone.utc) + timedelta(seconds=delay_seconds)
+        available_at = datetime.now(UTC) + timedelta(seconds=delay_seconds)
         job = MockJob(
             id=self._next_id(),
             name=name,
@@ -400,17 +397,17 @@ class MockJobQueue:
                 job.status = "pending"
                 # Exponential backoff
                 delay = 60 * job.attempts
-                job.available_at = datetime.now(timezone.utc) + timedelta(seconds=delay)
+                job.available_at = datetime.now(UTC) + timedelta(seconds=delay)
             return False
 
-    def process_next(self) -> Optional[MockJob]:
+    def process_next(self) -> MockJob | None:
         """
         Process the next available job.
 
         Returns:
             The processed job, or None if no jobs available
         """
-        now = datetime.now(timezone.utc)
+        now = datetime.now(UTC)
         for job in self._jobs:
             if job.status == "pending" and job.available_at <= now:
                 self._process_job(job)
@@ -432,17 +429,17 @@ class MockJobQueue:
         return count
 
     @property
-    def jobs(self) -> List[MockJob]:
+    def jobs(self) -> list[MockJob]:
         """Get all pending jobs."""
         return [j for j in self._jobs if j.status == "pending"]
 
     @property
-    def completed_jobs(self) -> List[MockJob]:
+    def completed_jobs(self) -> list[MockJob]:
         """Get all completed jobs."""
         return self._completed.copy()
 
     @property
-    def failed_jobs(self) -> List[MockJob]:
+    def failed_jobs(self) -> list[MockJob]:
         """Get all failed jobs."""
         return self._failed.copy()
 
@@ -452,7 +449,7 @@ class MockJobQueue:
         self._completed.clear()
         self._failed.clear()
 
-    def get_job(self, job_id: str) -> Optional[MockJob]:
+    def get_job(self, job_id: str) -> MockJob | None:
         """
         Get a job by ID.
 
@@ -493,8 +490,8 @@ class UserFixtureData:
     is_active: bool = True
     is_verified: bool = True
     is_superuser: bool = False
-    full_name: Optional[str] = None
-    extra: Dict[str, Any] = field(default_factory=dict)
+    full_name: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
 
 
 @dataclass
@@ -503,9 +500,9 @@ class TenantFixtureData:
 
     id: str = field(default_factory=generate_uuid)
     name: str = field(default_factory=lambda: f"Test Tenant {uuid.uuid4().hex[:6]}")
-    slug: Optional[str] = None
+    slug: str | None = None
     is_active: bool = True
-    extra: Dict[str, Any] = field(default_factory=dict)
+    extra: dict[str, Any] = field(default_factory=dict)
 
     def __post_init__(self):
         if self.slug is None:
@@ -629,7 +626,7 @@ async def create_test_tenant(
 # =============================================================================
 
 
-def pytest_fixtures() -> Dict[str, Callable]:
+def pytest_fixtures() -> dict[str, Callable]:
     """
     Get pytest fixture functions for use in conftest.py.
 

svc_infra/utils.py

@@ -1,17 +1,43 @@
+"""svc-infra utilities module.
+
+This module provides utility functions and helpers for svc-infra, including:
+- Template rendering and file writing utilities
+- Deprecation decorators and warnings
+"""
+
+from __future__ import annotations
+
+import functools
 import importlib.resources as pkg
+import warnings
+from collections.abc import Callable
 from pathlib import Path
 from string import Template as _T
-from typing import Any, Dict
+from typing import Any, TypeVar
+
+__all__ = [
+    # Template utilities
+    "render_template",
+    "write",
+    "ensure_init_py",
+    # Deprecation utilities
+    "deprecated",
+    "deprecated_parameter",
+    "DeprecatedWarning",
+]
+
 
+# =============================================================================
+# Template Utilities
+# =============================================================================
 
-def render_template(
-    tmpl_dir: str, name: str, subs: dict[str, Any] | None = None
-) -> str:
+
+def render_template(tmpl_dir: str, name: str, subs: dict[str, Any] | None = None) -> str:
     txt = pkg.files(tmpl_dir).joinpath(name).read_text(encoding="utf-8")
     return _T(txt).safe_substitute(subs or {})
 
 
-def write(dest: Path, content: str, overwrite: bool = False) -> Dict[str, Any]:
+def write(dest: Path, content: str, overwrite: bool = False) -> dict[str, Any]:
     dest = dest.resolve()
     dest.parent.mkdir(parents=True, exist_ok=True)
     if dest.exists() and not overwrite:
@@ -20,8 +46,143 @@ def write(dest: Path, content: str, overwrite: bool = False) -> Dict[str, Any]:
     return {"path": str(dest), "action": "wrote"}
 
 
-def ensure_init_py(
-    dir_path: Path, overwrite: bool, paired: bool, content: str
-) -> Dict[str, Any]:
+def ensure_init_py(dir_path: Path, overwrite: bool, paired: bool, content: str) -> dict[str, Any]:
     """Create __init__.py; paired=True writes models/schemas re-exports, otherwise minimal."""
     return write(dir_path / "__init__.py", content, overwrite)
+
+
+# =============================================================================
+# Deprecation Utilities
+# =============================================================================
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class DeprecatedWarning(DeprecationWarning):
+    """Custom deprecation warning for svc-infra.
+
+    This warning is used to distinguish svc-infra deprecations from
+    Python's built-in DeprecationWarning.
+    """
+
+    pass
+
+
+def deprecated(
+    version: str,
+    reason: str,
+    removal_version: str | None = None,
+    *,
+    stacklevel: int = 2,
+) -> Callable[[F], F]:
+    """Decorator to mark a function or class as deprecated.
+
+    The decorated function/class will emit a DeprecationWarning when called/instantiated.
+
+    Args:
+        version: The version in which the feature was deprecated (e.g., "1.2.0").
+        reason: The reason for deprecation and recommended alternative.
+        removal_version: The version in which the feature will be removed (e.g., "1.4.0").
+        stacklevel: Stack level for the warning (default 2 for immediate caller).
+
+    Returns:
+        A decorator that wraps the function/class with deprecation warning.
+
+    Example:
+        >>> @deprecated(
+        ...     version="1.2.0",
+        ...     reason="Use new_function() instead",
+        ...     removal_version="1.4.0"
+        ... )
+        ... def old_function():
+        ...     return "result"
+        >>>
+        >>> old_function()  # Emits DeprecationWarning
+        'result'
+    """
+
+    def decorator(func: F) -> F:
+        # Build the warning message
+        name = getattr(func, "__qualname__", getattr(func, "__name__", str(func)))
+        message = f"{name} is deprecated since version {version}."
+
+        if removal_version:
+            message += f" It will be removed in version {removal_version}."
+
+        message += f" {reason}"
+
+        if isinstance(func, type):
+            # Handle class deprecation
+            original_init = func.__init__  # type: ignore[misc]
+
+            @functools.wraps(original_init)
+            def new_init(self: Any, *args: Any, **kwargs: Any) -> None:
+                warnings.warn(message, DeprecatedWarning, stacklevel=stacklevel)
+                original_init(self, *args, **kwargs)
+
+            func.__init__ = new_init  # type: ignore[misc]
+
+            # Add deprecation info to docstring
+            if func.__doc__:
+                func.__doc__ = f".. deprecated:: {version}\n   {reason}\n\n{func.__doc__}"
+            else:
+                func.__doc__ = f".. deprecated:: {version}\n   {reason}"
+
+            return func  # type: ignore[return-value]
+        else:
+            # Handle function deprecation
+            @functools.wraps(func)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                warnings.warn(message, DeprecatedWarning, stacklevel=stacklevel)
+                return func(*args, **kwargs)
+
+            # Add deprecation info to docstring
+            if wrapper.__doc__:
+                wrapper.__doc__ = f".. deprecated:: {version}\n   {reason}\n\n{wrapper.__doc__}"
+            else:
+                wrapper.__doc__ = f".. deprecated:: {version}\n   {reason}"
+
+            return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def deprecated_parameter(
+    name: str,
+    version: str,
+    reason: str,
+    removal_version: str | None = None,
+    *,
+    stacklevel: int = 2,
+) -> None:
+    """Emit a deprecation warning for a deprecated parameter.
+
+    Call this function when a deprecated parameter is used. This should be
+    called at the beginning of a function that has deprecated parameters.
+
+    Args:
+        name: The name of the deprecated parameter.
+        version: The version in which the parameter was deprecated.
+        reason: The reason for deprecation and recommended alternative.
+        removal_version: The version in which the parameter will be removed.
+        stacklevel: Stack level for the warning (default 2 for immediate caller).
+
+    Example:
+        >>> def my_function(new_param: str, old_param: str | None = None):
+        ...     if old_param is not None:
+        ...         deprecated_parameter(
+        ...             name="old_param",
+        ...             version="1.2.0",
+        ...             reason="Use new_param instead"
+        ...         )
+        ...         new_param = old_param
+        ...     return new_param
+    """
+    message = f"Parameter '{name}' is deprecated since version {version}."
+
+    if removal_version:
+        message += f" It will be removed in version {removal_version}."
+
+    message += f" {reason}"
+
+    warnings.warn(message, DeprecatedWarning, stacklevel=stacklevel + 1)

svc_infra/webhooks/__init__.py

@@ -61,7 +61,7 @@ async def trigger_webhook(
         return None
 
     try:
-        msg_id = cast(int, webhook_service.publish(event, data))
+        msg_id = cast("int", webhook_service.publish(event, data))
         _logger.info(f"Triggered webhook event '{event}' with message ID {msg_id}")
         return msg_id
     except Exception as e: