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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: persistence-kit
-Version: 3.0.2
+Version: 3.2.0
 Summary: Reusable persistence and repository toolkit
 License: MIT
 License-File: LICENSE
@@ -18,11 +18,20 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Database
 Classifier: Typing :: Typed
+Provides-Extra: all
+Provides-Extra: api
+Provides-Extra: dynamodb
+Provides-Extra: security
+Provides-Extra: security-cognito
+Provides-Extra: storage-routes
+Provides-Extra: storage-s3
+Provides-Extra: testing
 Requires-Dist: asyncpg (>=0.30.0,<0.31.0)
-Requires-Dist: boto3 (>=1.35.0,<2.0.0)
-Requires-Dist: fastapi (>=0.115.0,<0.116.0)
+Requires-Dist: boto3 (>=1.35.0,<2.0.0) ; extra == "storage-s3" or extra == "security-cognito" or extra == "dynamodb" or extra == "all"
+Requires-Dist: fastapi (>=0.115.0,<0.116.0) ; extra == "api" or extra == "storage-routes" or extra == "security" or extra == "security-cognito" or extra == "testing" or extra == "all"
 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: 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
@@ -53,6 +62,8 @@ Author: Andres Felipe Serrano Barrios
 - `api/`: reusable API exceptions, handlers, and route loading helpers
 - `bootstrap/`: startup helpers, configuration registry, and seed orchestration
 - `utils/`: transversal helpers such as upsert utilities
+- `storage/`: reusable object storage contracts and local/S3 adapters
+- `security/`: reusable identity provider contracts, Cognito/memory adapters, and JWT verifiers
 - `repository/`: concrete repository implementations by backend
 - `repository_factory/`: entity registry, repository creation, and populated view repository
 
@@ -67,6 +78,28 @@ Recommended rule:
 pip install persistence-kit
 ```
 
+The base install keeps optional capabilities out of the dependency graph. Enable
+only what the host project uses:
+
+```bash
+pip install "persistence-kit[api]"
+pip install "persistence-kit[security]"
+pip install "persistence-kit[security-cognito]"
+pip install "persistence-kit[storage-s3]"
+pip install "persistence-kit[storage-routes]"
+pip install "persistence-kit[dynamodb]"
+```
+
+Available capabilities:
+
+- `api`: FastAPI exceptions, pagination helpers, route loading, and error handlers.
+- `security`: memory identity provider and JWT verifier.
+- `security-cognito`: security plus Cognito and AWS/JWKS dependencies.
+- `storage-s3`: S3 object storage adapter.
+- `storage-routes`: FastAPI local export download router.
+- `dynamodb`: DynamoDB repository backend.
+- `all`: every optional capability.
+
 ## Quick Start
 
 ```python
@@ -96,10 +129,25 @@ from persistence_kit import (
     Repository,
     ViewRepository,
     RepoSettings,
+    PersistenceKitSettings,
+    AuthProvider,
+    ExportStorageProvider,
     Database,
     ConfigRegistry,
     configuration,
     SeederProvider,
+    ObjectStorage,
+    LocalObjectStorage,
+    S3ObjectStorage,
+    get_export_storage,
+    build_local_export_storage_router,
+    IdentityProvider,
+    MemorySecurityProvider,
+    CognitoIdentityProvider,
+    MemoryJwtVerifier,
+    CognitoJwtVerifier,
+    get_identity_provider,
+    get_token_verifier,
     build_api_router,
     handle_service_errors,
     handle_repository_errors,
@@ -125,6 +173,93 @@ Use internal paths only for implementation details, for example:
 - `persistence_kit.repository_factory.registry.entity_registry`
 - `persistence_kit.repository_factory.view.populating_repository`
 
+## Object Storage
+
+`persistence_kit.storage` provides driven adapters for storing generated files or
+binary objects outside the domain layer:
+
+```python
+from persistence_kit.storage import LocalObjectStorage
+
+storage = LocalObjectStorage(
+    base_dir=".local",
+    public_base_url="http://localhost:8000",
+    signing_secret="dev-secret",
+)
+
+key = await storage.upload("exports/report.csv", b"id,name\n1,Ada\n", "text/csv")
+url = await storage.generate_presigned_url(key)
+```
+
+Available adapters:
+
+- `LocalObjectStorage`: stores files under a configured local directory and signs download URLs.
+- `S3ObjectStorage`: uploads objects to S3 and returns AWS presigned URLs.
+
+Backward-compatible aliases are exported for applications that previously used
+`LocalExportStorageProvider` and `S3ExportStorageProvider`.
+
+`get_export_storage(settings)` builds and caches the configured adapter from a
+`PersistenceKitSettings` instance or a subclass inherited by the host app.
+
+For FastAPI applications, `build_local_export_storage_router(...)` exposes a
+reusable local download route. The host app passes its settings provider,
+optional-current-user dependency, and product authorization callback.
+
+Install `persistence-kit[storage-s3]` before using `S3ObjectStorage` and
+`persistence-kit[storage-routes]` before using the FastAPI export route.
+
+## Security
+
+`persistence_kit.security` provides reusable driven adapters for application
+authentication flows:
+
+```python
+from persistence_kit.security import MemorySecurityProvider, MemoryJwtVerifier
+
+identity = MemorySecurityProvider(
+    jwt_secret="dev-secret-with-enough-length",
+    jwt_issuer="local-sandbox",
+    seed_role_users=True,
+    seed_role_codes=("admin", "operator"),
+    seed_user_domain="example.org",
+)
+verifier = MemoryJwtVerifier(secret="dev-secret-with-enough-length", issuer="local-sandbox")
+```
+
+Available pieces:
+
+- `IdentityProvider` and `TokenVerifier`: application-facing protocols.
+- `MemorySecurityProvider`: local identity provider for tests/sandbox environments.
+- `CognitoIdentityProvider`: AWS Cognito identity provider adapter.
+- `MemoryJwtVerifier` and `CognitoJwtVerifier`: JWT token verifiers.
+- Registration/login/password-reset result dataclasses and helper functions such as `unique_roles`.
+
+Host applications should keep domain-specific roles, authorization policies,
+scope rules, and route permission matrices outside the kit.
+
+Install `persistence-kit[security]` for the memory provider/JWT verifier and
+`persistence-kit[security-cognito]` for Cognito support.
+
+`PersistenceKitSettings` centralizes common auth, storage, observability, AWS,
+and job-service settings. Host applications can inherit from it and override
+only product-specific defaults:
+
+```python
+from persistence_kit import Database, PersistenceKitSettings
+
+
+class Settings(PersistenceKitSettings):
+    service_name: str = "my-api"
+    key_status_history_database: Database = Database.MONGO
+    memory_seed_role_codes: tuple[str, ...] = ("admin", "operator")
+```
+
+`persistence_kit.security.factory` can build the identity provider and token
+verifier from that inherited settings object. `persistence_kit.storage.factory`
+does the same for export storage, and `persistence_kit.storage.routes` exposes
+the reusable FastAPI local export route.
+
 ## Typical Host Application Flow
 
 1. Define your entities as dataclasses.
@@ -150,13 +285,13 @@ Create the local environment and run tests from the library root:
 
 ```bash
 poetry lock
-poetry install --with dev
+poetry install --with dev --all-extras
 poetry run pytest -q
 ```
 
 Current validation baseline:
 
-- `persistence_kit`: `138 passed`
+- `persistence_kit`: `335 passed`
 
 ## Publish to PyPI (Manual)
 

{persistence_kit-3.0.2 → persistence_kit-3.2.0}/README.md

@@ -21,6 +21,8 @@ Author: Andres Felipe Serrano Barrios
 - `api/`: reusable API exceptions, handlers, and route loading helpers
 - `bootstrap/`: startup helpers, configuration registry, and seed orchestration
 - `utils/`: transversal helpers such as upsert utilities
+- `storage/`: reusable object storage contracts and local/S3 adapters
+- `security/`: reusable identity provider contracts, Cognito/memory adapters, and JWT verifiers
 - `repository/`: concrete repository implementations by backend
 - `repository_factory/`: entity registry, repository creation, and populated view repository
 
@@ -35,6 +37,28 @@ Recommended rule:
 pip install persistence-kit
 ```
 
+The base install keeps optional capabilities out of the dependency graph. Enable
+only what the host project uses:
+
+```bash
+pip install "persistence-kit[api]"
+pip install "persistence-kit[security]"
+pip install "persistence-kit[security-cognito]"
+pip install "persistence-kit[storage-s3]"
+pip install "persistence-kit[storage-routes]"
+pip install "persistence-kit[dynamodb]"
+```
+
+Available capabilities:
+
+- `api`: FastAPI exceptions, pagination helpers, route loading, and error handlers.
+- `security`: memory identity provider and JWT verifier.
+- `security-cognito`: security plus Cognito and AWS/JWKS dependencies.
+- `storage-s3`: S3 object storage adapter.
+- `storage-routes`: FastAPI local export download router.
+- `dynamodb`: DynamoDB repository backend.
+- `all`: every optional capability.
+
 ## Quick Start
 
 ```python
@@ -64,10 +88,25 @@ from persistence_kit import (
     Repository,
     ViewRepository,
     RepoSettings,
+    PersistenceKitSettings,
+    AuthProvider,
+    ExportStorageProvider,
     Database,
     ConfigRegistry,
     configuration,
     SeederProvider,
+    ObjectStorage,
+    LocalObjectStorage,
+    S3ObjectStorage,
+    get_export_storage,
+    build_local_export_storage_router,
+    IdentityProvider,
+    MemorySecurityProvider,
+    CognitoIdentityProvider,
+    MemoryJwtVerifier,
+    CognitoJwtVerifier,
+    get_identity_provider,
+    get_token_verifier,
     build_api_router,
     handle_service_errors,
     handle_repository_errors,
@@ -93,6 +132,93 @@ Use internal paths only for implementation details, for example:
 - `persistence_kit.repository_factory.registry.entity_registry`
 - `persistence_kit.repository_factory.view.populating_repository`
 
+## Object Storage
+
+`persistence_kit.storage` provides driven adapters for storing generated files or
+binary objects outside the domain layer:
+
+```python
+from persistence_kit.storage import LocalObjectStorage
+
+storage = LocalObjectStorage(
+    base_dir=".local",
+    public_base_url="http://localhost:8000",
+    signing_secret="dev-secret",
+)
+
+key = await storage.upload("exports/report.csv", b"id,name\n1,Ada\n", "text/csv")
+url = await storage.generate_presigned_url(key)
+```
+
+Available adapters:
+
+- `LocalObjectStorage`: stores files under a configured local directory and signs download URLs.
+- `S3ObjectStorage`: uploads objects to S3 and returns AWS presigned URLs.
+
+Backward-compatible aliases are exported for applications that previously used
+`LocalExportStorageProvider` and `S3ExportStorageProvider`.
+
+`get_export_storage(settings)` builds and caches the configured adapter from a
+`PersistenceKitSettings` instance or a subclass inherited by the host app.
+
+For FastAPI applications, `build_local_export_storage_router(...)` exposes a
+reusable local download route. The host app passes its settings provider,
+optional-current-user dependency, and product authorization callback.
+
+Install `persistence-kit[storage-s3]` before using `S3ObjectStorage` and
+`persistence-kit[storage-routes]` before using the FastAPI export route.
+
+## Security
+
+`persistence_kit.security` provides reusable driven adapters for application
+authentication flows:
+
+```python
+from persistence_kit.security import MemorySecurityProvider, MemoryJwtVerifier
+
+identity = MemorySecurityProvider(
+    jwt_secret="dev-secret-with-enough-length",
+    jwt_issuer="local-sandbox",
+    seed_role_users=True,
+    seed_role_codes=("admin", "operator"),
+    seed_user_domain="example.org",
+)
+verifier = MemoryJwtVerifier(secret="dev-secret-with-enough-length", issuer="local-sandbox")
+```
+
+Available pieces:
+
+- `IdentityProvider` and `TokenVerifier`: application-facing protocols.
+- `MemorySecurityProvider`: local identity provider for tests/sandbox environments.
+- `CognitoIdentityProvider`: AWS Cognito identity provider adapter.
+- `MemoryJwtVerifier` and `CognitoJwtVerifier`: JWT token verifiers.
+- Registration/login/password-reset result dataclasses and helper functions such as `unique_roles`.
+
+Host applications should keep domain-specific roles, authorization policies,
+scope rules, and route permission matrices outside the kit.
+
+Install `persistence-kit[security]` for the memory provider/JWT verifier and
+`persistence-kit[security-cognito]` for Cognito support.
+
+`PersistenceKitSettings` centralizes common auth, storage, observability, AWS,
+and job-service settings. Host applications can inherit from it and override
+only product-specific defaults:
+
+```python
+from persistence_kit import Database, PersistenceKitSettings
+
+
+class Settings(PersistenceKitSettings):
+    service_name: str = "my-api"
+    key_status_history_database: Database = Database.MONGO
+    memory_seed_role_codes: tuple[str, ...] = ("admin", "operator")
+```
+
+`persistence_kit.security.factory` can build the identity provider and token
+verifier from that inherited settings object. `persistence_kit.storage.factory`
+does the same for export storage, and `persistence_kit.storage.routes` exposes
+the reusable FastAPI local export route.
+
 ## Typical Host Application Flow
 
 1. Define your entities as dataclasses.
@@ -118,13 +244,13 @@ Create the local environment and run tests from the library root:
 
 ```bash
 poetry lock
-poetry install --with dev
+poetry install --with dev --all-extras
 poetry run pytest -q
 ```
 
 Current validation baseline:
 
-- `persistence_kit`: `138 passed`
+- `persistence_kit`: `335 passed`
 
 ## Publish to PyPI (Manual)
 

persistence_kit-3.2.0/persistence_kit/__init__.py

@@ -0,0 +1,231 @@
+from importlib import import_module
+
+from .bootstrap.configuration import ConfigRegistry, configuration, set_config_package
+from .bootstrap.seeders import Seeder, SeederProvider
+from .bootstrap.startup import is_duplicate_startup_error, run_startup_bootstrap
+from .contracts.repository import Repository
+from .contracts.view_repository import ViewRepository
+from .settings import (
+    DEFAULT_MEMORY_JWT_ISSUER,
+    DEFAULT_MEMORY_JWT_SECRET,
+    DEFAULT_MEMORY_JWT_TTL_SECONDS,
+    LOCAL_DEFAULT_JOB_SERVICE_API_KEY,
+    AuthProvider,
+    DeploymentStage,
+    ExportStorageProvider,
+    PersistenceKitSettings,
+)
+from .settings.constants import Database
+from .settings.parsers import split_csv_list
+from .settings.repo_settings import RepoSettings
+from .storage import (
+    EXPORT_STORAGE_BUILDERS,
+    ExportStorage,
+    ExportStorageBuilder,
+    ObjectStorage,
+    StorageConfigError,
+    StorageError,
+    StoragePathError,
+    StoragePresignError,
+    StorageUploadError,
+    get_export_storage,
+)
+from .authenticated_user import AuthenticatedUser
+from .utils.upsert import dataclass_field_names, upsert_entity
+
+_OPTIONAL_EXPORTS = {
+    "ApiError": ("persistence_kit.api.common", "ApiError", "api"),
+    "pagination_params": ("persistence_kit.api.common", "pagination_params", "api"),
+    "BaseAPIException": ("persistence_kit.api.exceptions", "BaseAPIException", "api"),
+    "NotFoundException": ("persistence_kit.api.exceptions", "NotFoundException", "api"),
+    "ValidationException": ("persistence_kit.api.exceptions", "ValidationException", "api"),
+    "BusinessRuleException": (
+        "persistence_kit.api.exceptions",
+        "BusinessRuleException",
+        "api",
+    ),
+    "DatabaseException": ("persistence_kit.api.exceptions", "DatabaseException", "api"),
+    "handle_service_errors": (
+        "persistence_kit.api.error_handlers",
+        "handle_service_errors",
+        "api",
+    ),
+    "handle_repository_errors": (
+        "persistence_kit.api.error_handlers",
+        "handle_repository_errors",
+        "api",
+    ),
+    "build_api_router": ("persistence_kit.api.route_loader", "build_api_router", "api"),
+    "InMemoryRateLimiter": ("persistence_kit.api.rate_limit", "InMemoryRateLimiter", "api"),
+    "build_auth_rate_limit_dependency": (
+        "persistence_kit.api.rate_limit",
+        "build_auth_rate_limit_dependency",
+        "api",
+    ),
+    "IdentityProvider": ("persistence_kit.security.ports", "IdentityProvider", "security"),
+    "TokenVerifier": ("persistence_kit.security.ports", "TokenVerifier", "security"),
+    "CognitoIdentityProvider": (
+        "persistence_kit.security.providers",
+        "CognitoIdentityProvider",
+        "security-cognito",
+    ),
+    "MemorySecurityProvider": (
+        "persistence_kit.security.providers",
+        "MemorySecurityProvider",
+        "testing",
+    ),
+    "CognitoJwtVerifier": (
+        "persistence_kit.security.token_verifiers",
+        "CognitoJwtVerifier",
+        "security-cognito",
+    ),
+    "MemoryJwtVerifier": (
+        "persistence_kit.security.token_verifiers",
+        "MemoryJwtVerifier",
+        "testing",
+    ),
+    "get_identity_provider": (
+        "persistence_kit.security.factory",
+        "get_identity_provider",
+        "security",
+    ),
+    "get_token_verifier": (
+        "persistence_kit.security.factory",
+        "get_token_verifier",
+        "security",
+    ),
+    "RegistrationResult": (
+        "persistence_kit.security.registration",
+        "RegistrationResult",
+        "security",
+    ),
+    "RoleAssignmentResult": (
+        "persistence_kit.security.registration",
+        "RoleAssignmentResult",
+        "security",
+    ),
+    "UserStatusUpdateResult": (
+        "persistence_kit.security.registration",
+        "UserStatusUpdateResult",
+        "security",
+    ),
+    "LoginResult": ("persistence_kit.security.registration", "LoginResult", "security"),
+    "RefreshTokensResult": (
+        "persistence_kit.security.registration",
+        "RefreshTokensResult",
+        "security",
+    ),
+    "LogoutResult": ("persistence_kit.security.registration", "LogoutResult", "security"),
+    "PasswordResetCodeRequestResult": (
+        "persistence_kit.security.registration",
+        "PasswordResetCodeRequestResult",
+        "security",
+    ),
+    "PasswordResetConfirmResult": (
+        "persistence_kit.security.registration",
+        "PasswordResetConfirmResult",
+        "security",
+    ),
+    "PasswordResetResult": (
+        "persistence_kit.security.registration",
+        "PasswordResetResult",
+        "security",
+    ),
+    "RegisteredUserResult": (
+        "persistence_kit.security.registration",
+        "RegisteredUserResult",
+        "security",
+    ),
+    "RegisteredUsersPageResult": (
+        "persistence_kit.security.registration",
+        "RegisteredUsersPageResult",
+        "security",
+    ),
+    "validate_allowed_email_domain": (
+        "persistence_kit.security.registration",
+        "validate_allowed_email_domain",
+        "security",
+    ),
+    "unique_roles": ("persistence_kit.security.registration", "unique_roles", "security"),
+    "LocalObjectStorage": ("persistence_kit.storage.local", "LocalObjectStorage", "testing"),
+    "LocalExportStorageProvider": (
+        "persistence_kit.storage.local",
+        "LocalExportStorageProvider",
+        "testing",
+    ),
+    "S3ObjectStorage": ("persistence_kit.storage.s3", "S3ObjectStorage", "storage-s3"),
+    "S3ExportStorageProvider": (
+        "persistence_kit.storage.s3",
+        "S3ExportStorageProvider",
+        "storage-s3",
+    ),
+    "build_local_export_storage_router": (
+        "persistence_kit.storage.routes",
+        "build_local_export_storage_router",
+        "storage-routes",
+    ),
+    "serve_local_export": (
+        "persistence_kit.storage.routes",
+        "serve_local_export",
+        "storage-routes",
+    ),
+    "guess_export_media_type": (
+        "persistence_kit.storage.routes",
+        "guess_export_media_type",
+        "storage-routes",
+    ),
+}
+
+__all__ = [
+    "Repository",
+    "ViewRepository",
+    "split_csv_list",
+    "ConfigRegistry",
+    "configuration",
+    "Database",
+    "RepoSettings",
+    "AuthProvider",
+    "ExportStorageProvider",
+    "DeploymentStage",
+    "LOCAL_DEFAULT_JOB_SERVICE_API_KEY",
+    "DEFAULT_MEMORY_JWT_SECRET",
+    "DEFAULT_MEMORY_JWT_ISSUER",
+    "DEFAULT_MEMORY_JWT_TTL_SECONDS",
+    "PersistenceKitSettings",
+    "Seeder",
+    "SeederProvider",
+    "set_config_package",
+    "is_duplicate_startup_error",
+    "run_startup_bootstrap",
+    "AuthenticatedUser",
+    "dataclass_field_names",
+    "upsert_entity",
+    "ObjectStorage",
+    "StorageError",
+    "StorageConfigError",
+    "StoragePathError",
+    "StorageUploadError",
+    "StoragePresignError",
+    "ExportStorage",
+    "ExportStorageBuilder",
+    "EXPORT_STORAGE_BUILDERS",
+    "get_export_storage",
+    *_OPTIONAL_EXPORTS,
+]
+
+
+def __getattr__(name: str):
+    if name not in _OPTIONAL_EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module_name, attr_name, extra_name = _OPTIONAL_EXPORTS[name]
+    try:
+        module = import_module(module_name)
+    except ModuleNotFoundError as exc:
+        raise ModuleNotFoundError(
+            f"{name} requiere la capability opcional '{extra_name}'. "
+            f"Instala con `persistence-kit[{extra_name}]`."
+        ) from exc
+    value = getattr(module, attr_name)
+    globals()[name] = value
+    return value

{persistence_kit-3.0.2 → persistence_kit-3.2.0}/persistence_kit/api/__init__.py

@@ -7,6 +7,7 @@ from .exceptions import (
     NotFoundException,
     ValidationException,
 )
+from .rate_limit import InMemoryRateLimiter, build_auth_rate_limit_dependency
 from .route_loader import build_api_router
 
 __all__ = [
@@ -20,4 +21,6 @@ __all__ = [
     "handle_service_errors",
     "handle_repository_errors",
     "build_api_router",
+    "InMemoryRateLimiter",
+    "build_auth_rate_limit_dependency",
 ]