aws-python-helper 1.15.2__tar.gz → 1.16.0__tar.gz

{aws_python_helper-1.15.2 → aws_python_helper-1.16.0}/PKG-INFO

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

{aws_python_helper-1.15.2 → aws_python_helper-1.16.0}/aws_python_helper/repository/base.py

@@ -149,26 +149,66 @@ class Repository(ABC):
     @property
     def statuses(self) -> Optional[List[str]]:
         """
-        The values this record's `status` can take.
+        Los valores que puede tomar el `status` de este registro.
 
-        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:
+        Tres formas, según lo que la colección necesite:
 
-            class UserRepository(Repository):
+        **No declarar nada.** Se queda con los dos de siempre, `active` e
+        `inactive`, que es lo que hace que un listado pueda mostrar el estado de
+        cualquier cosa sin saber qué está mirando.
+
+        **Declarar `statuses`.** Reemplaza a los default: el vocabulario es ese y
+        no hay otro. Para una colección cuyo ciclo es completo y ajeno, donde
+        "activo" no significaría nada.
+
+            class SearchedKeyRepository(Repository):
                 @property
                 def statuses(self):
-                    return ["active", "pending", "inactive"]
+                    return ["queued", "in_progress", "complete", "failed"]
+
+        **Declarar `extra_statuses`.** Se suman a los default, que siguen
+        valiendo. Para una colección que tiene estados propios *además* del
+        ciclo de vida del registro.
+
+            class TaxSaleRepository(Repository):
+                @property
+                def extra_statuses(self):
+                    return ["new"]      # efectivo: new, active, 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.
+        Una escritura con un valor fuera del conjunto efectivo se rechaza, no se
+        guarda: un status que nadie esperaba llega a un panel como una etiqueta
+        desconocida y a una consulta como un silencio.
 
-        None for collections where a lifecycle makes no sense — sessions, tokens,
-        counters.
+        `None` para colecciones donde un ciclo de vida no significa nada
+        —sesiones, tokens, contadores—.
         """
         return list(DEFAULT_STATUSES)
 
+    @property
+    def extra_statuses(self) -> Optional[List[str]]:
+        """Valores propios que se agregan a los declarados, sin quitarlos.
+
+        La diferencia con `statuses` es qué pasa con `active` e `inactive`: acá
+        siguen valiendo. Ver la nota en `statuses`.
+        """
+        return None
+
+    @property
+    def effective_statuses(self) -> Optional[List[str]]:
+        """Lo que de verdad se acepta, ya resueltas las dos declaraciones.
+
+        Los extra van primero y sin repetir, porque el primero del conjunto es
+        el que recibe un registro nuevo cuando nadie dice otra cosa.
+        """
+        declared = self.statuses
+        extra = self.extra_statuses
+
+        if declared is None:
+            return list(dict.fromkeys(extra)) if extra else None
+        if not extra:
+            return list(declared)
+        return list(dict.fromkeys(list(extra) + list(declared)))
+
     @property
     def status_field(self) -> str:
         """Cómo se llama el campo que lleva el ciclo de vida del registro.
@@ -191,9 +231,14 @@ class Repository(ABC):
 
     @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
+        """Con qué nace un registro cuando nadie dice otra cosa.
+
+        El primero del conjunto efectivo, que con `extra_statuses` es el primero
+        de los propios: una venta nace `new`, no `active`, aunque `active`
+        también valga.
+        """
+        effective = self.effective_statuses
+        return effective[0] if effective else None
 
     @property
     def audit(self) -> bool:
@@ -277,7 +322,7 @@ class Repository(ABC):
             # La envoltura completa las escrituras; todo lo demás pasa de largo.
             self._collection_cache[key] = (
                 AuditedCollection(
-                    collection, self.statuses, self.default_status, self.status_field
+                    collection, self.effective_statuses, self.default_status, self.status_field
                 )
                 if self.audit
                 else collection

{aws_python_helper-1.15.2 → aws_python_helper-1.16.0}/aws_python_helper/utils/json_encoder.py

@@ -3,7 +3,7 @@ MongoDB JSON Encoder - Custom JSON encoder to handle MongoDB types
 """
 
 import json
-from datetime import datetime, date
+from datetime import datetime, date, timezone
 from decimal import Decimal
 from typing import Any
 
@@ -68,6 +68,15 @@ class MongoJSONEncoder(json.JSONEncoder):
         
         # Python datetime
         if isinstance(obj, datetime):
+            # Sin zona se asume UTC, que es lo que Mongo guarda y lo que el
+            # driver devuelve —naive— salvo que se lo configure para otra cosa.
+            #
+            # Sin esto la cadena sale sin marca y quien la lee la toma como hora
+            # local: en un navegador en UTC-5, un servicio que se anunció hace
+            # un minuto aparecía anunciándose "dentro de 5 horas". No falla
+            # nada, simplemente dice otra cosa.
+            if obj.tzinfo is None:
+                obj = obj.replace(tzinfo=timezone.utc)
             return obj.isoformat()
         
         # Python date

{aws_python_helper-1.15.2 → aws_python_helper-1.16.0}/aws_python_helper.egg-info/PKG-INFO

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

{aws_python_helper-1.15.2 → aws_python_helper-1.16.0}/aws_python_helper.egg-info/SOURCES.txt

@@ -59,6 +59,8 @@ aws_python_helper/utils/json_encoder.py
 aws_python_helper/utils/response.py
 aws_python_helper/utils/serializer.py
 tests/test_audit_stamp.py
+tests/test_effective_statuses.py
+tests/test_json_encoder.py
 tests/test_jwt_keys.py
 tests/test_model_query_schema.py
 tests/test_settings.py

{aws_python_helper-1.15.2 → aws_python_helper-1.16.0}/pyproject.toml

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

aws_python_helper-1.16.0/tests/test_effective_statuses.py

@@ -0,0 +1,90 @@
+"""Las tres formas de declarar el vocabulario de `status`."""
+
+from aws_python_helper.repository.audit import DEFAULT_STATUSES
+from aws_python_helper.repository.base import Repository
+
+
+class SinDeclarar(Repository):
+    """Se queda con los dos de siempre."""
+
+    @property
+    def collection_name(self):
+        return "sin"
+
+
+class CicloPropio(Repository):
+    """Reemplaza: `active` no significaría nada para una búsqueda."""
+
+    @property
+    def collection_name(self):
+        return "busquedas"
+
+    @property
+    def statuses(self):
+        return ["queued", "in_progress", "complete", "failed"]
+
+
+class CicloExtra(Repository):
+    """Suma: una venta nace `new` y además puede darse de baja."""
+
+    @property
+    def collection_name(self):
+        return "ventas"
+
+    @property
+    def extra_statuses(self):
+        return ["new"]
+
+
+class SinCiclo(Repository):
+    """Una colección donde un ciclo de vida no significa nada."""
+
+    @property
+    def collection_name(self):
+        return "tokens"
+
+    @property
+    def statuses(self):
+        return None
+
+
+class ExtraRepetido(Repository):
+    """Agrega uno que ya estaba: no se duplica."""
+
+    @property
+    def collection_name(self):
+        return "repetido"
+
+    @property
+    def extra_statuses(self):
+        return ["new", "active"]
+
+
+def test_sin_declarar_quedan_los_default():
+    assert SinDeclarar().effective_statuses == list(DEFAULT_STATUSES)
+    assert SinDeclarar().default_status == "active"
+
+
+def test_statuses_reemplaza_a_los_default():
+    assert CicloPropio().effective_statuses == [
+        "queued", "in_progress", "complete", "failed",
+    ]
+    assert "active" not in CicloPropio().effective_statuses
+
+
+def test_extra_se_suma_a_los_default():
+    assert CicloExtra().effective_statuses == ["new", "active", "inactive"]
+
+
+def test_el_primero_es_con_el_que_nace():
+    assert CicloPropio().default_status == "queued"
+    assert CicloExtra().default_status == "new"
+
+
+def test_sin_ciclo_no_valida_nada():
+    assert SinCiclo().effective_statuses is None
+    assert SinCiclo().default_status is None
+
+
+def test_un_extra_que_ya_era_default_no_se_repite():
+    assert ExtraRepetido().effective_statuses == ["new", "active", "inactive"]

aws_python_helper-1.16.0/tests/test_json_encoder.py

@@ -0,0 +1,51 @@
+"""Una fecha que sale de acá dice en qué zona está.
+
+Mongo guarda UTC y el driver la devuelve sin marca de zona. Mandada así, quien
+la lee la toma como hora local: en un navegador en UTC-5, algo que pasó hace un
+minuto se mostraba como "dentro de 5 horas". No falla nada — dice otra cosa.
+
+    ../constitution-core/venv/bin/python tests/test_json_encoder.py
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timedelta, timezone
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from aws_python_helper.utils.json_encoder import MongoJSONEncoder
+
+failures = []
+
+
+def check(label, condition):
+    print(f"  {'ok  ' if condition else 'FALLA'} {label}")
+    if not condition:
+        failures.append(label)
+
+
+print("== una fecha sin zona sale como UTC ==")
+naive = datetime(2026, 10, 1, 17, 25, 55)
+salida = json.loads(json.dumps({"at": naive}, cls=MongoJSONEncoder))["at"]
+print(f"    {salida}")
+check("lleva la marca de zona", salida.endswith("+00:00") or salida.endswith("Z"))
+check("no corre la hora", salida.startswith("2026-10-01T17:25:55"))
+
+print("\n== una que ya la trae se respeta ==")
+aware = datetime(2026, 10, 1, 17, 25, 55, tzinfo=timezone(timedelta(hours=-5)))
+salida = json.loads(json.dumps({"at": aware}, cls=MongoJSONEncoder))["at"]
+print(f"    {salida}")
+check("conserva su propia zona", salida.endswith("-05:00"))
+
+print("\n== y una fecha sin hora no se toca ==")
+from datetime import date as _date
+salida = json.loads(json.dumps({"on": _date(2026, 10, 1)}, cls=MongoJSONEncoder))["on"]
+print(f"    {salida}")
+check("sigue siendo una fecha", salida == "2026-10-01")
+
+print()
+if failures:
+    print(f"{len(failures)} fallas")
+    sys.exit(1)
+print("all good")