persistence-kit 3.2.0__tar.gz → 3.3.0__tar.gz

{persistence_kit-3.2.0 → persistence_kit-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: persistence-kit
-Version: 3.2.0
+Version: 3.3.0
 Summary: Reusable persistence and repository toolkit
 License: MIT
 License-File: LICENSE
@@ -32,6 +32,7 @@ Requires-Dist: fastapi (>=0.115.0,<0.116.0) ; extra == "api" or extra == "storag
 Requires-Dist: motor (>=3.7.1,<4.0.0)
 Requires-Dist: pydantic-settings (>=2.3.0,<3.0.0)
 Requires-Dist: pyjwt[crypto] (>=2.10.1,<3.0.0) ; extra == "security" or extra == "security-cognito" or extra == "testing" or extra == "all"
+Requires-Dist: python-multipart (>=0.0.20,<0.0.21) ; extra == "api" or extra == "storage-routes" or extra == "security" or extra == "security-cognito" or extra == "testing" or extra == "all"
 Requires-Dist: sqlalchemy[asyncio] (>=2.0.43,<3.0.0)
 Requires-Dist: typing-extensions (>=4.12.0,<5.0.0)
 Project-URL: Documentation, https://github.com/andresfserrano/persistence-kit#readme

{persistence_kit-3.2.0 → persistence_kit-3.3.0}/persistence_kit/__init__.py

@@ -13,6 +13,7 @@ from .settings import (
     AuthProvider,
     DeploymentStage,
     ExportStorageProvider,
+    MediaStorageProvider,
     PersistenceKitSettings,
 )
 from .settings.constants import Database
@@ -186,6 +187,7 @@ __all__ = [
     "RepoSettings",
     "AuthProvider",
     "ExportStorageProvider",
+    "MediaStorageProvider",
     "DeploymentStage",
     "LOCAL_DEFAULT_JOB_SERVICE_API_KEY",
     "DEFAULT_MEMORY_JWT_SECRET",

{persistence_kit-3.2.0 → persistence_kit-3.3.0}/persistence_kit/settings/__init__.py

@@ -6,6 +6,7 @@ from .app_settings import (
     AuthProvider,
     DeploymentStage,
     ExportStorageProvider,
+    MediaStorageProvider,
     PersistenceKitSettings,
 )
 from .constants import Database
@@ -18,6 +19,7 @@ __all__ = [
     "RepoSettings",
     "AuthProvider",
     "ExportStorageProvider",
+    "MediaStorageProvider",
     "DeploymentStage",
     "LOCAL_DEFAULT_JOB_SERVICE_API_KEY",
     "DEFAULT_MEMORY_JWT_SECRET",

{persistence_kit-3.2.0 → persistence_kit-3.3.0}/persistence_kit/settings/app_settings.py

@@ -17,6 +17,11 @@ class ExportStorageProvider(str, Enum):
     S3 = "s3"
 
 
+class MediaStorageProvider(str, Enum):
+    LOCAL = "local"
+    S3 = "s3"
+
+
 class DeploymentStage(str, Enum):
     LOCAL = "local"
     DEV = "dev"
@@ -53,6 +58,11 @@ class PersistenceKitSettings(RepoSettings):
     local_export_storage_dir: str = ".local"
     local_export_url_secret: str = "local-export-dev-secret-key-32-bytes"
 
+    # Media Storage (user-uploaded assets like product images, avatars, etc.)
+    media_storage_provider: MediaStorageProvider = MediaStorageProvider.LOCAL
+    local_media_storage_dir: str = ".local/media"
+    aws_s3_media_bucket: str | None = None
+
     # Cognito
     cognito_user_pool_id: str | None = None
     cognito_app_client_id: str | None = None

{persistence_kit-3.2.0 → persistence_kit-3.3.0}/persistence_kit/storage/__init__.py

@@ -10,6 +10,7 @@ from persistence_kit.storage.factory import (
     EXPORT_STORAGE_BUILDERS,
     ExportStorage,
     ExportStorageBuilder,
+    build_media_storage,
     get_export_storage,
 )
 
@@ -23,6 +24,7 @@ _ROUTE_EXPORTS = {
     "guess_export_media_type",
 }
 _S3_EXPORTS = {"S3ObjectStorage", "S3ExportStorageProvider"}
+_MEDIA_EXPORTS = {"MediaStorage"}
 
 __all__ = [
     "ObjectStorage",
@@ -39,6 +41,8 @@ __all__ = [
     "ExportStorageBuilder",
     "EXPORT_STORAGE_BUILDERS",
     "get_export_storage",
+    "MediaStorage",
+    "build_media_storage",
     "SettingsProvider",
     "CurrentUserDependency",
     "ExportDownloadAuthorizer",
@@ -67,4 +71,10 @@ def __getattr__(name: str):
         value = getattr(s3, name)
         globals()[name] = value
         return value
+    if name in _MEDIA_EXPORTS:
+        from persistence_kit.storage import media
+
+        value = getattr(media, name)
+        globals()[name] = value
+        return value
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{persistence_kit-3.2.0 → persistence_kit-3.3.0}/persistence_kit/storage/contracts.py

@@ -24,3 +24,7 @@ class ObjectStorage(Protocol):
         key: str,
         expires_in: int = 3600,
     ) -> str: ...
+
+    async def delete(self, key: str) -> None: ...
+
+    async def list_keys(self, prefix: str = "") -> list[str]: ...

{persistence_kit-3.2.0 → persistence_kit-3.3.0}/persistence_kit/storage/factory.py

@@ -1,7 +1,11 @@
 from functools import lru_cache
 from typing import Callable
 
-from persistence_kit.settings import ExportStorageProvider, PersistenceKitSettings
+from persistence_kit.settings import (
+    ExportStorageProvider,
+    MediaStorageProvider,
+    PersistenceKitSettings,
+)
 from persistence_kit.storage.contracts import ObjectStorage
 from persistence_kit.storage.errors import StorageConfigError
 
@@ -69,3 +73,68 @@ def get_export_storage(settings: PersistenceKitSettings) -> ExportStorage:
             f"Proveedor de storage de exportaciones no soportado: '{provider}'."
         )
     return builder(settings)
+
+
+@lru_cache
+def _local_media_object_storage_cached(base_dir: str) -> ObjectStorage:
+    from persistence_kit.storage.local import LocalObjectStorage
+
+    return LocalObjectStorage(
+        base_dir=base_dir,
+        public_base_url="",
+        signing_secret="not-used-for-public-media",
+    )
+
+
+@lru_cache
+def _s3_media_object_storage_cached(bucket: str, region: str) -> ObjectStorage:
+    from persistence_kit.storage.s3 import S3ObjectStorage
+
+    return S3ObjectStorage(bucket=bucket, region=region)
+
+
+def _build_media_object_storage(
+    settings: PersistenceKitSettings,
+    namespace: str,
+) -> ObjectStorage:
+    namespace = namespace.strip().strip("/").strip()
+    if not namespace:
+        raise StorageConfigError("El namespace de MediaStorage no puede estar vacío.")
+    if settings.media_storage_provider == MediaStorageProvider.LOCAL:
+        return _local_media_object_storage_cached(
+            f"{settings.local_media_storage_dir.rstrip('/')}/{namespace}"
+        )
+    if settings.media_storage_provider == MediaStorageProvider.S3:
+        if not settings.aws_s3_media_bucket:
+            raise StorageConfigError(
+                "Falta configuracion AWS_S3_MEDIA_BUCKET para el storage de media."
+            )
+        return _s3_media_object_storage_cached(
+            settings.aws_s3_media_bucket, settings.aws_region
+        )
+    provider = getattr(
+        settings.media_storage_provider, "value", settings.media_storage_provider
+    )
+    raise StorageConfigError(
+        f"Proveedor de storage de media no soportado: '{provider}'."
+    )
+
+
+def build_media_storage(
+    settings: PersistenceKitSettings,
+    *,
+    namespace: str,
+    url_prefix: str,
+    allowed_content_types=None,
+    max_bytes: int | None = None,
+):
+    from persistence_kit.storage.media import MediaStorage
+
+    storage = _build_media_object_storage(settings, namespace)
+    return MediaStorage(
+        storage=storage,
+        public_base_url=settings.public_base_url,
+        url_prefix=url_prefix,
+        allowed_content_types=allowed_content_types,
+        max_bytes=max_bytes,
+    )

{persistence_kit-3.2.0 → persistence_kit-3.3.0}/persistence_kit/storage/local.py

@@ -91,6 +91,40 @@ class LocalObjectStorage:
         ).digest()
         return f"{payload_token}.{_b64encode(signature)}"
 
+    async def delete(self, key: str) -> None:
+        destination = self.get_file_path(key)
+
+        def _delete() -> None:
+            if destination.is_file():
+                destination.unlink()
+            current = destination.parent
+            while current != self._base_dir and current.is_relative_to(self._base_dir):
+                try:
+                    if not current.is_dir() or any(current.iterdir()):
+                        break
+                    current.rmdir()
+                except OSError:
+                    break
+                current = current.parent
+
+        await asyncio.to_thread(_delete)
+
+    async def list_keys(self, prefix: str = "") -> list[str]:
+        normalized_prefix = prefix.strip("/").rstrip("/")
+        root = self._base_dir / normalized_prefix if normalized_prefix else self._base_dir
+
+        def _list() -> list[str]:
+            if not root.is_dir():
+                return []
+            collected: list[str] = []
+            for path in root.rglob("*"):
+                if path.is_file():
+                    rel = path.relative_to(self._base_dir).as_posix()
+                    collected.append(rel)
+            return collected
+
+        return await asyncio.to_thread(_list)
+
     def validate_download_token(self, key: str, token: str) -> bool:
         try:
             payload_token, signature_token = token.split(".", maxsplit=1)

persistence_kit-3.3.0/persistence_kit/storage/media.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+from persistence_kit.storage.contracts import ObjectStorage
+
+
+class MediaStorage:
+    CONTENT_TYPE_TO_EXTENSION: dict[str, str] = {
+        "image/jpeg": "jpg",
+        "image/png": "png",
+        "image/webp": "webp",
+        "image/gif": "gif",
+        "application/pdf": "pdf",
+    }
+    DEFAULT_ALLOWED_CONTENT_TYPES: tuple[str, ...] = (
+        "image/jpeg",
+        "image/png",
+        "image/webp",
+    )
+    DEFAULT_MAX_BYTES: int = 5 * 1024 * 1024
+
+    def __init__(
+        self,
+        *,
+        storage: ObjectStorage,
+        public_base_url: str | None,
+        url_prefix: str,
+        allowed_content_types: Iterable[str] | None = None,
+        max_bytes: int | None = None,
+    ) -> None:
+        self._storage = storage
+        self._public_base_url = (public_base_url or "").rstrip("/")
+        self._url_prefix = "/" + url_prefix.strip("/")
+        self._allowed_content_types = tuple(
+            allowed_content_types
+            if allowed_content_types is not None
+            else self.DEFAULT_ALLOWED_CONTENT_TYPES
+        )
+        self._max_bytes = max_bytes if max_bytes is not None else self.DEFAULT_MAX_BYTES
+
+    @property
+    def url_prefix(self) -> str:
+        return self._url_prefix
+
+    @property
+    def allowed_content_types(self) -> tuple[str, ...]:
+        return self._allowed_content_types
+
+    @property
+    def max_bytes(self) -> int:
+        return self._max_bytes
+
+    def validate_upload(self, data: bytes, content_type: str) -> None:
+        from persistence_kit.api.exceptions import ValidationException
+
+        if not data:
+            raise ValidationException("El archivo está vacío.")
+        if content_type not in self._allowed_content_types:
+            allowed = ", ".join(self._allowed_content_types)
+            raise ValidationException(
+                f"Tipo de archivo no permitido. Permitidos: {allowed}."
+            )
+        if len(data) > self._max_bytes:
+            max_mb = self._max_bytes // (1024 * 1024)
+            raise ValidationException(
+                f"El archivo excede el tamaño máximo permitido de {max_mb}MB."
+            )
+
+    async def upload(
+        self,
+        key: str,
+        data: bytes,
+        content_type: str = "application/octet-stream",
+    ) -> str:
+        return await self._storage.upload(key, data, content_type=content_type)
+
+    async def upload_file(
+        self,
+        key: str,
+        file_path: Path,
+        content_type: str = "application/octet-stream",
+    ) -> str:
+        return await self._storage.upload_file(key, file_path, content_type=content_type)
+
+    async def delete(self, key: str) -> None:
+        await self._storage.delete(key)
+
+    async def generate_presigned_url(self, key: str, expires_in: int = 3600) -> str:
+        return await self._storage.generate_presigned_url(key, expires_in=expires_in)
+
+    def build_url(self, key: str | None) -> str | None:
+        if not key:
+            return None
+        return f"{self._public_base_url}{self._url_prefix}/{key}"
+
+    async def remove_other_files_in_scope(self, scope: str, keep_key: str) -> None:
+        existing_keys = await self._storage.list_keys(prefix=scope)
+        for existing in existing_keys:
+            if existing != keep_key:
+                await self._storage.delete(existing)
+
+    async def remove_scope_dir(self, scope: str) -> None:
+        existing_keys = await self._storage.list_keys(prefix=scope)
+        for existing in existing_keys:
+            await self._storage.delete(existing)

{persistence_kit-3.2.0 → persistence_kit-3.3.0}/persistence_kit/storage/s3.py

@@ -6,6 +6,7 @@ from pathlib import Path
 
 from persistence_kit.storage.errors import (
     StorageConfigError,
+    StorageError,
     StoragePresignError,
     StorageUploadError,
 )
@@ -91,5 +92,34 @@ class S3ObjectStorage:
             logger.exception("S3 presign fallido bucket=%s key=%s", self._bucket, key)
             raise StoragePresignError(f"No fue posible generar la URL prefirmada: {exc}") from exc
 
+    async def delete(self, key: str) -> None:
+        def _delete() -> None:
+            self._client.delete_object(Bucket=self._bucket, Key=key)
+
+        try:
+            await asyncio.to_thread(_delete)
+        except ClientError as exc:
+            logger.exception("S3 delete fallido bucket=%s key=%s", self._bucket, key)
+            raise StorageError(f"No fue posible borrar el objeto en S3: {exc}") from exc
+
+    async def list_keys(self, prefix: str = "") -> list[str]:
+        normalized_prefix = prefix.lstrip("/")
+        if normalized_prefix and not normalized_prefix.endswith("/"):
+            normalized_prefix = normalized_prefix + "/"
+
+        def _list() -> list[str]:
+            keys: list[str] = []
+            paginator = self._client.get_paginator("list_objects_v2")
+            for page in paginator.paginate(Bucket=self._bucket, Prefix=normalized_prefix):
+                for obj in page.get("Contents", []) or []:
+                    keys.append(obj["Key"])
+            return keys
+
+        try:
+            return await asyncio.to_thread(_list)
+        except ClientError as exc:
+            logger.exception("S3 list fallido bucket=%s prefix=%s", self._bucket, normalized_prefix)
+            raise StorageError(f"No fue posible listar objetos en S3: {exc}") from exc
+
 
 S3ExportStorageProvider = S3ObjectStorage

{persistence_kit-3.2.0 → persistence_kit-3.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "persistence-kit"
-version = "3.2.0"
+version = "3.3.0"
 description = "Reusable persistence and repository toolkit"
 authors = ["Andres Felipe Serrano Barrios <andresfserrano1@gmail.com>"]
 readme = "README.md"
@@ -33,16 +33,17 @@ pydantic-settings = "^2.3.0"
 fastapi = {version = "^0.115.0", optional = true}
 boto3 = {version = "^1.35.0", optional = true}
 pyjwt = {version = "^2.10.1", extras = ["crypto"], optional = true}
+python-multipart = {version = "^0.0.20", optional = true}
 
 [tool.poetry.extras]
-api = ["fastapi"]
+api = ["fastapi", "python-multipart"]
 storage-s3 = ["boto3"]
-storage-routes = ["fastapi"]
-security = ["fastapi", "pyjwt"]
-security-cognito = ["fastapi", "pyjwt", "boto3"]
+storage-routes = ["fastapi", "python-multipart"]
+security = ["fastapi", "pyjwt", "python-multipart"]
+security-cognito = ["fastapi", "pyjwt", "boto3", "python-multipart"]
 dynamodb = ["boto3"]
-testing = ["fastapi", "pyjwt"]
-all = ["fastapi", "boto3", "pyjwt"]
+testing = ["fastapi", "pyjwt", "python-multipart"]
+all = ["fastapi", "boto3", "pyjwt", "python-multipart"]
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.3.0"