tempest-fastapi-sdk 0.167.0__tar.gz → 0.167.1__tar.gz

{tempest_fastapi_sdk-0.167.0 → tempest_fastapi_sdk-0.167.1}/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to **tempest-fastapi-sdk** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.167.1] — 2026-07-26
+
+### Fixed
+
+- **`BaseController` now accepts services typed over a concrete update
+  schema.** `ServiceT`'s bound was written `BaseService[Any, Any]`, which is not
+  a partial application: PEP 696 fills the omitted `UpdateT` with its
+  `BaseSchema` default, and since that parameter is invariant the bound admitted
+  only services whose update schema was exactly `BaseSchema`. Every service
+  written the documented way — `BaseService[Repo, Resp, MyUpdateSchema]` — was
+  rejected by the type checker with `Type parameter "UpdateT@BaseService" is
+  invariant, but "MyUpdateSchema" is not the same as "BaseSchema"`, forcing a
+  `# type: ignore[type-var]` on the controller declaration. The bound is now
+  `BaseService[Any, Any, Any]`, which leaves the invariant parameter open while
+  keeping the `BaseSchema` constraint. Type-check only — runtime behavior is
+  unchanged, and the `# type: ignore[type-var]` workarounds can be dropped.
+- **The suite can now see this class of bug.** `mypy` runs over the package, not
+  over `tests/`, so `tests/controllers/test_base.py` already declared exactly
+  this service/controller pair and stayed green. New
+  `tests/controllers/test_generic_bounds.py` inspects `ServiceT.__bound__`
+  directly and runs `mypy --strict` over a downstream-shaped snippet, asserting
+  no `[type-var]` diagnostic.
+
+### Documentation
+
+- `docs/architecture.md` / `docs/architecture.en.md` — the controllers & services
+  section now shows the 3rd generic parameter on both layers and notes that the
+  pair requires 0.167.1+.
+
 ## [0.167.0] — 2026-07-26
 
 Permission guards: a decorator that runs plain `(user) -> user | None`

{tempest_fastapi_sdk-0.167.0 → tempest_fastapi_sdk-0.167.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.167.0
+Version: 0.167.1
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk

{tempest_fastapi_sdk-0.167.0 → tempest_fastapi_sdk-0.167.1}/docs/architecture.en.md

@@ -163,6 +163,31 @@ What you inherit by subclassing `BaseController[ServiceT, ResponseT]`:
 | `update(id, data)` | `service.update` | Same. |
 | `delete(id)` | `service.delete` | Same. |
 
+!!! tip "Typing the `update` payload end to end"
+    The 3rd generic parameter is the update schema, and it must be the **same** on both layers: a service declared as `BaseService[Repo, Resp, MyUpdateSchema]` fits `BaseController[MyService, Resp, MyUpdateSchema]`. Omit the 3rd parameter on either one and it falls back to the `BaseSchema` default, leaving `update`'s `data` loosely typed.
+
+    ```python
+    from tempest_fastapi_sdk import BaseController, BaseService
+
+    from src.db.repositories import CoinPackRepository
+    from src.schemas import CoinPackResponseSchema, CoinPackUpdateSchema
+
+
+    class CoinPackService(
+        BaseService[CoinPackRepository, CoinPackResponseSchema, CoinPackUpdateSchema]
+    ):
+        """Service typed over the concrete update schema."""
+
+
+    class CoinPackController(
+        BaseController[CoinPackService, CoinPackResponseSchema, CoinPackUpdateSchema]
+    ):
+        """Controller repeating the same update schema."""
+    ```
+
+    !!! warning "Requires 0.167.1+"
+        On earlier versions this pair failed type checking with `Type parameter "UpdateT@BaseService" is invariant, but "CoinPackUpdateSchema" is not the same as "BaseSchema"` — `ServiceT`'s bound pinned that invariant parameter to `BaseSchema`. Fixed in 0.167.1; nothing changes at runtime.
+
 When a use case needs domain rules, override the inherited method in the service. When a use case needs to coordinate more than one service, override the inherited method (or add a new one) in the controller. The router never grows — it only depends on the controller.
 
 ```python

{tempest_fastapi_sdk-0.167.0 → tempest_fastapi_sdk-0.167.1}/docs/architecture.md

@@ -163,6 +163,31 @@ O que você herda ao subclassear `BaseController[ServiceT, ResponseT]`:
 | `update(id, data)` | `service.update` | Igual. |
 | `delete(id)` | `service.delete` | Igual. |
 
+!!! tip "Tipando o payload de `update` ponta a ponta"
+    O 3º parâmetro genérico é o schema de update, e ele precisa ser o **mesmo** nas duas camadas: um service declarado como `BaseService[Repo, Resp, MeuUpdateSchema]` encaixa em `BaseController[MeuService, Resp, MeuUpdateSchema]`. Omitir o 3º parâmetro em qualquer uma delas cai no default `BaseSchema`, e o `data` de `update` chega sem tipo preciso.
+
+    ```python
+    from tempest_fastapi_sdk import BaseController, BaseService
+
+    from src.db.repositories import CoinPackRepository
+    from src.schemas import CoinPackResponseSchema, CoinPackUpdateSchema
+
+
+    class CoinPackService(
+        BaseService[CoinPackRepository, CoinPackResponseSchema, CoinPackUpdateSchema]
+    ):
+        """Service tipado sobre o schema de update concreto."""
+
+
+    class CoinPackController(
+        BaseController[CoinPackService, CoinPackResponseSchema, CoinPackUpdateSchema]
+    ):
+        """Controller que repete o mesmo schema de update."""
+    ```
+
+    !!! warning "Requer 0.167.1+"
+        Em versões anteriores esse par falhava no type check com `Type parameter "UpdateT@BaseService" is invariant, but "CoinPackUpdateSchema" is not the same as "BaseSchema"` — o bound de `ServiceT` deixava o parâmetro invariante fixado em `BaseSchema`. Corrigido em 0.167.1; nada muda em runtime.
+
 Quando um caso de uso precisa de regras de domínio, sobrescreva o método herdado no service. Quando um caso de uso precisa coordenar mais de um service, sobrescreva o método herdado (ou adicione um novo) no controller. O router nunca cresce — ele só depende do controller.
 
 ```python

{tempest_fastapi_sdk-0.167.0 → tempest_fastapi_sdk-0.167.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.167.0"
+version = "0.167.1"
 description = "Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects."
 readme = "README.md"
 requires-python = ">=3.11"

{tempest_fastapi_sdk-0.167.0 → tempest_fastapi_sdk-0.167.1}/tempest_fastapi_sdk/__init__.py

@@ -444,7 +444,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.167.0"
+__version__: str = "0.167.1"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",

{tempest_fastapi_sdk-0.167.0 → tempest_fastapi_sdk-0.167.1}/tempest_fastapi_sdk/controllers/base.py

@@ -10,7 +10,13 @@ from typing_extensions import TypeVar
 from tempest_fastapi_sdk.schemas.base import BaseSchema
 from tempest_fastapi_sdk.services.base import BaseService
 
-ServiceT = TypeVar("ServiceT", bound=BaseService[Any, Any])
+ServiceT = TypeVar("ServiceT", bound=BaseService[Any, Any, Any])
+"""Concrete service class the controller delegates to. The bound spells all
+three of :class:`BaseService`'s parameters as ``Any``: ``BaseService[Any, Any]``
+is not a partial application — PEP 696 fills the omitted ``UpdateT`` with its
+default (:class:`BaseSchema`), and because ``UpdateT`` is invariant that bound
+only admits services whose update schema is exactly ``BaseSchema``. Any service
+declared as ``BaseService[Repo, Resp, MyUpdateSchema]`` would be rejected."""
 ResponseT = TypeVar("ResponseT")
 UpdateT = TypeVar("UpdateT", bound=BaseSchema, default=BaseSchema)
 """Update-payload schema for :meth:`BaseController.update`. Defaults to

tempest_fastapi_sdk-0.167.1/tests/controllers/test_generic_bounds.py

@@ -0,0 +1,121 @@
+"""Static-typing regression tests for ``BaseController``'s generic bounds.
+
+The bug these guard against is invisible at runtime: ``BaseController`` and
+``BaseService`` both declare their ``UpdateT`` parameter with a PEP 696 default
+of ``BaseSchema``. A bound written as ``BaseService[Any, Any]`` is therefore not
+a partial application — the checker fills ``UpdateT`` with ``BaseSchema``, and
+since that parameter is invariant the bound admits only services whose update
+schema is exactly ``BaseSchema``. Every service declared the documented way,
+``BaseService[Repo, Resp, MyUpdateSchema]``, was rejected with
+``Type parameter "UpdateT@BaseService" is invariant``.
+
+Nothing fails at import time, and ``mypy`` only runs over the package (not over
+``tests/``), so the regular suite could not see it. These tests close both gaps:
+one inspects the bound directly, the other runs ``mypy`` over a snippet shaped
+like real downstream code.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any, get_args
+
+import pytest
+
+from tempest_fastapi_sdk.controllers.base import ServiceT
+
+DOWNSTREAM_SNIPPET = '''\
+"""Downstream service/controller pair with a concrete update schema."""
+
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from tempest_fastapi_sdk import (
+    BaseController,
+    BaseModel,
+    BaseRepository,
+    BaseResponseSchema,
+    BaseSchema,
+    BaseService,
+)
+
+
+class Widget(BaseModel):
+    __tablename__ = "widget_typing_snippet"
+
+    name: Mapped[str] = mapped_column(String(64), nullable=False)
+
+
+class WidgetResponseSchema(BaseResponseSchema):
+    name: str
+
+
+class WidgetUpdateSchema(BaseSchema):
+    name: str | None = None
+
+
+class WidgetRepository(BaseRepository[Widget]):
+    pass
+
+
+class WidgetService(
+    BaseService[WidgetRepository, WidgetResponseSchema, WidgetUpdateSchema]
+):
+    pass
+
+
+class WidgetController(
+    BaseController[WidgetService, WidgetResponseSchema, WidgetUpdateSchema]
+):
+    pass
+'''
+
+
+class TestServiceTBound:
+    def test_bound_spells_every_service_parameter(self) -> None:
+        """``ServiceT``'s bound must parameterize all three of ``BaseService``.
+
+        Written as ``BaseService[Any, Any]``, the omitted ``UpdateT`` resolves to
+        its ``BaseSchema`` default and pins the bound to that exact schema. The
+        third explicit ``Any`` is what keeps the invariant parameter open.
+        """
+        bound = ServiceT.__bound__
+        assert bound is not None
+        assert get_args(bound) == (Any, Any, Any)
+
+
+@pytest.mark.filterwarnings("ignore::DeprecationWarning")
+class TestDownstreamTypeChecks:
+    def test_controller_accepts_service_with_concrete_update_schema(
+        self, tmp_path: Path
+    ) -> None:
+        """``mypy`` must accept a controller typed over a concrete update schema.
+
+        Runs the checker over a snippet written the way the docs tell services to
+        be written, then asserts no ``type-var`` diagnostic surfaced. Only that
+        error code is asserted on, so unrelated diagnostics from the snippet's
+        environment cannot make this test flap.
+        """
+        mypy_api = pytest.importorskip(
+            "mypy.api", reason="mypy is a dev-group dependency"
+        )
+        module = tmp_path / "downstream_widget.py"
+        module.write_text(DOWNSTREAM_SNIPPET, encoding="utf-8")
+
+        stdout, stderr, _ = mypy_api.run(
+            [
+                str(module),
+                "--strict",
+                "--no-incremental",
+                "--no-error-summary",
+                "--hide-error-context",
+                "--cache-dir",
+                str(tmp_path / ".mypy_cache"),
+                "--python-executable",
+                sys.executable,
+            ]
+        )
+
+        type_var_errors = [line for line in stdout.splitlines() if "[type-var]" in line]
+        assert not type_var_errors, f"{type_var_errors}\n{stderr}"

{tempest_fastapi_sdk-0.167.0 → tempest_fastapi_sdk-0.167.1}/uv.lock

@@ -5576,7 +5576,7 @@ wheels = [
 
 [[package]]
 name = "tempest-fastapi-sdk"
-version = "0.167.0"
+version = "0.167.1"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },