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

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

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

{aws_python_helper-1.15.3 → 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.3 → 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.3
+Version: 1.16.0
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
 License-Expression: MIT

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

@@ -59,6 +59,7 @@ 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

{aws_python_helper-1.15.3 → 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.3"
+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"]