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

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

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

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

@@ -26,6 +26,7 @@ from .utils.serializer import serialize_mongo_types
 
 # Repository
 from .repository.base import Repository
+from .repository.audit import current_actor, public_audit
 
 # Context
 from .context.session import Session, get_session, set_session
@@ -59,6 +60,8 @@ __all__ = [
     'FargateExecutor',
     'Lambda',
     'Repository',
+    'current_actor',
+    'public_audit',
     'fargate_handler',
     'api_handler',
     'sqs_handler',

{aws_python_helper-1.3.0 → aws_python_helper-1.5.0}/aws_python_helper/api/dispatcher.py

@@ -79,8 +79,15 @@ class Dispatcher:
             # 2. Authorization based on mode
             authorization = os.getenv('AUTHORIZATION', '').lower()
             requires_user = authorization in ('user', 'full', 'permission')
-            requires_state = authorization in ('state', 'full')
-            requires_permission = authorization == 'permission' 
+            requires_permission = authorization == 'permission'
+
+            # Pedir el state es independiente de pedir un permiso, así que va por
+            # su propia variable. Los valores viejos `state` y `full` la implican,
+            # para que un servicio sin migrar siga comportándose igual.
+            requires_state = (
+                authorization in ('state', 'full')
+                or os.getenv('REQUIRES_STATE', '').lower() in ('1', 'true', 'yes')
+            )
 
             # 2a. Authenticate (if mode requires user)
             if requires_user:

aws_python_helper-1.5.0/aws_python_helper/repository/__init__.py

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

aws_python_helper-1.5.0/aws_python_helper/repository/audit.py

@@ -0,0 +1,204 @@
+"""
+Automatic audit stamping for every write.
+
+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.
+
+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"
+are different answers.
+
+Author is stored denormalised —id plus the name as it read at the time— so
+reading a record never needs a second query, and renaming someone later does not
+rewrite history.
+"""
+
+import os
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Union
+
+from ..context.session import get_session
+
+USER = 'user'
+SYSTEM = 'system'
+
+CREATED_AT = 'created_at'
+CREATED_BY = 'created_by'
+UPDATED_AT = 'updated_at'
+UPDATED_BY = 'updated_by'
+
+
+def _system_actor() -> Dict[str, str]:
+    """The process doing the writing, when no person is behind it."""
+    service = os.getenv('SERVICE_CODE') or os.getenv('NAMESPACE') or 'constitution'
+    # Cada entrypoint deja su rastro: la lambda su nombre, el task el suyo.
+    process = (
+        os.getenv('PROCESS_NAME')
+        or os.getenv('AWS_LAMBDA_FUNCTION_NAME')
+        or os.getenv('TASK_NAME')
+        or service
+    )
+    return {'type': SYSTEM, 'id': service, 'name': process}
+
+
+def current_actor() -> Dict[str, str]:
+    """Who is writing right now, according to the request-scoped session."""
+    try:
+        session = get_session()
+    except Exception:
+        return _system_actor()
+
+    user = getattr(session, 'user', None) if session else None
+    if not isinstance(user, dict):
+        return _system_actor()
+
+    user_id = user.get('_id') or user.get('id') or user.get('user_id')
+    if not user_id:
+        return _system_actor()
+
+    name = user.get('name') or user.get('email') or str(user_id)
+    return {'type': USER, 'id': str(user_id), 'name': name}
+
+
+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.
+
+    Whatever the caller set explicitly wins: this fills gaps, it does not
+    overrule a repository that knows better.
+    """
+    if not isinstance(document, dict):
+        return document
+
+    now, who = _now(), current_actor()
+    document.setdefault(CREATED_AT, now)
+    document.setdefault(UPDATED_AT, now)
+    document.setdefault(CREATED_BY, who)
+    document.setdefault(UPDATED_BY, who)
+    return document
+
+
+def _merge_into_set(update: Dict[str, Any], values: Dict[str, Any], operator: str) -> None:
+    section = update.get(operator)
+    if not isinstance(section, dict):
+        section = {}
+        update[operator] = section
+    for key, value in values.items():
+        section.setdefault(key, value)
+
+
+def stamp_update(
+    update: Union[Dict[str, Any], List[Dict[str, Any]]],
+    upsert: bool = False,
+) -> Union[Dict[str, Any], List[Dict[str, Any]]]:
+    """The two 'updated' fields on a modification, and the 'created' ones on an upsert.
+
+    An update can also be an aggregation pipeline, and a pipeline takes stages,
+    not operators: there the stamp goes as one more `$set` stage at the end.
+    """
+    now, who = _now(), current_actor()
+    touched = {UPDATED_AT: now, UPDATED_BY: who}
+
+    if isinstance(update, list):
+        # En un pipeline `$set` es una etapa y pisa lo anterior a propósito: va al
+        # final para que el sello no lo tape una etapa posterior.
+        return update + [{'$set': {UPDATED_AT: now, UPDATED_BY: who}}]
+
+    if not isinstance(update, dict):
+        return 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))
+
+    update = dict(update)
+    _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')
+    return update
+
+
+class AuditedCollection:
+    """A Motor collection that stamps who wrote and when.
+
+    Only the write methods are intercepted; everything else —find, aggregate,
+    count_documents, create_index— passes straight through untouched.
+
+    `bulk_write` is deliberately left alone: its operations carry their own
+    filters and updates, and silently rewriting them would be harder to predict
+    than asking for the stamp explicitly.
+    """
+
+    __slots__ = ('_collection',)
+
+    def __init__(self, collection: Any):
+        object.__setattr__(self, '_collection', collection)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._collection, name)
+
+    def __repr__(self) -> str:
+        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)
+
+    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
+        )
+
+    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
+        )
+
+    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
+        )
+
+    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
+        )
+
+    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
+        )
+
+    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
+        )
+
+
+def public_audit(document: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """Leaves the audit fields ready to show: name and type, dates in ISO.
+
+    The author travels as name plus type because a panel has to tell a person
+    from a process, not just print a string.
+    """
+    if not isinstance(document, dict):
+        return document
+
+    document = dict(document)
+    for field in (CREATED_BY, UPDATED_BY):
+        value = document.get(field)
+        if isinstance(value, dict):
+            document[field] = {'name': value.get('name'), 'type': value.get('type', USER)}
+    for field in (CREATED_AT, UPDATED_AT):
+        value = document.get(field)
+        if isinstance(value, datetime):
+            # Sin tzinfo Mongo devuelve naive, y el navegador lo leería como hora local.
+            if value.tzinfo is None:
+                value = value.replace(tzinfo=timezone.utc)
+            document[field] = value.isoformat()
+    return document

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

@@ -13,6 +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
 
 
 class Repository(ABC):
@@ -35,6 +36,8 @@ class Repository(ABC):
         is_external (bool): Whether to use an external MongoDB cluster. Default: False.
         cluster_name (str): External cluster name. Required if is_external=True.
         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.
 
     Usage:
         # Core repository — always uses 'core' database
@@ -138,6 +141,24 @@ class Repository(ABC):
         """Whether this repository uses an external MongoDB cluster. Default: False."""
         return False
 
+    @property
+    def audit(self) -> bool:
+        """
+        Whether writes carry created_at/created_by/updated_at/updated_by.
+
+        On by default, so a record always answers who last touched it and when
+        without any repository having to fill it in. The author is a person when
+        a request carries a token, and the process itself otherwise.
+
+        Turn it off only where the stamp would be noise: collections that already
+        are a log of who did what (sessions, tokens), or raw scraped data written
+        in bulk where the author is always the same process.
+
+            class TokenRepository(Repository):
+                audit = False
+        """
+        return True
+
     @property
     def cluster_name(self) -> Optional[str]:
         """
@@ -198,7 +219,11 @@ class Repository(ABC):
             else:
                 db = MongoManager.get_database(self.database_name)
 
-            self._collection_cache[key] = db[self.collection_name]
+            collection = db[self.collection_name]
+            # La envoltura sella las escrituras; todo lo demás pasa de largo.
+            self._collection_cache[key] = (
+                AuditedCollection(collection) if self.audit else collection
+            )
 
         return self._collection_cache[key]
 

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

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

{aws_python_helper-1.3.0 → aws_python_helper-1.5.0}/aws_python_helper.egg-info/SOURCES.txt

@@ -42,6 +42,7 @@ aws_python_helper/model_query/base.py
 aws_python_helper/permissions/__init__.py
 aws_python_helper/permissions/catalog.py
 aws_python_helper/repository/__init__.py
+aws_python_helper/repository/audit.py
 aws_python_helper/repository/base.py
 aws_python_helper/sns/__init__.py
 aws_python_helper/sns/publisher.py

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

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

aws_python_helper-1.3.0/aws_python_helper/repository/__init__.py

@@ -1,3 +0,0 @@
-from .base import Repository
-
-__all__ = ['Repository']