aws-python-helper 1.5.0__tar.gz → 1.7.0__tar.gz

{aws_python_helper-1.5.0 → aws_python_helper-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aws-python-helper
-Version: 1.5.0
+Version: 1.7.0
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
 License-Expression: MIT

{aws_python_helper-1.5.0 → aws_python_helper-1.7.0}/aws_python_helper/__init__.py

@@ -26,7 +26,14 @@ from .utils.serializer import serialize_mongo_types
 
 # Repository
 from .repository.base import Repository
-from .repository.audit import current_actor, public_audit
+from .repository.audit import (
+    ACTIVE,
+    DEFAULT_STATUSES,
+    INACTIVE,
+    InvalidStatusError,
+    current_actor,
+    public_audit,
+)
 
 # Context
 from .context.session import Session, get_session, set_session
@@ -62,6 +69,10 @@ __all__ = [
     'Repository',
     'current_actor',
     'public_audit',
+    'ACTIVE',
+    'INACTIVE',
+    'DEFAULT_STATUSES',
+    'InvalidStatusError',
     'fargate_handler',
     'api_handler',
     'sqs_handler',

{aws_python_helper-1.5.0 → aws_python_helper-1.7.0}/aws_python_helper/api/base.py

@@ -288,6 +288,27 @@ class API(ABC):
             'headers': self._response_headers
         }
     
+    @property
+    def public(self) -> bool:
+        """
+        Whether this endpoint answers without a token.
+
+        Declared here, next to the code, so the permission catalog can leave it
+        out: a permission for something nobody needs permission for is noise in
+        every role screen, and an administrator ticking it would be granting
+        nothing.
+
+        This does not make an endpoint public — terraform does, by leaving
+        `authorization` unset on its lambda. This says so, so the rest of the
+        framework can act on it.
+
+            class AuthLoginAPI(API):
+                @property
+                def public(self):
+                    return True
+        """
+        return False
+
     @property
     def schema(self):
         """

{aws_python_helper-1.5.0 → aws_python_helper-1.7.0}/aws_python_helper/api/fetcher.py

@@ -7,6 +7,34 @@ import importlib.util
 from pathlib import Path
 from typing import List
 
+def load_controller_class(file_path: str):
+    """The API class a controller file defines.
+
+    Shared so the permission catalog asks the class the same questions the
+    dispatcher does — a second way of finding it would answer differently the
+    day one of them changes.
+    """
+    spec = importlib.util.spec_from_file_location("api_module", file_path)
+    if not spec or not spec.loader:
+        raise ImportError(f"Could not load module spec from: {file_path}")
+
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    for item_name in dir(module):
+        item = getattr(module, item_name)
+        if (isinstance(item, type) and
+                hasattr(item, 'process') and
+                item.__name__ not in ['API', 'ABC'] and
+                item.__module__ == module.__name__):
+            return item
+
+    raise ValueError(
+        f"No API class found in {file_path}\n"
+        f"Make sure your file exports a class that inherits from API"
+    )
+
+
 class Fetcher:
     """
     Dynamically load API controllers
@@ -187,30 +215,7 @@ class Fetcher:
                 f"Expected file for endpoint '{self.endpoint}' with method '{self.method}'"
             )
         
-        # Load module dynamically
-        spec = importlib.util.spec_from_file_location("api_module", file_path)
-        if not spec or not spec.loader:
-            raise ImportError(f"Could not load module spec from: {file_path}")
-        
-        module = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(module)
-        
-        # Search for a class that inherits from API
-        controller_class = None
-        for item_name in dir(module):
-            item = getattr(module, item_name)
-            if (isinstance(item, type) and
-                hasattr(item, 'process') and
-                item.__name__ not in ['API', 'ABC'] and
-                item.__module__ == module.__name__):
-                controller_class = item
-                break
-        
-        if not controller_class:
-            raise ValueError(
-                f"No API class found in {file_path}\n"
-                f"Make sure your file exports a class that inherits from API"
-            )
+        controller_class = load_controller_class(file_path)
         
         # Cache the class (not the instance)
         self._cache[file_path] = controller_class

{aws_python_helper-1.5.0 → aws_python_helper-1.7.0}/aws_python_helper/permissions/catalog.py

@@ -12,10 +12,14 @@ otherwise silently stop matching in the other, and an access check that never
 matches fails open or shut without anyone noticing.
 """
 
+import logging
 import os
+import re
 from typing import Dict, List
 
-from ..api.fetcher import Fetcher
+from ..api.fetcher import Fetcher, load_controller_class
+
+logger = logging.getLogger(__name__)
 
 # Cómo se llama el archivo según el método. `list` y `get` son ambos GET: uno
 # responde la colección, el otro un elemento.
@@ -46,6 +50,10 @@ def discover(api_root: str, service: str) -> List[Dict[str, str]]:
             if extension != ".py" or stem not in FILE_METHODS:
                 continue
 
+            controller = _controller(os.path.join(current, filename))
+            if controller and getattr(controller(), "public", False):
+                continue
+
             relative = os.path.relpath(current, api_root)
             parts = [] if relative == "." else relative.split(os.sep)
             path = "/" + "/".join(parts)
@@ -62,11 +70,40 @@ def discover(api_root: str, service: str) -> List[Dict[str, str]]:
                 "method": method,
                 "path": path,
                 "scope": "item" if stem == "get" else "collection",
+                "name": _readable(controller),
             })
 
     return sorted(found, key=lambda item: item["code"])
 
 
+def _controller(file_path: str):
+    """The controller class, or None if it cannot be read.
+
+    None errs towards listing the endpoint. A permission that appears for a
+    public endpoint is noise; one that disappears for a protected endpoint
+    leaves the check with nothing to match and locks everybody out of it.
+    """
+    try:
+        return load_controller_class(file_path)
+    except Exception as exc:
+        logger.warning("Could not read %s, listing it anyway: %s", file_path, exc)
+        return None
+
+
+def _readable(controller) -> str:
+    """The class name as words: `UsersInviteAPI` -> `Users Invite`.
+
+    A panel showing raw paths makes people read routing to answer "what does
+    this let someone do". The class already names the thing; this only spaces it
+    out. Empty when the class could not be read, so the panel falls back to the
+    path rather than inventing a name.
+    """
+    if controller is None:
+        return ""
+    name = re.sub(r"(API|Api)$", "", controller.__name__)
+    return re.sub(r"(?<=[a-z0-9])(?=[A-Z])", " ", name).strip()
+
+
 def service_wildcard(service: str) -> str:
     return f"{service}:*"
 

aws_python_helper-1.7.0/aws_python_helper/repository/__init__.py

@@ -0,0 +1,19 @@
+from .base import Repository
+from .audit import (
+    ACTIVE,
+    DEFAULT_STATUSES,
+    INACTIVE,
+    InvalidStatusError,
+    current_actor,
+    public_audit,
+)
+
+__all__ = [
+    'Repository',
+    'ACTIVE',
+    'INACTIVE',
+    'DEFAULT_STATUSES',
+    'InvalidStatusError',
+    'current_actor',
+    'public_audit',
+]

{aws_python_helper-1.5.0 → aws_python_helper-1.7.0}/aws_python_helper/repository/audit.py

@@ -1,10 +1,17 @@
 """
-Automatic audit stamping for every write.
+Framework-managed fields on every write: who, when, and what state.
 
 Records answer "who last touched this, and when" without any repository having to
-remember to fill it in. The four fields —created_at, created_by, updated_at,
-updated_by— are injected by wrapping the Motor collection, so call sites keep
-using `self.collection.insert_one(...)` exactly as before.
+remember to fill it in. The four audit fields —created_at, created_by,
+updated_at, updated_by— plus `status` are injected by wrapping the Motor
+collection, so call sites keep using `self.collection.insert_one(...)` exactly as
+before.
+
+`status` is the lifecycle of a record, uniform across every entity so a listing
+can show it without knowing what it is looking at. Two values by default, active
+and inactive; a repository declaring `statuses` gets its own set. A value outside
+that set is refused rather than stored: a status nobody expected reaches a panel
+as an unknown label and a query as a silent mismatch.
 
 Not every write comes from a person. A scraper, a queue consumer or a scheduled
 task writes too, and the stamp says so: "nobody knows" and "the system did it"
@@ -28,6 +35,11 @@ CREATED_AT = 'created_at'
 CREATED_BY = 'created_by'
 UPDATED_AT = 'updated_at'
 UPDATED_BY = 'updated_by'
+STATUS = 'status'
+
+ACTIVE = 'active'
+INACTIVE = 'inactive'
+DEFAULT_STATUSES = [ACTIVE, INACTIVE]
 
 
 def _system_actor() -> Dict[str, str]:
@@ -66,11 +78,27 @@ def _now() -> datetime:
     return datetime.now(timezone.utc)
 
 
-def stamp_new(document: Dict[str, Any]) -> Dict[str, Any]:
-    """The four fields on a document being created.
+class InvalidStatusError(ValueError):
+    """A status the repository does not declare."""
+
+
+def _check_status(value: Any, statuses: Optional[List[str]]) -> None:
+    if statuses and value is not None and value not in statuses:
+        raise InvalidStatusError(
+            f"'{value}' is not a valid status. Declared: {', '.join(statuses)}"
+        )
+
+
+def stamp_new(
+    document: Dict[str, Any],
+    statuses: Optional[List[str]] = None,
+    default_status: Optional[str] = None,
+) -> Dict[str, Any]:
+    """The framework fields on a document being created.
 
     Whatever the caller set explicitly wins: this fills gaps, it does not
-    overrule a repository that knows better.
+    overrule a repository that knows better. What it does not let pass is a
+    status outside the declared set.
     """
     if not isinstance(document, dict):
         return document
@@ -80,6 +108,10 @@ def stamp_new(document: Dict[str, Any]) -> Dict[str, Any]:
     document.setdefault(UPDATED_AT, now)
     document.setdefault(CREATED_BY, who)
     document.setdefault(UPDATED_BY, who)
+
+    if statuses:
+        document.setdefault(STATUS, default_status or statuses[0])
+        _check_status(document.get(STATUS), statuses)
     return document
 
 
@@ -95,6 +127,8 @@ def _merge_into_set(update: Dict[str, Any], values: Dict[str, Any], operator: st
 def stamp_update(
     update: Union[Dict[str, Any], List[Dict[str, Any]]],
     upsert: bool = False,
+    statuses: Optional[List[str]] = None,
+    default_status: Optional[str] = None,
 ) -> Union[Dict[str, Any], List[Dict[str, Any]]]:
     """The two 'updated' fields on a modification, and the 'created' ones on an upsert.
 
@@ -114,18 +148,28 @@ def stamp_update(
 
     # Un reemplazo entero —sin operadores— es un documento, no una modificación.
     if update and not any(key.startswith('$') for key in update):
-        return stamp_new(dict(update))
+        return stamp_new(dict(update), statuses, default_status)
 
     update = dict(update)
+    if statuses:
+        for operator in ('$set', '$setOnInsert'):
+            section = update.get(operator)
+            if isinstance(section, dict) and STATUS in section:
+                _check_status(section[STATUS], statuses)
+
     _merge_into_set(update, touched, '$set')
     if upsert:
-        # Si termina insertando, el registro nace ahora: created_* sólo en ese caso.
-        _merge_into_set(update, {CREATED_AT: now, CREATED_BY: who}, '$setOnInsert')
+        # Si termina insertando, el registro nace ahora: created_* y el estado
+        # inicial sólo en ese caso.
+        born = {CREATED_AT: now, CREATED_BY: who}
+        if statuses:
+            born[STATUS] = default_status or statuses[0]
+        _merge_into_set(update, born, '$setOnInsert')
     return update
 
 
 class AuditedCollection:
-    """A Motor collection that stamps who wrote and when.
+    """A Motor collection that fills in who wrote, when, and the record's status.
 
     Only the write methods are intercepted; everything else —find, aggregate,
     count_documents, create_index— passes straight through untouched.
@@ -135,10 +179,23 @@ class AuditedCollection:
     than asking for the stamp explicitly.
     """
 
-    __slots__ = ('_collection',)
+    __slots__ = ('_collection', '_statuses', '_default_status')
 
-    def __init__(self, collection: Any):
+    def __init__(
+        self,
+        collection: Any,
+        statuses: Optional[List[str]] = None,
+        default_status: Optional[str] = None,
+    ):
         object.__setattr__(self, '_collection', collection)
+        object.__setattr__(self, '_statuses', statuses)
+        object.__setattr__(self, '_default_status', default_status)
+
+    def _new(self, document: Dict[str, Any]) -> Dict[str, Any]:
+        return stamp_new(document, self._statuses, self._default_status)
+
+    def _update(self, update: Any, upsert: bool) -> Any:
+        return stamp_update(update, upsert, self._statuses, self._default_status)
 
     def __getattr__(self, name: str) -> Any:
         return getattr(self._collection, name)
@@ -147,36 +204,36 @@ class AuditedCollection:
         return f'AuditedCollection({self._collection!r})'
 
     async def insert_one(self, document: Dict[str, Any], *args: Any, **kwargs: Any):
-        return await self._collection.insert_one(stamp_new(document), *args, **kwargs)
+        return await self._collection.insert_one(self._new(document), *args, **kwargs)
 
     async def insert_many(self, documents: Any, *args: Any, **kwargs: Any):
         return await self._collection.insert_many(
-            [stamp_new(document) for document in documents], *args, **kwargs
+            [self._new(document) for document in documents], *args, **kwargs
         )
 
     async def update_one(self, filter: Any, update: Any, *args: Any, **kwargs: Any):
         return await self._collection.update_one(
-            filter, stamp_update(update, kwargs.get('upsert', False)), *args, **kwargs
+            filter, self._update(update, kwargs.get('upsert', False)), *args, **kwargs
         )
 
     async def update_many(self, filter: Any, update: Any, *args: Any, **kwargs: Any):
         return await self._collection.update_many(
-            filter, stamp_update(update, kwargs.get('upsert', False)), *args, **kwargs
+            filter, self._update(update, kwargs.get('upsert', False)), *args, **kwargs
         )
 
     async def find_one_and_update(self, filter: Any, update: Any, *args: Any, **kwargs: Any):
         return await self._collection.find_one_and_update(
-            filter, stamp_update(update, kwargs.get('upsert', False)), *args, **kwargs
+            filter, self._update(update, kwargs.get('upsert', False)), *args, **kwargs
         )
 
     async def replace_one(self, filter: Any, replacement: Any, *args: Any, **kwargs: Any):
         return await self._collection.replace_one(
-            filter, stamp_new(dict(replacement)), *args, **kwargs
+            filter, self._new(dict(replacement)), *args, **kwargs
         )
 
     async def find_one_and_replace(self, filter: Any, replacement: Any, *args: Any, **kwargs: Any):
         return await self._collection.find_one_and_replace(
-            filter, stamp_new(dict(replacement)), *args, **kwargs
+            filter, self._new(dict(replacement)), *args, **kwargs
         )
 
 

{aws_python_helper-1.5.0 → aws_python_helper-1.7.0}/aws_python_helper/repository/base.py

@@ -13,7 +13,7 @@ from typing import Any, Dict, List, Optional, Tuple
 from ..database.mongo_manager import MongoManager
 from ..database.external_mongo_manager import ExternalMongoManager
 from ..context.session import get_session
-from .audit import AuditedCollection
+from .audit import DEFAULT_STATUSES, AuditedCollection
 
 
 class Repository(ABC):
@@ -38,6 +38,11 @@ class Repository(ABC):
         indexes (list): List of index definitions to create automatically.
         audit (bool): Stamp created_at/created_by/updated_at/updated_by on every
             write. Default: True — no repository has to remember to do it.
+        statuses (list[str] | None): Allowed values of the record's `status`.
+            Default: ['active', 'inactive']. None means this collection has no
+            status at all.
+        default_status (str): What a new record gets. Default: the first of
+            `statuses`.
 
     Usage:
         # Core repository — always uses 'core' database
@@ -141,6 +146,35 @@ class Repository(ABC):
         """Whether this repository uses an external MongoDB cluster. Default: False."""
         return False
 
+    @property
+    def statuses(self) -> Optional[List[str]]:
+        """
+        The values this record's `status` can take.
+
+        Every entity carries one, and the same two by default, so a listing can
+        show the state of anything without knowing what it is looking at. A
+        repository with its own lifecycle declares it:
+
+            class UserRepository(Repository):
+                @property
+                def statuses(self):
+                    return ["active", "pending", "inactive"]
+
+        A write with a value outside this set is refused, not stored: an
+        unexpected status reaches a panel as an unknown label and a query as a
+        silent mismatch.
+
+        None for collections where a lifecycle makes no sense — sessions, tokens,
+        counters.
+        """
+        return list(DEFAULT_STATUSES)
+
+    @property
+    def default_status(self) -> Optional[str]:
+        """What a record gets when nobody says otherwise. First of `statuses`."""
+        declared = self.statuses
+        return declared[0] if declared else None
+
     @property
     def audit(self) -> bool:
         """
@@ -220,9 +254,11 @@ class Repository(ABC):
                 db = MongoManager.get_database(self.database_name)
 
             collection = db[self.collection_name]
-            # La envoltura sella las escrituras; todo lo demás pasa de largo.
+            # La envoltura completa las escrituras; todo lo demás pasa de largo.
             self._collection_cache[key] = (
-                AuditedCollection(collection) if self.audit else collection
+                AuditedCollection(collection, self.statuses, self.default_status)
+                if self.audit
+                else collection
             )
 
         return self._collection_cache[key]

{aws_python_helper-1.5.0 → aws_python_helper-1.7.0}/aws_python_helper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aws-python-helper
-Version: 1.5.0
+Version: 1.7.0
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
 License-Expression: MIT

{aws_python_helper-1.5.0 → aws_python_helper-1.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aws-python-helper"
-version = "1.5.0"
+version = "1.7.0"
 description = "AWS Python Helper Framework"
 readme = "README.md"
 requires-python = ">=3.9"

aws_python_helper-1.5.0/aws_python_helper/repository/__init__.py

@@ -1,4 +0,0 @@
-from .base import Repository
-from .audit import current_actor, public_audit
-
-__all__ = ['Repository', 'current_actor', 'public_audit']