hexcore 6.0.0__tar.gz → 6.0.2__tar.gz

{hexcore-6.0.0/hexcore.egg-info → hexcore-6.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 6.0.0
+Version: 6.0.2
 Summary: Núcleo reutilizable para proyectos Python con arquitectura hexagonal y event handling. Provee abstracciones, utilidades y contratos para DDD, eventos y desacoplamiento de infraestructura.
 Author-email: "David Latosefki (Indroic)" <indroic@outlook.com>
 License-Expression: MIT
@@ -385,6 +385,18 @@ admin = build_root_router(
 mount_routers(app, [admin, (public_router, {"prefix": "/v1"})])
 ```
 
+`children` acepta también una **secuencia**, y no es azúcar: un dict no puede tener dos claves
+`""`, así que un raíz con varios hijos que **ya traen su propio prefijo** —lo normal cuando cada
+feature declara sus rutas completas— no se puede expresar con un mapa.
+
+```python
+# usuarios_router y tickets_router ya son APIRouter(prefix="/usuarios") y (prefix="/tickets").
+api_v1 = build_root_router("/api/v1", [usuarios_router, tickets_router])
+
+# Se pueden mezclar: un router pelado equivale a ("", router).
+api_v1 = build_root_router("/api/v1", [usuarios_router, ("/reports", reports_router)])
+```
+
 ### Endpoints de listado y búsqueda
 
 ```python
@@ -706,6 +718,28 @@ otro origen (Mongo, Redis, un YAML), implementá `cqrs.ICronJobRepository`.
 `cron_job()` deriva el `task_name` de `__cqrs_task_name__`: escribirlo a mano es cómo se acaba
 con un cron que encola una tarea ya renombrada, y el fallo aparece en el worker.
 
+Cada job lleva además una `description` que viaja a la tabla. El scheduler no la usa: es lo que
+un panel le muestra al operador para que sepa **qué hace** un cron antes de desactivarlo — con
+sólo `task_name` y una expresión cron no se distingue apagar algo inofensivo de dejar de
+facturar. Por defecto sale de la primera línea del docstring de la tarea, que suele ser
+exactamente eso:
+
+```python
+@cqrs.background_task(queue="billing")
+async def emitir_facturas() -> None:
+    """Emite las facturas del mes y las envía por email."""
+    ...
+
+cqrs.cron_job(emitir_facturas, "0 6 1 * *")
+# description == "Emite las facturas del mes y las envía por email."
+
+cqrs.cron_job(cerrar_caja, "0 3 * * *", description="Cierra la caja del día.")
+```
+
+> Si tu tabla es anterior a esta columna, la migración es un `add_column` nullable —
+> `create_cron_tables()` lo trae escrito en su docstring. Un modelo propio que no la tenga no
+> rompe: el seed inserta lo que la tabla admita.
+
 **Cómo decide si toca ejecutar.** No compara contra el minuto actual, sino que busca si hubo
 alguna ocurrencia entre `last_run_at` y ahora:
 
@@ -884,18 +918,23 @@ estructura de migraciones con Alembic.
 
 | Serie | Estado | Qué significa |
 | :-- | :-- | :-- |
-| **5.x** | ✅ **Activa** | La única soportada. Recibe features y correcciones. |
+| **6.x** | ✅ **Activa** | La única soportada. Recibe features y correcciones. |
+| **5.x** | ⛔ **Deprecada** | Misma superficie de API que 6.x. Migrar es actualizar la versión. |
 | **4.x** | ⛔ **Deprecada** | Aplicación **parcial**: le faltan el fix del event loop de Celery, las fachadas y la documentación alineada. |
 | **3.x** | ⛔ **Deprecada** | Aplicación **parcial**: tiene las correcciones P0/P1 pero ninguna de las factories de FastAPI. |
 | **2.x** | ⛔ **Deprecada** | Contiene los bugs silenciosos corregidos en 5.x (ver abajo). |
 | **1.x** | ⛔ **Deprecada** | Sin soporte de ningún tipo. |
 
-**Todo lo anterior a 5.0 está deprecado. Migrá a 5.x.**
+**Todo lo anterior a 5.0 está deprecado. Migrá a 6.x.**
 
 3.0.0 y 4.0.0 existen sólo porque el trabajo se mergeó por fases y cada merge disparó un bump
 automático: **no son releases pensadas para usarse**, son cortes intermedios de la misma
 migración. 5.0.0 es la primera versión completa.
 
+6.0.0 es el mismo caso: la disparó un PR de documentación con un commit `feat!:`. No hay
+**ninguna** ruptura de API entre 5.x y 6.x — los alias anteriores a 5.0 siguen importables y
+siguen avisando.
+
 ### Por qué 2.x y anteriores no deberían estar en producción
 
 No es una cuestión de estilo: 2.x tiene defectos que no lanzan excepción y no aparecen en logs

{hexcore-6.0.0 → hexcore-6.0.2}/README.md

@@ -340,6 +340,18 @@ admin = build_root_router(
 mount_routers(app, [admin, (public_router, {"prefix": "/v1"})])
 ```
 
+`children` acepta también una **secuencia**, y no es azúcar: un dict no puede tener dos claves
+`""`, así que un raíz con varios hijos que **ya traen su propio prefijo** —lo normal cuando cada
+feature declara sus rutas completas— no se puede expresar con un mapa.
+
+```python
+# usuarios_router y tickets_router ya son APIRouter(prefix="/usuarios") y (prefix="/tickets").
+api_v1 = build_root_router("/api/v1", [usuarios_router, tickets_router])
+
+# Se pueden mezclar: un router pelado equivale a ("", router).
+api_v1 = build_root_router("/api/v1", [usuarios_router, ("/reports", reports_router)])
+```
+
 ### Endpoints de listado y búsqueda
 
 ```python
@@ -661,6 +673,28 @@ otro origen (Mongo, Redis, un YAML), implementá `cqrs.ICronJobRepository`.
 `cron_job()` deriva el `task_name` de `__cqrs_task_name__`: escribirlo a mano es cómo se acaba
 con un cron que encola una tarea ya renombrada, y el fallo aparece en el worker.
 
+Cada job lleva además una `description` que viaja a la tabla. El scheduler no la usa: es lo que
+un panel le muestra al operador para que sepa **qué hace** un cron antes de desactivarlo — con
+sólo `task_name` y una expresión cron no se distingue apagar algo inofensivo de dejar de
+facturar. Por defecto sale de la primera línea del docstring de la tarea, que suele ser
+exactamente eso:
+
+```python
+@cqrs.background_task(queue="billing")
+async def emitir_facturas() -> None:
+    """Emite las facturas del mes y las envía por email."""
+    ...
+
+cqrs.cron_job(emitir_facturas, "0 6 1 * *")
+# description == "Emite las facturas del mes y las envía por email."
+
+cqrs.cron_job(cerrar_caja, "0 3 * * *", description="Cierra la caja del día.")
+```
+
+> Si tu tabla es anterior a esta columna, la migración es un `add_column` nullable —
+> `create_cron_tables()` lo trae escrito en su docstring. Un modelo propio que no la tenga no
+> rompe: el seed inserta lo que la tabla admita.
+
 **Cómo decide si toca ejecutar.** No compara contra el minuto actual, sino que busca si hubo
 alguna ocurrencia entre `last_run_at` y ahora:
 
@@ -839,18 +873,23 @@ estructura de migraciones con Alembic.
 
 | Serie | Estado | Qué significa |
 | :-- | :-- | :-- |
-| **5.x** | ✅ **Activa** | La única soportada. Recibe features y correcciones. |
+| **6.x** | ✅ **Activa** | La única soportada. Recibe features y correcciones. |
+| **5.x** | ⛔ **Deprecada** | Misma superficie de API que 6.x. Migrar es actualizar la versión. |
 | **4.x** | ⛔ **Deprecada** | Aplicación **parcial**: le faltan el fix del event loop de Celery, las fachadas y la documentación alineada. |
 | **3.x** | ⛔ **Deprecada** | Aplicación **parcial**: tiene las correcciones P0/P1 pero ninguna de las factories de FastAPI. |
 | **2.x** | ⛔ **Deprecada** | Contiene los bugs silenciosos corregidos en 5.x (ver abajo). |
 | **1.x** | ⛔ **Deprecada** | Sin soporte de ningún tipo. |
 
-**Todo lo anterior a 5.0 está deprecado. Migrá a 5.x.**
+**Todo lo anterior a 5.0 está deprecado. Migrá a 6.x.**
 
 3.0.0 y 4.0.0 existen sólo porque el trabajo se mergeó por fases y cada merge disparó un bump
 automático: **no son releases pensadas para usarse**, son cortes intermedios de la misma
 migración. 5.0.0 es la primera versión completa.
 
+6.0.0 es el mismo caso: la disparó un PR de documentación con un commit `feat!:`. No hay
+**ninguna** ruptura de API entre 5.x y 6.x — los alias anteriores a 5.0 siguen importables y
+siguen avisando.
+
 ### Por qué 2.x y anteriores no deberían estar en producción
 
 No es una cuestión de estilo: 2.x tiene defectos que no lanzan excepción y no aparecen en logs

{hexcore-6.0.0 → hexcore-6.0.2}/hexcore/_deprecation.py

@@ -3,7 +3,7 @@ Mecanismo de deprecación de la superficie de API anterior a 5.0.
 
 Conviven dos nombres para varios conceptos (`AbstractCommandBus`/`ICommandBus`,
 `AbstractSerializer`/`ISerializer`, …) por retrocompatibilidad con 1.x/2.x. Los canónicos
-son los `Abstract*`; los alias siguen funcionando, pero avisan y se eliminarán en 6.0.
+son los `Abstract*`; los alias siguen funcionando, pero avisan y se eliminarán en 7.0.
 
 Un alias declarado como `ICommandBus = AbstractCommandBus` **no puede avisar**: es una
 asignación, y leerlo no ejecuta nada. Por eso el aviso se implementa con `__getattr__` de
@@ -34,7 +34,14 @@ __all__ = [
 
 #: Versión en la que se eliminan los alias. Se menciona en cada aviso para que el usuario
 #: sepa cuánto margen tiene.
-REMOVED_IN = "6.0"
+#:
+#: **Tiene que ser estrictamente mayor que la versión publicada**, o el aviso se contradice
+#: a sí mismo: anunciar "se elimina en 6.0" corriendo en 6.0.0, con los alias delante, le
+#: enseña al usuario que estos avisos no hay que leerlos. Ya pasó, porque en este repo dos
+#: majors salieron de commits `feat!:` involuntarios. Lo vigila
+#: `test_removed_in_is_ahead_of_the_published_version`: si un bump vuelve a alcanzar a este
+#: valor, el fallo salta en CI y no en el aviso que lee el usuario.
+REMOVED_IN = "7.0"
 
 
 def warn_deprecated(

{hexcore-6.0.0 → hexcore-6.0.2}/hexcore/domain/cqrs/cron.py

@@ -20,10 +20,19 @@ class CronJobDefinition:
     payload: dict[str, t.Any] = field(default_factory=dict)
     queue: str = "default"
     is_active: bool = True
-    
+
     # Para control de estado si se usa sin locks distribuidos
     last_run_at: datetime | None = None
 
+    # Qué hace el job, en prosa. No lo usa el scheduler: existe para el humano que ve la
+    # tabla en un panel de administración y tiene que decidir si desactivar un cron. Sin
+    # esto sólo se ve `task_name` y una expresión cron, que no dicen si apagarlo es
+    # inofensivo o deja de facturar.
+    #
+    # Va al final del dataclass a propósito: intercalarlo cambiaría el significado de los
+    # argumentos posicionales de quien ya construye definiciones a mano.
+    description: str | None = None
+
 
 class ICronJobRepository(abc.ABC):
     """

{hexcore-6.0.0 → hexcore-6.0.2}/hexcore/infrastructure/api/routing.py

@@ -17,10 +17,35 @@ __all__ = ["build_root_router", "mount_routers"]
 # (`prefix`, `tags`, `dependencies`…).
 MountableRouter = t.Union[APIRouter, t.Tuple[APIRouter, t.Dict[str, t.Any]]]
 
+# Los hijos de un router raíz. El `Mapping` es la forma bonita cuando cada hijo tiene su
+# sub-prefijo; la secuencia existe porque un dict **no puede** tener dos claves `""`, y un
+# raíz cuyos hijos ya declaran sus rutas completas necesita exactamente eso.
+RouterChildren = t.Union[
+    t.Mapping[str, APIRouter],
+    t.Sequence[t.Union[APIRouter, t.Tuple[str, APIRouter]]],
+]
+
+
+def _iter_children(
+    children: RouterChildren,
+) -> t.Iterator[t.Tuple[str, APIRouter]]:
+    """Normaliza las dos formas de `children` a pares ``(sub_prefijo, router)``."""
+    if isinstance(children, t.Mapping):
+        yield from children.items()
+        return
+
+    for entry in children:
+        if isinstance(entry, tuple):
+            yield entry
+        else:
+            # Un router pelado en la secuencia = sin sub-prefijo. Es el caso que motivó
+            # aceptar secuencias, así que merece no tener que escribir `("", router)`.
+            yield "", entry
+
 
 def build_root_router(
     prefix: str,
-    children: t.Mapping[str, APIRouter],
+    children: RouterChildren,
     *,
     dependencies: t.Sequence[t.Any] = (),
     tags: list[str] | None = None,
@@ -31,8 +56,16 @@ def build_root_router(
 
     Args:
         prefix: Prefijo del router raíz (p. ej. ``"/admin"``).
-        children: Mapa ``{sub_prefijo: router}``. Un sub-prefijo vacío monta el hijo
-            directamente sobre el prefijo raíz.
+        children: Los hijos, en cualquiera de las dos formas:
+
+            - **Mapa** ``{sub_prefijo: router}``. Un sub-prefijo vacío monta el hijo
+              directamente sobre el prefijo raíz.
+            - **Secuencia** de routers o de pares ``(sub_prefijo, router)``. Un router
+              pelado equivale a sub-prefijo vacío.
+
+            La secuencia no es azúcar: un dict no puede tener **dos** claves ``""``, así
+            que un raíz con varios hijos que ya traen su propio prefijo —lo normal cuando
+            cada feature declara sus rutas completas— no se puede expresar con un mapa.
         dependencies: Dependencias comunes a todos los hijos (típicamente la auth).
         tags: Tags comunes.
         **router_kwargs: Se pasan tal cual a `APIRouter` (``responses``,
@@ -49,6 +82,9 @@ def build_root_router(
             dependencies=[Depends(require_admin)],
             tags=["admin"],
         )
+
+        # Hijos que ya declaran sus rutas completas: no hay sub-prefijo que poner.
+        api_router = build_root_router("/api/v1", [usuarios_router, tickets_router])
     """
     root = APIRouter(
         prefix=prefix,
@@ -56,7 +92,7 @@ def build_root_router(
         tags=t.cast(t.Any, tags),
         **router_kwargs,
     )
-    for child_prefix, child in children.items():
+    for child_prefix, child in _iter_children(children):
         root.include_router(child, prefix=child_prefix)
     return root
 

{hexcore-6.0.0 → hexcore-6.0.2}/hexcore/infrastructure/cqrs/cron_sql.py

@@ -69,6 +69,11 @@ class CronJobModelMixin:
     last_run_at: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), nullable=True, default=None
     )
+    # Nullable: las tablas que ya existen no tienen la columna, y una migración que la
+    # añadiera NOT NULL exigiría inventarle una descripción a cada job ya sembrado.
+    description: Mapped[str | None] = mapped_column(
+        String(512), nullable=True, default=None
+    )
 
     @declared_attr
     def payload(cls) -> Mapped[dict[str, t.Any]]:  # noqa: N805
@@ -85,6 +90,7 @@ class CronJobModelMixin:
             queue=self.queue,
             is_active=self.is_active,
             last_run_at=self.last_run_at,
+            description=self.description,
         )
 
 
@@ -196,22 +202,28 @@ async def seed_cron_jobs(
             return 0
 
         statement = _insert_ignore(session, model)
+        # Un modelo propio anterior a la columna `description` no la tiene, y un INSERT de
+        # Core con una clave que no es columna revienta con `Unconsumed column names`. Se
+        # siembra lo que la tabla admita en vez de tirar el arranque entero.
+        columns = set(model.__table__.c.keys())
         inserted = 0
         # Fila a fila para que `rowcount` sea fiable en todos los dialectos: con
         # executemany varios drivers devuelven -1 y el contador mentiría. Son un puñado
         # de filas y esto corre una vez al arrancar.
         for job in missing:
+            values = {
+                "job_id": job.job_id,
+                "task_name": job.task_name,
+                "cron_expression": job.cron_expression,
+                "payload": job.payload,
+                "queue": job.queue,
+                "is_active": job.is_active,
+                "last_run_at": _as_utc(job.last_run_at) if job.last_run_at else None,
+                "description": job.description,
+            }
             result = await session.execute(
                 statement,
-                {
-                    "job_id": job.job_id,
-                    "task_name": job.task_name,
-                    "cron_expression": job.cron_expression,
-                    "payload": job.payload,
-                    "queue": job.queue,
-                    "is_active": job.is_active,
-                    "last_run_at": _as_utc(job.last_run_at) if job.last_run_at else None,
-                },
+                {key: value for key, value in values.items() if key in columns},
             )
             if result.rowcount != 0:
                 inserted += 1
@@ -271,6 +283,14 @@ async def create_cron_tables(
             sa.Column("queue", sa.String(64), nullable=False),
             sa.Column("is_active", sa.Boolean(), nullable=False),
             sa.Column("last_run_at", sa.DateTime(timezone=True), nullable=True),
+            sa.Column("description", sa.String(512), nullable=True),
+        )
+
+    Si la tabla es anterior a la columna `description`, la migración de actualización es::
+
+        op.add_column(
+            "hexcore_cron_jobs",
+            sa.Column("description", sa.String(512), nullable=True),
         )
     """
     from hexcore.infrastructure.repositories.orms.sqlalchemy.session import get_engine
@@ -290,6 +310,7 @@ def cron_job(
     payload: dict[str, t.Any] | None = None,
     queue: str | None = None,
     is_active: bool = True,
+    description: str | None = None,
 ) -> CronJobDefinition:
     """
     Construye un `CronJobDefinition` a partir de una función decorada con
@@ -299,11 +320,16 @@ def cron_job(
     escribir el nombre a mano es cómo se acaba con un cron que encola una tarea que ya
     se renombró, y el fallo aparece en el worker, no aquí.
 
+    `description` no la lee el scheduler: viaja a la tabla para que el panel que muestra
+    los crons pueda decir **qué hace** cada uno antes de que alguien lo desactive. Si no
+    se pasa, se usa la primera línea del docstring de la tarea, que suele ser justo eso.
+
     Uso::
 
         seed = [
             cron_job(cerrar_caja, "0 3 * * *"),
             cron_job(purgar_logs, "0 4 * * 0", payload={"days": 30}),
+            cron_job(facturar, "0 6 1 * *", description="Emite las facturas del mes."),
         ]
 
     Raises:
@@ -325,9 +351,29 @@ def cron_job(
         payload=payload or {},
         queue=queue or getattr(task, "__cqrs_queue__", "default"),
         is_active=is_active,
+        description=description or _first_docstring_line(task),
     )
 
 
+def _first_docstring_line(task: t.Callable[..., t.Any]) -> str | None:
+    """
+    La primera línea del docstring de la tarea, o `None`.
+
+    Que el default salga del docstring y no quede vacío es lo que hace que la columna
+    sirva sin trabajo extra: la descripción que el operador necesita casi siempre ya está
+    escrita justo encima de la función.
+    """
+    doc = getattr(task, "__doc__", None)
+    if not doc:
+        return None
+
+    for line in doc.strip().splitlines():
+        stripped = line.strip()
+        if stripped:
+            return stripped
+    return None
+
+
 def _default_session_scope() -> t.AsyncContextManager[AsyncSession]:
     from hexcore.infrastructure.uow.scopes import session_scope
 

{hexcore-6.0.0 → hexcore-6.0.2/hexcore.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 6.0.0
+Version: 6.0.2
 Summary: Núcleo reutilizable para proyectos Python con arquitectura hexagonal y event handling. Provee abstracciones, utilidades y contratos para DDD, eventos y desacoplamiento de infraestructura.
 Author-email: "David Latosefki (Indroic)" <indroic@outlook.com>
 License-Expression: MIT
@@ -385,6 +385,18 @@ admin = build_root_router(
 mount_routers(app, [admin, (public_router, {"prefix": "/v1"})])
 ```
 
+`children` acepta también una **secuencia**, y no es azúcar: un dict no puede tener dos claves
+`""`, así que un raíz con varios hijos que **ya traen su propio prefijo** —lo normal cuando cada
+feature declara sus rutas completas— no se puede expresar con un mapa.
+
+```python
+# usuarios_router y tickets_router ya son APIRouter(prefix="/usuarios") y (prefix="/tickets").
+api_v1 = build_root_router("/api/v1", [usuarios_router, tickets_router])
+
+# Se pueden mezclar: un router pelado equivale a ("", router).
+api_v1 = build_root_router("/api/v1", [usuarios_router, ("/reports", reports_router)])
+```
+
 ### Endpoints de listado y búsqueda
 
 ```python
@@ -706,6 +718,28 @@ otro origen (Mongo, Redis, un YAML), implementá `cqrs.ICronJobRepository`.
 `cron_job()` deriva el `task_name` de `__cqrs_task_name__`: escribirlo a mano es cómo se acaba
 con un cron que encola una tarea ya renombrada, y el fallo aparece en el worker.
 
+Cada job lleva además una `description` que viaja a la tabla. El scheduler no la usa: es lo que
+un panel le muestra al operador para que sepa **qué hace** un cron antes de desactivarlo — con
+sólo `task_name` y una expresión cron no se distingue apagar algo inofensivo de dejar de
+facturar. Por defecto sale de la primera línea del docstring de la tarea, que suele ser
+exactamente eso:
+
+```python
+@cqrs.background_task(queue="billing")
+async def emitir_facturas() -> None:
+    """Emite las facturas del mes y las envía por email."""
+    ...
+
+cqrs.cron_job(emitir_facturas, "0 6 1 * *")
+# description == "Emite las facturas del mes y las envía por email."
+
+cqrs.cron_job(cerrar_caja, "0 3 * * *", description="Cierra la caja del día.")
+```
+
+> Si tu tabla es anterior a esta columna, la migración es un `add_column` nullable —
+> `create_cron_tables()` lo trae escrito en su docstring. Un modelo propio que no la tenga no
+> rompe: el seed inserta lo que la tabla admita.
+
 **Cómo decide si toca ejecutar.** No compara contra el minuto actual, sino que busca si hubo
 alguna ocurrencia entre `last_run_at` y ahora:
 
@@ -884,18 +918,23 @@ estructura de migraciones con Alembic.
 
 | Serie | Estado | Qué significa |
 | :-- | :-- | :-- |
-| **5.x** | ✅ **Activa** | La única soportada. Recibe features y correcciones. |
+| **6.x** | ✅ **Activa** | La única soportada. Recibe features y correcciones. |
+| **5.x** | ⛔ **Deprecada** | Misma superficie de API que 6.x. Migrar es actualizar la versión. |
 | **4.x** | ⛔ **Deprecada** | Aplicación **parcial**: le faltan el fix del event loop de Celery, las fachadas y la documentación alineada. |
 | **3.x** | ⛔ **Deprecada** | Aplicación **parcial**: tiene las correcciones P0/P1 pero ninguna de las factories de FastAPI. |
 | **2.x** | ⛔ **Deprecada** | Contiene los bugs silenciosos corregidos en 5.x (ver abajo). |
 | **1.x** | ⛔ **Deprecada** | Sin soporte de ningún tipo. |
 
-**Todo lo anterior a 5.0 está deprecado. Migrá a 5.x.**
+**Todo lo anterior a 5.0 está deprecado. Migrá a 6.x.**
 
 3.0.0 y 4.0.0 existen sólo porque el trabajo se mergeó por fases y cada merge disparó un bump
 automático: **no son releases pensadas para usarse**, son cortes intermedios de la misma
 migración. 5.0.0 es la primera versión completa.
 
+6.0.0 es el mismo caso: la disparó un PR de documentación con un commit `feat!:`. No hay
+**ninguna** ruptura de API entre 5.x y 6.x — los alias anteriores a 5.0 siguen importables y
+siguen avisando.
+
 ### Por qué 2.x y anteriores no deberían estar en producción
 
 No es una cuestión de estilo: 2.x tiene defectos que no lanzan excepción y no aparecen en logs

{hexcore-6.0.0 → hexcore-6.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hexcore"
-version = "6.0.0"
+version = "6.0.2"
 authors = [
   { name="David Latosefki (Indroic)", email="indroic@outlook.com" },
 ]

{hexcore-6.0.0 → hexcore-6.0.2}/tests/test_api_middlewares_and_routing.py

@@ -282,6 +282,74 @@ def test_build_root_router_supports_empty_child_prefix():
         assert client.get("/root/items").json() == {"from": "direct"}
 
 
+def _self_prefixed_child(prefix: str, name: str) -> APIRouter:
+    """Un hijo que ya declara su propia ruta completa: no le queda sub-prefijo que poner."""
+    router = APIRouter(prefix=prefix)
+
+    @router.get("/items")
+    async def items() -> dict[str, str]:
+        return {"from": name}
+
+    return router
+
+
+def test_build_root_router_accepts_two_children_without_sub_prefix():
+    """
+    El caso que un `Mapping` **no puede expresar**: dos hijos que ya traen sus rutas
+    completas, o sea dos sub-prefijos vacíos. Un dict no admite dos claves `""`, así que
+    con la firma anterior este root router había que escribirse a mano.
+    """
+    root = build_root_router(
+        "/api/v1",
+        [
+            _self_prefixed_child("/usuarios", "usuarios"),
+            _self_prefixed_child("/tickets", "tickets"),
+        ],
+    )
+    app = FastAPI()
+    app.include_router(root)
+
+    with TestClient(app) as client:
+        assert client.get("/api/v1/usuarios/items").json() == {"from": "usuarios"}
+        assert client.get("/api/v1/tickets/items").json() == {"from": "tickets"}
+
+
+def test_build_root_router_sequence_mixes_bare_routers_and_pairs():
+    root = build_root_router(
+        "/api",
+        [_child("raiz"), ("/reports", _child("reports"))],
+    )
+    app = FastAPI()
+    app.include_router(root)
+
+    with TestClient(app) as client:
+        assert client.get("/api/items").json() == {"from": "raiz"}
+        assert client.get("/api/reports/items").json() == {"from": "reports"}
+
+
+def test_build_root_router_sequence_still_applies_dependencies_and_tags():
+    """Las dos formas de `children` tienen que ser equivalentes en todo lo demás."""
+    calls: list[str] = []
+
+    async def guard() -> None:
+        calls.append("checked")
+
+    root = build_root_router(
+        "/secure",
+        [("/a", _child("a"))],
+        dependencies=[Depends(guard)],
+        tags=["admin"],
+    )
+    app = FastAPI()
+    app.include_router(root)
+
+    with TestClient(app) as client:
+        assert client.get("/secure/a/items").status_code == 200
+
+    assert calls == ["checked"]
+    assert app.openapi()["paths"]["/secure/a/items"]["get"]["tags"] == ["admin"]
+
+
 def test_mount_routers_accepts_plain_routers_and_tuples():
     app = FastAPI()
     mount_routers(